unienv_interface.remote.wire¶
Safe wire format: one JSON document plus raw binary attachments. No pickle.
A frame is::
u32 buffer count | u32 JSON length | u64 length per buffer | UTF-8 JSON | buffers...
(all little-endian). Plain JSON carries None, bools, ints, strings, lists and
string-keyed dicts. Everything else is a JSON object tagged with the reserved key
"__t":
========== =========================================================== ======================
tag fields decodes to
========== =========================================================== ======================
tuple v: list of values tuple
dict v: list of [key, value] pairs dict (any hashable
keys, or one using
"__t" as a key)
float v: "nan", "inf" or "-inf" non-finite float
bytes b: buffer index bytes
nd d: dtype string, s: shape, b: buffer index; array of the receiver's
or c: codec, o: codec options, b: index list backend and device
space v: space_to_json document Space
graph v: dict of the GraphInstance fields GraphInstance
========== =========================================================== ======================
NumPy scalars travel as 0-d arrays; torch / JAX arrays are sent as NumPy arrays.
Anything else raises TypeError: no arbitrary objects are ever reconstructed.
Decoding validates every frame (sizes, buffer references, dtype allowlist,
shape x itemsize == length, nesting depth) and raises WireError otherwise.
Bases: ValueError
A frame is malformed or violates the wire format's limits.
SpaceJSON(document: Dict[str, Any])
An already serialized space (space_to_json output); encodes as a space tag.
CodecArray(array: ndarray, codec: str, options: Dict[str, Any])
An array leaf the encoder compresses with a registered :class:ArrayCodec.
register_codec(name: str, codec: ArrayCodec) -> None
Register an array codec under name (needed on both peers).
encode(value: Any, *, copy: bool = False, max_size: Optional[int] = None) -> Tuple[List[Any], int]
Encode value into frame parts [header, json, *buffers] and the frame size.
Large arrays are attached zero-copy unless copy is set, so the parts must be
sent before those arrays change. Raises TypeError for unsupported values.
read_header(head: bytes, max_size: int) -> Tuple[int, int]
Validate the fixed 8-byte header; return (buffer count, JSON length).
split(data: Any, max_size: int = DEFAULT_MAX_FRAME_SIZE) -> Tuple[memoryview, List[memoryview]]
Split one contiguous (preferably writable) frame into its JSON and buffers.
parse(document: Any) -> Any
Parse the JSON part of a frame (strict JSON; tags are not resolved yet).
restore(node: Any, buffers: Sequence[Any], backend: Optional[ComputeBackend] = None, device: Optional[object] = None) -> Any
Resolve the tags of a parsed frame; arrays become backend arrays on device.
Every buffer must be referenced exactly once. Arrays share memory with the (writable) buffers when no backend conversion is needed.
loads(data: Any, backend: Optional[ComputeBackend] = None, device: Optional[object] = None, max_size: int = DEFAULT_MAX_FRAME_SIZE) -> Any
Decode one contiguous frame (copied once so that arrays are writable).