API Reference

Top-level package

Public package surface for pyshmem.

SharedMemory

class pyshmem.SharedMemory(*, name, shape, dtype, size, gpu_device, gpu_enabled, cpu_mirror, data_shm, metadata_shm, owner, gpu_handle_shm=None, gpu_tensor=None, torch_dtype=None)

A named shared-memory stream.

Instances are created via create() or attached to via open(). The object exposes shape and dtype metadata, lock management, read and write operations, and lifecycle helpers such as close() and unlink().

For GPU-backed streams, gpu_device identifies the attached CUDA device. When cpu_mirror is False, CPU-only handles may still inspect metadata and take locks, but they cannot read the payload without reopening with a CUDA attachment.

Parameters:

  • name (str)

  • shape (tuple[int, ...])

  • dtype (np.dtype)

  • size (int)

  • gpu_device (str | None)

  • gpu_enabled (bool)

  • cpu_mirror (bool)

  • data_shm (shared_memory.SharedMemory)

  • metadata_shm (shared_memory.SharedMemory)

  • owner (bool)

  • gpu_handle_shm (shared_memory.SharedMemory | None)

property count: int

Return the number of completed writes recorded on the stream.

property write_time: float

Return the UNIX timestamp of the most recent completed write.

property write_sequence: int

Return the internal write sequence counter for the stream.

acquire(*, timeout=None, poll_interval=0.001)

Acquire the cross-process write lock for the stream.

The lock is re-entrant within the current thread. When timeout is provided, a TimeoutError is raised if the lock cannot be acquired before the deadline.

Parameters:
Return type:

None

release()

Release one level of the current thread’s re-entrant lock state.

Return type:

None

locked(*, timeout=None, poll_interval=0.001)

Return a context manager for the stream lock.

Parameters:
close()

Close this local handle without destroying the underlying stream.

Return type:

None

Destroy the underlying named shared-memory stream.

Return type:

None

delete()

Alias for unlink().

Return type:

None

clear()

Reset the current payload to zeros and record a new write.

Return type:

None

write(value)

Write a full payload into the stream.

value must match the configured shape. CPU-backed streams accept values understood by numpy.asarray(); GPU-backed streams also accept CUDA tensors on the configured device.

Parameters:

value (Any)

Return type:

None

read(*, safe=True, poll_interval=1e-06)

Read the current payload from the stream.

When safe is True, the method returns a consistent snapshot of the latest completed write. When safe is False, the caller must already own the stream lock via locked() or acquire().

Parameters:
read_new(*, timeout=None, safe=True, poll_interval=1e-05)

Block until a new write arrives, then return its payload.

Parameters:

Factory functions

pyshmem.create(name, *, shape, dtype=<class 'numpy.float32'>, size=None, gpu_device=None, cpu_mirror=None)

Create a new named shared-memory stream.

Parameters:

  • name (str) – User-visible stream name.

  • shape (Sequence[int]) – Payload shape.

  • dtype (Any) – NumPy dtype stored in the stream.

  • size (int | None) – Optional explicit size check. When provided, it must exactly match the size implied by shape and dtype.

  • gpu_device (str | int | None) – Optional CUDA device identifier such as "cuda:0".

  • cpu_mirror (bool | None) – Controls whether GPU-backed streams also maintain a CPU mirror. Defaults to True for CPU streams and False for GPU streams.

Return type:

SharedMemory

pyshmem.open(name, *, gpu_device=None)

Attach to an existing named shared-memory stream.

Parameters:
Return type:

SharedMemory

Parameters:

name (str)

Return type:

None

pyshmem.gpu_available()

Return True when CUDA-backed PyTorch streams are available.

Return type:

bool