On this page:
serializable?
serialize
deserialize
serialized=?
deserialize-module-guard
serializable-struct
define-serializable-struct
serializable-struct/ versions
define-serializable-struct/ versions
make-deserialize-info
prop: serializable
make-serialize-info

12.11 Serialization

The bindings documented in this section are provided by the racket/serialize library, not racket/base or racket.

(serializable? v)  boolean?
  v : any/c
Returns #t if v appears to be serializable, without checking the content of compound values, and #f otherwise. See serialize for an enumeration of serializable values.

(serialize v)  any
  v : serializable?
Returns a value that encapsulates the value v. This value includes only readable values, so it can be written to a stream with write, later read from a stream using read, and then converted to a value like the original using deserialize. Serialization followed by deserialization produces a value with the same graph structure and mutability as the original value, but the serialized value is a plain tree (i.e., no sharing).

The following kinds of values are serializable:

Serialization succeeds for a compound value, such as a pair, only if all content of the value is serializable. If a value given to serialize is not completely serializable, the exn:fail:contract exception is raised.

If v contains a cycle (i.e., a collection of objects that are all reachable from each other), then v can be serialized only if the cycle includes a mutable value, where a prefab structure counts as mutable only if all of its fields are mutable.

The serialize and deserialize functions currently do not handle certain cyclic values that read and write can handle, such as '#0=(#0#).

See deserialize for information on the format of serialized data.

(deserialize v)  any
  v : any/c
Given a value v that was produced by serialize, produces a value like the one given to serialize, including the same graph structure and mutability.

A serialized representation v is a list of six or seven elements:

The result of deserialize shares no mutable values with the argument to deserialize.

If a value provided to serialize is a simple tree (i.e., no sharing), then the fourth and fifth elements in the serialized representation will be empty.

(serialized=? v1 v2)  boolean?
  v1 : any/c
  v2 : any/c
Returns #t if v1 and v2 represent the same serialization information.

More precisely, it returns the same value that (equal? (deserialize v1) (deserialize v2)) would return if

A parameter whose value is called by deserialize before dynamically loading a module via dynamic-require. The two arguments provided to the procedure are the same as the arguments to be passed to dynamic-require. The procedure can raise an exception to disallow the dynamic-require.

(serializable-struct id maybe-super (field ...)
                     struct-option ...)
Like struct, but instances of the structure type are serializable with serialize. This form is allowed only at the top level or in a module’s top level (so that deserialization information can be found later).

Serialization only supports cycles involving the created structure type when all fields are mutable (or when the cycle can be broken through some other mutable value).

In addition to the bindings generated by struct, serializable-struct binds deserialize-info:id-v0 to deserialization information. Furthermore, in a module context, it automatically provides this binding.

The serializable-struct form enables the construction of structure instances from places where id is not accessible, since deserialization must construct instances. Furthermore, serializable-struct provides limited access to field mutation, but only for instances generated through the deserialization information bound to deserialize-info:id-v0. See make-deserialize-info for more information.

The -v0 suffix on the deserialization enables future versioning on the structure type through serializable-struct/version.

When a supertype is supplied in maybe-super is supplied, compile-time information bound to the supertype identifier must include all of the supertype’s field accessors. If any field mutator is missing, the structure type will be treated as immutable for the purposes of marshaling (so cycles involving only instances of the structure type cannot be handled by the deserializer).

Examples:

  > (serializable-struct point (x y))
  > (point-x (deserialize (serialize (point 1 2))))

  1

(define-serializable-struct id-maybe-super (field ...)
                             struct-option ...)
Like serializable-struct, but with the supertype syntax and default constructor name of define-struct.

(serializable-struct/versions id-maybe-super vers (field ...)
                              (other-version-clause ...)
                              struct-option ...)
 
other-version-clause = 
(other-vers make-proc-expr
            cycle-make-proc-expr)
Like serializable-struct, but the generated deserializer binding is deserialize-info:id-vvers. In addition, deserialize-info:id-vother-vers is bound for each other-vers. The vers and each other-vers must be a literal, exact, nonnegative integer.

Each make-proc-expr should produce a procedure, and the procedure should accept as many argument as fields in the corresponding version of the structure type, and it produce an instance of id. Each graph-make-proc-expr should produce a procedure of no arguments; this procedure should return two values: an instance x of id (typically with #f for all fields) and a procedure that accepts another instance of id and copies its field values into x.

Examples:

  > (serializable-struct point (x y) #:mutable #:transparent)
  > (define ps (serialize (point 1 2)))
  > (deserialize ps)

  (point 1 2)

  > (define x (point 1 10))
  > (set-point-x! x x)
  > (define xs (serialize x))
  > (deserialize xs)

  #0=(point #0# 10)

  > (serializable-struct/versions point 1 (x y z)
       ([0
         ; Constructor for simple v0 instances:
         (lambda (x y) (point x y 0))
         ; Constructor for v0 instance in a cycle:
         (lambda ()
           (let ([p0 (point #f #f 0)])
             (values
               p0
               (lambda (p)
                 (set-point-x! p0 (point-x p))
                 (set-point-y! p0 (point-y p))))))])
       #:mutable #:transparent)
  > (deserialize (serialize (point 4 5 6)))

  (point 4 5 6)

  > (deserialize ps)

  (point 1 2 0)

  > (deserialize xs)

  #0=(point #0# 10 0)

(define-serializable-struct/versions id-maybe-super vers (field ...)
                                     (other-version-clause ...)
                                     struct-option ...)
Like serializable-struct/versions, but with the supertype syntax and default constructor name of define-struct. }

(make-deserialize-info make cycle-make)  any
  make : procedure?
  cycle-make : (-> (values any/c procedure?))
Produces a deserialization information record to be used by deserialize. This information is normally tied to a particular structure because the structure has a prop:serializable property value that points to a top-level variable or module-exported variable that is bound to deserialization information.

The make procedure should accept as many argument as the structure’s serializer put into a vector; normally, this is the number of fields in the structure. It should return an instance of the structure.

The cycle-make procedure should accept no arguments, and it should return two values: a structure instance x (with dummy field values) and an update procedure. The update procedure takes another structure instance generated by the make, and it transfers the field values of this instance into x.

prop:serializable : property?
This property identifies structures and structure types that are serializable. The property value should be constructed with make-serialize-info.

(make-serialize-info to-vector    
  deserialize-id    
  can-cycle?    
  dir)  any
  to-vector : (any/c . -> . vector?)
  deserialize-id : 
(or identifier?
    symbol?
    (cons/c symbol?
            module-path-index?))
  can-cycle? : any/c
  dir : path-string?
Produces a value to be associated with a structure type through the prop:serializable property. This value is used by serialize.

The to-vector procedure should accept a structure instance and produce a vector for the instance’s content.

The deserialize-id value indicates a binding for deserialize information, to either a module export or a top-level definition. It must be one of the following:

See make-deserialize-info and deserialize for more information.

The can-cycle? argument should be false if instances should not be serialized in such a way that deserialization requires creating a structure instance with dummy field values and then updating the instance later.

The dir argument should be a directory path that is used to resolve a module reference for the binding of deserialize-id. This directory path is used as a last resort when deserialize-id indicates a module that was loaded through a relative path with respect to the top level. Usually, it should be (or (current-load-relative-directory) (current-directory)).