Python Adapter

Use Zinc from Python with numpy integration

The Python adapter uses cffi (not ctypes) for FFI bindings. It wraps numpy’s np.frombuffer for zero-copy array views.

Installation

pip install zinc-shm

Or from source:

cd adapters/python
pip install -e .

SharedRegion

from zinc import SharedRegion

create

region = SharedRegion.create("my-data", 4096)

Creates a new region. Raises OSError if the name already exists, the name is invalid, or the capacity is not page-aligned.

open

region = SharedRegion.open("my-data")

Opens an existing region. Raises OSError if the region does not exist or the header is corrupted.

as_buffer

Returns a memoryview backed directly by the shared mmap. No copying occurs.

buf = region.as_buffer()
# buf is a memoryview, writable and sliceable
buf[:4] = struct.pack('<I', 42)

as_numpy

Returns a numpy ndarray backed directly by the shared memory. No copying occurs. Requires numpy to be installed.

import numpy as np

arr = region.as_numpy(dtype=np.float32)
arr[0] = 42.0  # writes directly to shared memory

Without a dtype argument, it defaults to np.uint8.

raw = region.as_numpy()  # shape: (capacity,), dtype: uint8

notify

region.notify()

wait

success = region.wait(timeout_ms=1000)

Returns True if notified, False if timed out.

close

region.close()

The region is also closed when the SharedRegion object is garbage collected or used as a context manager:

with SharedRegion.open("my-data") as region:
    buf = region.as_buffer()
    # region is automatically closed after the block

Example: numpy integration

from zinc import SharedRegion
import numpy as np
import struct

# Writer process
writer = SharedRegion.create("tensor-data", 8192)
arr = writer.as_numpy(dtype=np.float32)
arr[:] = np.linspace(0, 1, 2048, dtype=np.float32)
writer.notify()

# Reader process (separate terminal)
reader = SharedRegion.open("tensor-data")
arr = reader.as_numpy(dtype=np.float32)
print(arr[:5])  # [0. 0.00048828 0.00097656 0.00146484 0.00195312]

The as_numpy call returns a view, not a copy. Writing to the array from either process modifies the same physical memory.

FFI details

The adapter loads libzinc_core.{so,dylib,dll} at import time. It reads zinc.h from include/ relative to the Python package to define the FFI signatures. If the header is missing, it falls back to a hardcoded CDEF.

The library path is resolved relative to the Python package location. If the library is not found, copy it to a standard library path or set LD_LIBRARY_PATH / DYLD_LIBRARY_PATH.