---

8.4 Persistent vats

When a vat is spawned, it can be spawned as a persistent vat with a given persistence environment and set of roots. The vat also has a storage provider associated with it. Vats can be persisted either on each churn (when the vat reaches quiescence), or manually. If a vat is configured to persist on churns, just the objects which have changed (using become) will be persisted.

Procedure: spawn-persistent-vat persistent-env spawn-roots-thunk store [#:persist-on] [#:vat-constructor] [#:name] [#:log?] ¶

[#:log-capacity] [#:persistence-registry] [#:version] [#:upgrade]

Create and return a reference to a new vat configured with persistence.

• persistence-env: The persistence environment containing all objects within the persistence graph (See Persistence environments)
• spawn-roots-thunk: A thunk which is invoked if no persisted state of the vat exists. The lambda should spawn and return the roots of the object graph to be persisted.
• store: The store that persistence data will be read and written to See Persistence stores.
• persist-on: If 'churn will persist on churns, otherwise in a manual persistence mode (default: 'churn).
• vat-constructor: The constructor used to create the vat, defaults to spawn-fibrous-vat.
• name: Name of the vat. Note that this is not the name it is bound to in the current namespace.
• log?: If #t, log vat events; otherwise, do not.
• log-capacity: Number of events to be retained in the log. Defaults to 256.
• persistence-registry: The refr to a shared ^persistence-registry object which, if provided, enables persisting and rehydrating objects from other local vats.
• version: Usually a number (but not limited to), to indicate the version for the roots of the graph. When the roots of the graph change, this version should change and an upgrade path in the upgrade procedure should be provided. This defaults to 0 when no version is specified.
• upgrade: This is a procedure which is run if the version of the roots in the persistence store does not match the version in version. The procedure takes in the previous version as its first arguments followed by all the roots that were read from the store. The procedure should return two values, 1) the new version number and 2) a list of the new roots themselves. The new root version should match that of version.

  The migrations macro is generally what would be expected to be used for the upgrade procedure

(define-actor (^counter bcom value)
  (lambda ()
    (bcom (^counter bcom (+ 1 value)) value)))

(define persistence-env
  (make-persistence-env
   `((((counter) ^counter) ,^counter))))

(define-values (vat my-counter)
  (spawn-persistent-vat
   persistence-env
   (lambda ()
     (spawn ^counter 0))
   (make-memory-store)))

The ^persistence-registry actor is designed to be spawned anew each time the program starts (i.e. is not part of the persistence graph) and is shared amongst several persistent vats which want to persist/rehydrate objects across vats.

Unlike local near refrs which are promises during rehydration, but are swapped to local refrs after rehydration is complete, Far refrs remain promises and should resolve after both vats are setup and have registered themselves with the ^persistence-registry object.

Here’s an example of two vats, the cell on b-vat holds a reference to an object on a-vat

;; Spawn the persistence registry in its own vat without persistence enabled.
(define persistence-registry
  (with-vat (spawn-vat)
    (spawn ^persistence-registry)))

;; Spawn the initial a-vat with an a-cell object
(define a-vat-store (make-memory-store))
(define-values (a-vat a-cell)
  (spawn-persistent-vat
   cell-env
   (lambda () (spawn ^cell))
   a-vat-store
   #:persistence-registry persistence-registry))

;; Spawn a b-vat with a b-cell object, that will reference the far refr a-cell.
(define b-vat-store (make-memory-store))
(define-values (b-vat b-cell)
  (spawn-persistent-vat
   cell-env
   (lambda () (spawn ^cell a-cell))
   b-vat-store
   #:persistence-registry persistence-registry))

;; Let go of our persistence registry reference so it can be garbage collected.
(set! persistence-registry #f)

The persistence registry builds a map of strong references to all the references within a vat. This ensures references only held by far vats are kept around until all the vats are spawned. A consequence of this design is that if the reference to the persistence registry is kept around, the initial graph of actors in vats can never be garbage collected. Thus, it’s important to let go of the reference to the ^persistence-registry actor once all the vats which need it have been spawned.