marshalling

Name

marshalling — marshalling — pack an object into an ordered stream so it can cross a boundary

Synopsis

marshal [--in-order] [--no-partial] OBJECT > wire
unmarshal < wire > OBJECT
wire := marshal(object); object := unmarshal(wire)

Description

marshal takes an OBJECT — a thing that exists only as a cluster of fields sitting near each other in one address space — and lays it out as a single ordered stream fit to travel across a process, machine, or protocol boundary. The inverse, unmarshal, receives that stream on the far side and rebuilds the object from it. A pointer is meaningless once it leaves the room it was born in; marshalling is the act of turning proximity into sequence so the far side has something to read.

Order is the whole contract. The receiver reads the stream field by field in the sequence the sender wrote it, and there is no seeking back. A stream that arrives shuffled, truncated, or missing its length prefix does not degrade gracefully — it is refused at the gate. marshal writes nothing until every field is in its slot; the bridge does not accept partial data.

marshalling is not encryption, not compression, and not validation, though it is frequently mistaken for all three by callers who wanted those instead.

Options

--in-order

Write fields in canonical sequence. This is the only order. Accepted for the reassurance of the caller, who suspected there was another.

--no-partial

Refuse to emit a stream that is missing a field. Default. Half a parade is not a shorter parade.

--deep

Follow the object's pointers and marshal what they point at, too. Continues until it meets itself coming the other way.

--zero-copy

Promise not to allocate. Allocates. The promise is marshalled separately.

--schema=FILE

Carry the shape alongside the bytes so the far side can disagree with precision instead of by accident.

--trust-the-wire

Skip the length prefix. The wire has never once deserved this.

Exit Status

0

object marshalled; the rake left the yard in order

1

field out of sequence; stream refused at the gate (PILEUP)

2

cyclic reference; --deep is still walking and will not return

75

unmarshalled on the far side into a struct that no longer has that field

History

"From Old High German marahscalc, literally horse-servant (marah, horse; scalc, servant) — the man who kept the stables, an office that rose with cavalry until a field marshal commanded armies. The sense of arranging things into order gave English the marshalling yard, where locomotives shunt scattered wagons into ordered trains. Computing borrowed the term for serialization in the era of remote procedure calls; Sun RPC's XDR and later Microsoft COM/DCOM made marshalling arguments across a boundary a daily chore, and gRPC with Protocol Buffers carries the schema-checked version everywhere today."

Bugs

--deep on a self-referential object recurses until the stack is a monument to the attempt. Documented as depth-first.

Marshalling and serialization are the same operation with two priesthoods that do not attend each other's conferences.

A field added on one side and not the other unmarshals into silence. Silence exits 0. This is by design and no one is happy about it.

See Also

thunk(3), backpressure(3), idempotent(3). The living exhibit demonstrates the word in motion:

▸ operate marshalling

Author

"Maintained by The Marshal, formerly of the stables, who stands at the mouth of the bridge with a clipboard and waves each car forward only when it is the next one. He has seen your object arrive out of order before. He is not surprised, only patient."