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

Build the core from a source checkout, then set up the adapter:

python3 -m pip install -e 'adapters/python[numpy]'

SharedRegion

from zinc import SharedRegion

create

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

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
import struct
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.

wait_async

Wait without blocking the asyncio event loop:

if await region.wait_async(timeout_ms=1000):
    data = bytes(region.as_buffer()[:4])

The native wait runs in the default thread pool. It returns False on timeout and raises on other errors, like wait(). The worker retains the mapping until it finishes, even if you close the region or cancel the coroutine. Cancellation does not stop the native wait: it may consume a notification before its timeout. Choose a bounded timeout and avoid concurrent waits on the same handle.

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", 16384)
arr = writer.as_numpy(dtype=np.float32)
arr[:] = np.linspace(0, 1, arr.size, dtype=np.float32)
writer.notify()

# Reader process (separate terminal)
reader = SharedRegion.open("tensor-data")
arr = reader.as_numpy(dtype=np.float32)
if reader.wait(1000):
    print(arr[:5])

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

Typing

Type stubs and a py.typed marker ship with the package. as_buffer() returns a memoryview; as_numpy() returns a NumPy array, with uint8 as the default dtype. Install the numpy extra for NumPy’s type definitions. Factory methods and context managers preserve SharedRegion subclasses.

FFI details

The adapter loads libzinc_core.{so,dylib} from the repository’s target/release directory at import time. Its CFFI declarations match the generated C ABI. Build the core before importing it.

try_wait() consumes a pending notification without blocking. close() prevents new operations; exported memoryviews and NumPy arrays keep their mapping alive until released.