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 function to rehydrate the object upon rehydration.

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:

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

(define* (^greeter _bcom our-name #:optional (init-number-of-times #f))
  (define number-of-times
    (or init-number-of-times (spawn ^cell 0)))
  (lambda (their-name)
    ($ number-of-times (+ ($ number-of-times) 1))
    (format #f "Hello ~a, my name is ~a (called: ~a)"
            their-name our-name ($ 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
  (make-persistence-env
   (list (list '((greeter) ^greeter) ^greeter))
   #:extends 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.

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))