ezmsg.tools.shmem.shmem_mirror#

It is possible to move data from ezmsg to non-ezmsg processes using shared memory. This module contains the non-ezmsg half of that communication. The ezmsg half is found in .shmem. The same shmem_name must be passed to both the ShMemCircBuff and the EZShmMirror objects!

Besides the sample data, the mirror exposes the source AxisArray’s static metadata – its coordinate axes (e.g. a ch axis naming each channel), axis units, and attrs – via the axes, attrs, and dims properties. These are plain dicts rather than ezmsg objects; see .aux_meta for why. They read None until the writer publishes, and update in place if it ever republishes, so poll them (or register_metadata_callback) rather than reading once.

Classes

class EZShmMirror(shmem_name=None)[source]#

Bases: object

An object that has a local (in-client-process) representation of the shared memory from another process’ .shmem.ShMemCircBuff Unit.

There are 2 pieces of shared memory: the metadata and the data buffer. The ezmsg node is responsible for creating both pieces. Here we only connect to them. We cannot know if the shared memory exists before we try to connect to it, so we must try the connection – sometimes repeatedly while handling connection errors.

Parameters:: shmem_name (str | None)

__init__(shmem_name=None)[source]#

Parameters:: shmem_name (str | None)

disconnect()[source]#

property meta: ShmemArrMeta | None#

property buffer: NDArray | None#

property write_index: int | None#

property connected: bool#

property axes: Dict[str, dict] | None#

The source AxisArray’s axes as plain dicts, or None if unavailable.

Keyed by axis name. Each value is {"kind": "linear", "unit", "gain", "offset"} or {"kind": "coord", "unit", "dims", "data"} – see aux_meta for why these are dicts rather than ezmsg axis objects.

The buffered axis (whatever the sink was configured to buffer along, normally "time") appears here with only its static descriptors: its position along the stream lives in the ring’s write index, not here.

None means the writer has not published yet – poll again. A writer this build cannot read raises ShmemVersionError on connect rather than showing up as None here.

property attrs: dict | None#: The source AxisArray’s attrs, minus any non-transportable values.

property dims: List[str] | None#

The source AxisArray’s dimension names, in the sender’s order.

Note the buffer itself is rolled so the buffered axis comes first; this is the message’s original ordering.

property stream_dim: str | None#

Which dimension the source declared it accumulates along.

Distinct from the buffered axis: an operator can override that, and a producer on ezmsg < 3.10 declares nothing, in which case this is None.

property buffered_axis: str | None#: Which dimension the ring is a history along.

property metadata_available: bool#: Whether a decoded metadata blob is currently held.

register_metadata_callback(callback)[source]#

Call callback whenever a new metadata generation is decoded.

Separate from register_change_callback(), which fires when the data buffer is rebuilt. The two are independent: channel labels can arrive without the buffer changing, and vice versa.

Parameters:: callback (Callable)
Return type:: None

unregister_metadata_callback()[source]#

Return type:: None

register_change_callback(callback)[source]#

Parameters:: callback (Callable)
Return type:: None

unregister_change_callback()[source]#

Return type:: None

connect(name)[source]#

Parameters:: name (str)
Return type:: None

auto_view(n=None)[source]#

Parameters:: n (int | None)
Return type:: Tuple[NDArray, bool]