spdl.pipeline.ArenaReaderProtocol

class ArenaReaderProtocol

Reader endpoint: the first step in the parent process.

Backends implement this protocol to surface offloaded binaries to _restore(). Methods are called from the parent process’s consumer thread and need not be thread-safe. A process-region channel may reverse the sender/receiver process roles.

Added in version 0.7.0.

Changed in version 0.9.0: This extension contract is publicly available from spdl.pipeline.

Methods

end_unit(span[, anchors])	Signal that one unit has been fully read.
read_binary(offset, nbytes)	Return the bytes for one offloaded binary.
reset()	Prepare the reader for a new iteration.

Attributes

zero_copy

Whether read_binary() hands out live, reusable views into shared memory (segment pool) rather than private copies (ring).

end_unit(span: int, anchors: list[object] | None = None) → None

Signal that one unit has been fully read.

Parameters:

• span – The unit’s span as returned by ArenaWriterProtocol.commit_unit(). Lets the backend release the entire region in bulk regardless of how the binaries are laid out.

• anchors – Opaque lifetime owners supplied by the serializer for views restored from this unit, for example an array base owner. This metadata is for custom readers; it does not imply CUDA pinning. Builtins ignore the list because native exports independently retain their backing. Defaults to None; an omitted, second-positional or anchors= argument is valid. SPDL continues passing an actual list positionally to custom readers whose existing implementation requires one.

Logical end does not invalidate surviving exports or establish physical reuse: the backend must preserve their storage and ordering constraints. This method also accounts for an unread unit discarded without exporting bytes; the serializer supplies an empty list in that case.

Returns:

None. Called from a finally block in _restore(), so accounting stays correct even if unpickling raised.

Changed in version 0.9.0: Renamed pinned to optional anchors with a None default. Positional calls remain valid; replace the old pinned= keyword with anchors=.

read_binary(offset: int, nbytes: int) → memoryview[bytes]

Return the bytes for one offloaded binary.

Parameters:

• offset – Physical byte offset in the arena (as returned by ArenaWriterProtocol.write_binary()).

• nbytes – Number of bytes of the payload.

Returns:

A memoryview of exactly nbytes bytes. With zero_copy=True (segment pool) the view aliases shared memory and its actual exporter must retain the backing for every surviving storage export (see end_unit()). With zero_copy=False (ring), the bytes have already been copied out into an independent owning buffer. Slices, casts, NumPy base chains, Torch storage and incomplete transfer sources must retain the correct backing; releasing the original Python wrapper alone does not prove physical storage is reusable.

reset() → None

Prepare the reader for a new iteration.

Called by the parent once per iteration, after the worker has signaled ITERATION_STARTED and before the first item is consumed. Zero-copy backends must preserve the accounting for views that remain alive from previous iterations.

Returns:

None.

property zero_copy: bool

Whether read_binary() hands out live, reusable views into shared memory (segment pool) rather than private copies (ring). Handlers use this flag to choose between a zero-copy view and an owning / copied-out restore.