Skip to main content

Module clone

cljrs_value

Module clone 

Source
Expand description

Structured-clone boundary between isolates (Phase B2).

serialize converts a Value to a Send + Sync intermediate form; deserialize allocates a fresh copy into the current isolate’s GC heap. Non-shareable values (mutable state, closures, native resources) produce a CloneError so the compiler — not a runtime panic — enforces the boundary.

The round-trip is:

isolate A: Value → serialize → SerializedValue   (Send) ──► thread boundary
isolate B:                      SerializedValue → deserialize → Value

§What is shareable

  • All scalar immediates: Nil, Bool, Long, Double, Char, Uuid
  • Heap-allocated data values: Str, BigInt, BigDecimal, Ratio, Pattern (source only), Symbol, Keyword
  • All persistent collections: List, Vector, Map, Set, Queue, Cons
  • Primitive and object arrays (snapshot of current contents)
  • TypeInstance records (fields cloned recursively)
  • Error (message + data + cause chain, Thrown value cloned recursively)
  • Lazy sequences: realized first; the realized value is then cloned
  • WithMeta, Reduced wrappers (inner value + meta cloned recursively)

§Cross-isolate shared references (Phase B3)

  • SharedAtom, ByteBlob — Arc-cloned, not deep-copied; both isolates share the same underlying cell/buffer.
  • Var — the var’s root binding crosses through its shared cell (Arc<ArcSwap<Option<SharedValue>>>), so a var def’d in one isolate is observable by value from another, keyword/symbol identity preserved. A var whose current root holds a non-promotable value (a closure / native resource) is not shareable and returns CloneError — such vars are explicitly isolate-local (option (b) of the ADR).

§What is not shareable (returns CloneError)

  • Atom, Volatile, Promise, Future, Agent (mutable state)
  • Fn, BoundFn, Macro, NativeFunction, ProtocolFn, MultiFn (closures capture isolate-local GcPtrs)
  • Namespace, Protocol (global singletons managed elsewhere)
  • Resource, NativeObject (isolate-bound OS handles / native objects)
  • TransientMap, TransientSet, TransientVector (isolate-local transients)
  • Delay whose thunk has not yet been forced (thunk is isolate-local)
  • Matcher (regex engine state tied to one execution context)

Structs§

SerializedError
Serialized form of crate::error::ExceptionInfo.

Enums§

CloneError
Reason a value cannot cross an isolate boundary.
SerializedErrorKind
Mirrors ValueError with Value replaced by SerializedValue.
SerializedValue
Send + Sync intermediate form produced by serialize and consumed by deserialize. All heap data is owned (no GcPtr), so it is safe to move across thread boundaries.

Functions§

deserialize
Deserialize a wire form into a fresh Value allocated in the current isolate’s GC heap. Infallible: all non-shareable values are rejected at serialize time, so nothing in SerializedValue requires runtime checks.
serialize
Serialize a Value into a Send + Sync wire form suitable for crossing an isolate boundary. Returns CloneError for non-shareable values.