spdl.pipeline.ArenaProtocol

class ArenaProtocol

An arena object passed to iterate_in_subprocess via arena.

Owns the shared-memory segment and produces the writer / reader endpoints used on each side of the inter-process boundary. The arena is created and owned by the parent, passed to the worker through process spawn arguments, and torn down by the parent after the worker is confirmed dead. Custom objects conform structurally; importing or subclassing this protocol is not required. Ordinary iteration owns arena teardown; process-region channels borrow caller-owned arenas.

Added in version 0.7.0.

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

Methods

close()	Release this process's handle to the shared-memory segment.
open_reader()	Open the reader endpoint for the parent side.
open_writer()	Open the writer endpoint for the worker side.
shutdown_arena()	Request shutdown and wake producers blocked on arena capacity.
unlink()	Destroy the OS-level shared-memory segment.

close() → None

Release this process’s handle to the shared-memory segment.

Called by the parent during teardown after the worker has been confirmed dead. Does not destroy the OS-level segment; see unlink() for that. Safe to call once per arena. Backends that provide terminal cancellation through close may also use it before worker join, but final physical retirement must wait for worker and native-export/transfer quiescence. Live or uncertain storage must remain retained rather than being unmapped or overwritten.

Returns:

None.

open_reader() → ArenaReaderProtocol

Open the reader endpoint for the parent side.

Should be called once per arena, in the parent process, before the first item is consumed. The returned reader is the first step in the parent pipeline. A process-region channel opens it in its receiving process; consumer-local pinning is the backend’s policy.

Returns:

A fresh ArenaReaderProtocol bound to this arena.

open_writer() → ArenaWriterProtocol

Open the writer endpoint for the worker side.

Should be called once per arena, in the worker process, before the first item is offloaded. The returned writer is the last step in the worker pipeline. A process-region channel opens it in its sending process, which may instead be the parent.

Returns:

A fresh ArenaWriterProtocol bound to this arena.

shutdown_arena() → None

Request shutdown and wake producers blocked on arena capacity.

Called before joining the sending process, so a producer waiting inside ArenaWriterProtocol.begin_unit() or ArenaWriterProtocol.write_binary() can observe shutdown and leave its wait. IPC callers use this operation through the protocol, not a backend-specific private hook.

This operation is repeatable and must not release mappings, unregister live storage or unlink shared names. Existing byte exports and pending transfers retain their storage. A shutdown request is not proof that the worker has exited or that storage is safe to retire; complete close() and unlink() only after safe teardown.

Returns:

None.

Changed in version 0.9.0: Custom arena backends must expose the pre-join shutdown operation explicitly as part of this structural contract.

unlink() → None

Destroy the OS-level shared-memory segment.

Called by the owning parent during teardown after safe close() retirement. If close fails with uncertain storage or worker state, retain ownership and names until safe retry is possible; unlink is not a substitute for proving quiescence. Must be called once per arena by its owner and only after every process that mapped the segment has released its handle. Removing names must not invalidate surviving mapped aliases.

Returns:

None.