8.5 Persistence Environments

All persistence aware objects need be defined in what’s known as an persistence environment. These environments specify a set of information which must exist to be able to take portrait and/or rehydrate objects. This is a unique name for the object, the constructor, and if different from the constructor, a procedure to rehydrate the object.

When taking portraits of objects or rehydrating them every single object must be present in the given persistence env, this would obviously be quite tedious as object graphs get larger and contain lots of different objects. This is made easier by the persistence environments being able to extend from (or inherit from) other persistence environments. Lets take the idea of our greeter from earlier:

(use-modules (goblins)
             (goblins actor-lib cell))

(define-actor (^greeter* _bcom our-name number-of-times)
  (lambda (their-name)
    (let ((times ($ number-of-times)))
      ($ number-of-times (+ 1 times))
      (format #f "Hello ~a, my name is ~a (called ~a)"
              their-name our-name times))))

(define* (^greeter bcom our-name #:optional [number-of-times 0])
  (spawn ^greeter* our-name (spawn ^cell number-of-times)))

The persistence environment here would need to specify two objects, the ^greeter* object and the ^cell object. This is made a little more complicated by the fact that we didn’t define ^cell, we’re using that from a library, Goblins’ actor-lib library.

This is where persistence environment inheritance helps, we can specify the objects we’ve defined (i.e. ^greeter*) and specify the persistence environment that actor-lib’s cell module provides for us:

(define greeter-env
  (persistence-env-compose
   (namespace-env (greeter)
     ^greeter*)

   ;; Specify the cell environment from (goblins actor-lib cell)
   cell-env))

If we later wanted to define another persistence environment which uses our greeter, we could define a new persistence environment which extends from greeter-env.

The reason we’re including ^greeter*, rather than ^greeter in the persistence environment, is that when a constructor returns a refr, rather than a procedure. Goblins throws away the outer object and just uses the returned refr. As greeter is acting as a helper and returning a refr to greeter*, it is that object which you’re getting when you spawn ^greeter and thus tha object you need to put in the persistence environment.

Procedure: make-persistence-env bindings #:extends ¶

This creates a persistence environment based on a set of object specifications and a list of other persistence environments to extend from.

This takes two arguments, each being a list. The first is bindings which is a list of all the object specifications specified as a list:

(OBJECT-NAME OBJECT-CONSTRUCTOR [OBJECT_REHYDRATOR])

The second keyword argument, extends is either a single persistent environment to extend from, or a list of several persistent environments to extent from.

Important: Care should be taken to prevent cycles within persistence environments.

This procedure returns a single value, a persistence environment.

Procedure: persistence-env-compose envs … ¶

Composes a new persistence environment which contains all of the provided envs.

Syntax: namespace-env nameaspace objects … ¶

Makes a new persistence environment with all of the objects provided in objects namespaced within namespace.

The following are equivalent:

(define cell-env
  (make-persistence-env
   `((((goblins actor-lib cell) ^cell) ,^cell)
     (((goblins actor-lib cell) ^ro-cell) ,^ro-cell)
     (((goblins actor-lib cell) ^wo-cell) ,^wo-cell))))

(define cell-env
  (namespace-env
   (goblins actor-lib cell)
   ^cell ^ro-cell ^wo-cell))