13.10 Fast-Load Serialization (original) (raw)
13.10 Fast-Load Serialization🔗ℹ
(fasl->s-exp in [#:datum-intern? datum-intern? #:external-lifts external-lifts #:skip-prefix? skip-prefix?]) → any/c in : (or/c input-port? bytes?) datum-intern? : any/c = #t external-lifts : vector? = '#() skip-prefix? : any/c = #f
The s-exp->fasl function serializes v to a byte string, printing it directly to out if out is an output port or returning the byte string otherwise. Thefasl->s-exp function decodes a value from a byte string (supplied either directly or as an input port) that was encoded withs-exp->fasl.
The v argument must be a value that could be quoted as a literal—that is, a value without syntax objects for which(compile `',v) would work and be readable after write—or it can include correlated objects mixed with those values. The byte string produced bys-exp->fasl does not use the same format as compiled code, however.
If a value within v is not valid as a quoted literal, and if handle-fail is not #f, thenhandle-fail is called on the nested value, and the result ofhandle-fail is written in that value’s place. Thehandle-fail procedure might raise an exception instead of returning a replacement value. If handle-fail is #f, then the exn:fail:contract exception is raised when an invalid value is encountered.
If external-lift? is not #f, then it receives each value v-sub encountered in v bys-exp->fasl. If the result of external-lift? onv-sub is true, then v-sub is not encoded in the result, and it instead treated as externally lifted. A deserializing fasl->s-exp receives a external-liftsvector that has one value for each externally lifted value, in the same order as passed to external-lift? on serialization.
Like (compile `',v), s-exp->fasl does not preserve graph structure, support cycles, or handle non-prefabstructures. Compose s-exp->fasl with serialize to preserve graph structure, handle cyclic data, and encode serializable structures. The s-exp->fasl and fasl->s-expfunctions consult current-write-relative-directory andcurrent-load-relative-directory(falling back to current-directory), respectively, in the same way as bytecode saving and loading to store paths in relative form, and they similarly allow and convert constrained srclocvalues (see Printing Compiled Code).
Unless keep-mutable? is provided as true tos-exp->fasl, then mutable values in v are replaced by immutable values when the result is decoded byfasl->s-exp. Unless datum-intern? is provided as#f, then any immutable value produced by fasl->s-expis filtered by datum-intern-literal. The defaults make the composition of s-exp->fasl and fasl->s-exp behave like the composition of write and read.
If skip-prefix? is not #f, then a prefix that identifies the stream as a serialization is not written bys-exp->fasl or read by fasl->s-exp. Omitting a prefix can save a small amount of space, which can useful when serializing small values, but it gives up a sanity check on thefasl->s-exp that is often useful.
The byte-string encoding produced by s-exp->fasl is independent of the Racket version, except as future Racket versions introduce extensions that are not currently recognized. In particular, the result of s-exp->fasl will be valid as input to any future version of fasl->s-exp (as long as theskip-prefix? arguments are consistent).
Examples:
> (define fasl (s-exp->fasl (list #("speed") 'racer #\!))) > fasl #"racket/fasl:\0\24\34\3 \1\23\5speed\16\5racer\r!" > (fasl->s-exp fasl) '(#("speed") racer #\!)
Changed in version 6.90.0.21 of package base: Made s-exp->fasl format version-independent and added the #:keep-mutable?and #:datum-intern? arguments.
Changed in version 7.3.0.7: Added support for correlated objects.
Changed in version 7.5.0.3: Added the #:handle-fail argument.
Changed in version 7.5.0.9: Added the #:external-lift? and #:external-lifts arguments.
Changed in version 8.9.0.4: Added support for fxvectors and flvectors.