---

8.3 Operations on actormaps

Using the persistence support on an actormap allows for taking a portrait of its current state, rehydrating that state into an actormap and updating the behavior of an object through an upgrade mechanism.

Procedure: actormap-take-portrait am persistence-env . roots ¶

Takes a portrait of the objects within the actormap starting with the supplied roots.

This takes an actormap, am which contains the objects and an persistence-env which describes some additional information about all the objects within the graph that’s needed to support persistence. The final arguments are all the roots within the graph.

The portrait is a map where each object within the portrait that is represented by an integer which maps to its respective portrait data (in a serializable form), this integer is known as a slot. When an object contains a reference to another object, that object is referred to by its slot.

The procedure returns two values to its continuation, those are:

1. the self portrait data 2. the root slots: these are in order the integers of the root objects.

Procedure: actormap-restore! am persistence-env portrait-data roots ¶

This restores the objects in the actormap am from the portrait data portrait-data using the object specifications data stored in persistence-env with the given roots.

Due to the way rehydration of depictions works each object is represented as a vow which will be resolved when returned.

This procedure returns to the continuation all the references to the restored objects for the given roots. This is so that the number of values returned is equal to the number of roots provided.

Procedure: actormap-replace-behavior! am persistence-env ¶

Replace actors in actormap am with new behavior from persistence-env

It’s often desirable, especially when developing a system, to update or otherwise change the behavior of objects which already exist in an actormap. This can easily be done by using the persistence system in Goblins. Each object can describe itself through its self portrait and then be rehydrated into its new behavior allowing seamless upgrades.

This procedure will first calculate all of the objects that have an updated constructor within persistence-env. It will then take a portrait all those objects, then using that portrait data, rehydrate them with the new behavior keeping the object references the same.

It’s important to note that in order to be able to replace the behavior the objects must be been defined as redefinable, this is commonly done by using the define-hackable macro provided with Goblins. Non-redefinable actors will not have their behavior replaced as they will appear as different objects within the persistence-env.

Procedure: actormap-replace-behavior am persistence-env ¶

Functional version of actormap-replace-behavior!

This works the same as ‘actormap-replace-behavior!’ but it returns a transactormap which the user can choose whether or not to commit.

Procedure: actormap-save-to-store! am persistence-env store . roots ¶

Take and save the portrait for the object graph starting with roots as the root objects in the graph. Store the portrait data within the store, which is a See Persistence stores.

The persistence-env should be a persistence environment with the object specifications of all the objects within the object graph being persisted.

Procedure: actormap-restore-from-store! am persistence-env store ¶

Restores the object graph that has previously been stored in the store into the actormap am. All objects that appear in the graph must be defined in the persistence environment persistence-env. Returns the roots as values.

Procedure: local-refr->persistable-object-identifier local-refr ¶

Convert a local object reference, local-refr to a persistable object identifier.

A persistable object identifier is a value which can be used when comparing two objects together with equal?. This is particularly useful when using object refrs as keys within hash tables. They are persistable by Goblins’ persistence system and available immediately upon restoration, without requiring any coordination with other objects or vats, as is the case when persisting references to objects on other vats.

This identifier is not a refr and cannot be used to send messages to the object. It is solely designed as a stand-in to compare two object refrs together to check if they are the same object or not. Persistable object identifiers also cannot be converted back to refrs.

This procedure will always convert a local-refr to a persistable object identifier value which will always be equal? to another persistable object identifier produced from the same refr, even between restores.

Note: This only works for refrs spawned in vats, not for refrs from working directly with actormaps.

(use-modules (goblins)
             (goblins core)
             (goblins actor-lib cell)
             (goblins persistence-store memory))

(define store (make-memory-store))
(define-values (vat my-cell)
  (spawn-persistent-vat
   cell-env
   (lambda ()
     (spawn ^cell))
   store))
(define my-cell-identifier
  (local-refr->persistable-object-identifier my-cell))

;; Now make a new actormap, and restore a new cell refr from the portrait data
(define-values (vat* my-cell*)
  (spawn-persistent-vat
   cell-env
   (lambda ()
     (error "should never get here as it's reading from the store"))
   store))
;; Now create an identifier for the my-cell* that we just restored.
(define my-cell-identifier*
  (local-refr->persistable-object-identifier my-cell*))

;;; they're `equal?': (equal? #t)
(pk 'equal? (equal? my-cell-identifier my-cell-identifier*))