global-buffer 1.0.0__tar.gz

global_buffer-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Izzet Sezer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

global_buffer-1.0.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include src/global_buffer/_core.pyx
+include src/global_buffer/_core.c
+include src/global_buffer/gb_atomics.h
+include LICENSE README.md

global_buffer-1.0.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: global_buffer
+Version: 1.0.0
+Summary: Cross-platform cross-process shared-memory ring buffer: zero-copy numpy arrays + pydantic messages, 0-CPU blocking callbacks.
+Author: Izzet Sezer
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/sezer-muhammed/GlobalBuffer
+Project-URL: Repository, https://github.com/sezer-muhammed/GlobalBuffer
+Project-URL: Documentation, https://github.com/sezer-muhammed/GlobalBuffer/tree/main/docs
+Project-URL: Changelog, https://github.com/sezer-muhammed/GlobalBuffer/blob/main/CHANGELOG.md
+Project-URL: Bug Tracker, https://github.com/sezer-muhammed/GlobalBuffer/issues
+Keywords: shared-memory,ipc,ring-buffer,numpy,pydantic,zero-copy
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: System :: Hardware
+Classifier: Topic :: System :: Networking
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: msgspec>=0.18
+Requires-Dist: pydantic>=2
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: Cython>=3.0; extra == "dev"
+Dynamic: license-file
+
+# GlobalBuffer
+
+Cross-platform, cross-process **named shared-memory buffer** for Python.
+
+`import global_buffer as gb`
+
+A writer publishes samples by name; any process on the same host attaches by name
+and reads — either the newest sample or every sample in order, by blocking call or
+background callback. Built for streams that mix **high frequency** (e.g. 200 Hz
+numeric arrays) and **low frequency** (e.g. 1 Hz structured status messages)
+without burning CPU on either end.
+
+It fills the gap between `multiprocessing.shared_memory` (too low-level),
+`UltraDict` (dated, pickle-based), and iceoryx2/eCAL (heavy native installs):
+a pip-installable, pydantic-native, callback-driven buffer with a clean API and a
+lock-free Cython hot path.
+
+## Status
+
+**v1.0.0.** Core is stable and covered by 70 tests (including a cross-process
+no-torn-reads stress test), verified on macOS / CPython 3.14. Linux, Windows and
+aarch64 (Jetson) are supported and wheels are configured, with broad CI
+verification on those platforms in progress. See [`CHANGELOG.md`](CHANGELOG.md)
+for known limitations.
+
+## Features
+
+- **Two stream kinds, one API**
+  - **Array streams** — fixed dtype + shape numpy data, written and read **zero-copy**.
+  - **Message streams** — `pydantic` models on the public API, `msgspec` (msgpack) on the wire (~10× faster than pickle).
+- **Last-value or in-order reads** — `latest()` jumps to the newest sample;
+  `next()` consumes every sample in order and reports `overruns` if a reader falls behind.
+- **Lock-free, tear-free** — single-writer / multi-reader ring with a spare slot
+  (`capacity + 1`) plus a per-slot seqlock implemented with C11 atomics. No torn reads even at high rate.
+- **Near-0-CPU wakeups** — readers block on an adaptive poll of the shared commit
+  counter; idle readers cost roughly one atomic load every couple of milliseconds.
+- **Cross-platform** — Linux, macOS, Windows; ships as compiled wheels.
+
+## Install
+
+```bash
+pip install global_buffer
+```
+
+Wheels are published for CPython 3.9–3.13 on manylinux x86_64 / aarch64,
+macOS (x86_64 + arm64) and Windows amd64. A source build needs a C11 compiler.
+
+## Quickstart
+
+### Array stream (200 Hz, zero-copy)
+
+```python
+import global_buffer as gb
+import numpy as np
+
+# writer / owner
+csi = gb.create(name="csi", schema=gb.ArraySpec(dtype="complex64", shape=(64, 4)),
+                capacity=8)
+
+with csi.reserve() as slot:      # slot is an ndarray view directly into shm
+    slot[:] = frame              # fill in place — no copy
+# or: csi.write(frame)           # single-memcpy convenience form
+
+# reader (any other process)
+r = gb.attach("csi")             # schema discovered from the segment
+frame = r.latest()               # newest committed sample
+r.on_data(lambda sample, seq: process(sample), mode="latest")  # bg thread
+```
+
+### Message stream (1 Hz, pydantic)
+
+```python
+import pydantic, global_buffer as gb
+
+class Status(pydantic.BaseModel):
+    gain: float
+    cam_on: bool
+
+status = gb.create(name="status", schema=Status, capacity=4, max_bytes=512)
+status.write(Status(gain=1.2, cam_on=True))
+
+rs = gb.attach("status", model=Status)   # schema mismatch -> raises on attach
+msg = rs.next(timeout=1.0)               # -> validated Status instance
+```
+
+### OO consumer
+
+```python
+class CsiConsumer(gb.Consumer):
+    def callback(self):                  # framework sets self.data / self.seq
+        self.processed = heavy_process(self.data)
+
+ob = CsiConsumer.attach("csi", mode="latest")
+ob.start()
+...
+ob.stop()
+```
+
+## Semantics
+
+- `capacity` is the number of logical slots; the core allocates `capacity + 1` so
+  the writer never overwrites the slot a reader could currently be reading.
+- A reader created with `attach()` starts at the newest sample present at attach time.
+- `latest()` returns `None` on an empty buffer. `next(timeout=...)` raises
+  `gb.Empty` on timeout; without a timeout it blocks.
+- `next()` accumulates `reader.overruns` when the writer laps the reader by more
+  than `capacity` samples (the reader then jumps to the oldest still-available sample).
+- `reader.writer_alive` reflects a heartbeat the writer stamps on every write
+  (a writer silent for >2 s reads as not alive).
+
+## Lifecycle
+
+```python
+buf.close()    # detach this handle (segment stays alive)
+buf.unlink()   # owner removes the segment
+gb.unlink(name)  # remove a segment by name (e.g. clean up after a crash)
+```
+
+GlobalBuffer manages segment lifetime explicitly (it opts out of the
+multiprocessing `resource_tracker` where supported, Python 3.13+), so a reader
+exiting never unlinks the owner's segment.
+
+## Platform support
+
+| OS | Segment | Notification |
+|---|---|---|
+| Linux | `multiprocessing.shared_memory` (POSIX shm) | adaptive poll on commit counter |
+| macOS | `multiprocessing.shared_memory` (POSIX shm) | adaptive poll on commit counter |
+| Windows | `multiprocessing.shared_memory` (mem-mapped) | adaptive poll on commit counter |
+
+> **Verification status.** Behaviour is verified on macOS today; the Linux/Windows
+> CI matrix and aarch64 wheels are configured and will be exercised before those
+> platforms are declared production-verified.
+>
+> **Note on notifications.** The current release uses adaptive polling of the
+> shared commit counter for wakeups — fully portable, reliable on all three OSes,
+> and near-0 CPU when idle (the poll interval backs off to ~2 ms). A true 0-CPU
+> kernel-blocking backend (Linux `eventfd` / process-shared pthread condvar,
+> Windows named semaphore) fits behind the same interface and is planned once it
+> can be verified per-OS in CI. POSIX named semaphores were evaluated and dropped:
+> they behave unreliably on macOS.
+
+## Build from source
+
+```bash
+python -m pip install -U pip setuptools wheel Cython numpy msgspec pydantic
+python setup.py build_ext --inplace
+PYTHONPATH=src python -c "import global_buffer as gb; print(gb.__version__)"
+```
+
+## Run the tests
+
+```bash
+PYTHONPATH=src python -m pytest tests -v                 # full suite
+PYTHONPATH=src python -m pytest tests -m "not crossproc_slow"   # skip the long stress test
+```
+
+Or in Docker:
+
+```bash
+docker build -t globalbuffer . && docker run --rm globalbuffer
+docker compose up   # two-process writer/reader demo
+```
+
+## Jetson / aarch64
+
+Wheels are built for `manylinux aarch64`. Atomics and process spawn behaviour can
+differ from x86; run the suite on the target device once as a smoke test.
+
+## Design
+
+Full documentation is in [`docs/`](docs/index.md); design rationale and the
+on-disk segment layout are in [`docs/design.md`](docs/design.md).
+
+## License
+
+MIT © 2026 Izzet Sezer

global_buffer-1.0.0/README.md

@@ -0,0 +1,177 @@
+# GlobalBuffer
+
+Cross-platform, cross-process **named shared-memory buffer** for Python.
+
+`import global_buffer as gb`
+
+A writer publishes samples by name; any process on the same host attaches by name
+and reads — either the newest sample or every sample in order, by blocking call or
+background callback. Built for streams that mix **high frequency** (e.g. 200 Hz
+numeric arrays) and **low frequency** (e.g. 1 Hz structured status messages)
+without burning CPU on either end.
+
+It fills the gap between `multiprocessing.shared_memory` (too low-level),
+`UltraDict` (dated, pickle-based), and iceoryx2/eCAL (heavy native installs):
+a pip-installable, pydantic-native, callback-driven buffer with a clean API and a
+lock-free Cython hot path.
+
+## Status
+
+**v1.0.0.** Core is stable and covered by 70 tests (including a cross-process
+no-torn-reads stress test), verified on macOS / CPython 3.14. Linux, Windows and
+aarch64 (Jetson) are supported and wheels are configured, with broad CI
+verification on those platforms in progress. See [`CHANGELOG.md`](CHANGELOG.md)
+for known limitations.
+
+## Features
+
+- **Two stream kinds, one API**
+  - **Array streams** — fixed dtype + shape numpy data, written and read **zero-copy**.
+  - **Message streams** — `pydantic` models on the public API, `msgspec` (msgpack) on the wire (~10× faster than pickle).
+- **Last-value or in-order reads** — `latest()` jumps to the newest sample;
+  `next()` consumes every sample in order and reports `overruns` if a reader falls behind.
+- **Lock-free, tear-free** — single-writer / multi-reader ring with a spare slot
+  (`capacity + 1`) plus a per-slot seqlock implemented with C11 atomics. No torn reads even at high rate.
+- **Near-0-CPU wakeups** — readers block on an adaptive poll of the shared commit
+  counter; idle readers cost roughly one atomic load every couple of milliseconds.
+- **Cross-platform** — Linux, macOS, Windows; ships as compiled wheels.
+
+## Install
+
+```bash
+pip install global_buffer
+```
+
+Wheels are published for CPython 3.9–3.13 on manylinux x86_64 / aarch64,
+macOS (x86_64 + arm64) and Windows amd64. A source build needs a C11 compiler.
+
+## Quickstart
+
+### Array stream (200 Hz, zero-copy)
+
+```python
+import global_buffer as gb
+import numpy as np
+
+# writer / owner
+csi = gb.create(name="csi", schema=gb.ArraySpec(dtype="complex64", shape=(64, 4)),
+                capacity=8)
+
+with csi.reserve() as slot:      # slot is an ndarray view directly into shm
+    slot[:] = frame              # fill in place — no copy
+# or: csi.write(frame)           # single-memcpy convenience form
+
+# reader (any other process)
+r = gb.attach("csi")             # schema discovered from the segment
+frame = r.latest()               # newest committed sample
+r.on_data(lambda sample, seq: process(sample), mode="latest")  # bg thread
+```
+
+### Message stream (1 Hz, pydantic)
+
+```python
+import pydantic, global_buffer as gb
+
+class Status(pydantic.BaseModel):
+    gain: float
+    cam_on: bool
+
+status = gb.create(name="status", schema=Status, capacity=4, max_bytes=512)
+status.write(Status(gain=1.2, cam_on=True))
+
+rs = gb.attach("status", model=Status)   # schema mismatch -> raises on attach
+msg = rs.next(timeout=1.0)               # -> validated Status instance
+```
+
+### OO consumer
+
+```python
+class CsiConsumer(gb.Consumer):
+    def callback(self):                  # framework sets self.data / self.seq
+        self.processed = heavy_process(self.data)
+
+ob = CsiConsumer.attach("csi", mode="latest")
+ob.start()
+...
+ob.stop()
+```
+
+## Semantics
+
+- `capacity` is the number of logical slots; the core allocates `capacity + 1` so
+  the writer never overwrites the slot a reader could currently be reading.
+- A reader created with `attach()` starts at the newest sample present at attach time.
+- `latest()` returns `None` on an empty buffer. `next(timeout=...)` raises
+  `gb.Empty` on timeout; without a timeout it blocks.
+- `next()` accumulates `reader.overruns` when the writer laps the reader by more
+  than `capacity` samples (the reader then jumps to the oldest still-available sample).
+- `reader.writer_alive` reflects a heartbeat the writer stamps on every write
+  (a writer silent for >2 s reads as not alive).
+
+## Lifecycle
+
+```python
+buf.close()    # detach this handle (segment stays alive)
+buf.unlink()   # owner removes the segment
+gb.unlink(name)  # remove a segment by name (e.g. clean up after a crash)
+```
+
+GlobalBuffer manages segment lifetime explicitly (it opts out of the
+multiprocessing `resource_tracker` where supported, Python 3.13+), so a reader
+exiting never unlinks the owner's segment.
+
+## Platform support
+
+| OS | Segment | Notification |
+|---|---|---|
+| Linux | `multiprocessing.shared_memory` (POSIX shm) | adaptive poll on commit counter |
+| macOS | `multiprocessing.shared_memory` (POSIX shm) | adaptive poll on commit counter |
+| Windows | `multiprocessing.shared_memory` (mem-mapped) | adaptive poll on commit counter |
+
+> **Verification status.** Behaviour is verified on macOS today; the Linux/Windows
+> CI matrix and aarch64 wheels are configured and will be exercised before those
+> platforms are declared production-verified.
+>
+> **Note on notifications.** The current release uses adaptive polling of the
+> shared commit counter for wakeups — fully portable, reliable on all three OSes,
+> and near-0 CPU when idle (the poll interval backs off to ~2 ms). A true 0-CPU
+> kernel-blocking backend (Linux `eventfd` / process-shared pthread condvar,
+> Windows named semaphore) fits behind the same interface and is planned once it
+> can be verified per-OS in CI. POSIX named semaphores were evaluated and dropped:
+> they behave unreliably on macOS.
+
+## Build from source
+
+```bash
+python -m pip install -U pip setuptools wheel Cython numpy msgspec pydantic
+python setup.py build_ext --inplace
+PYTHONPATH=src python -c "import global_buffer as gb; print(gb.__version__)"
+```
+
+## Run the tests
+
+```bash
+PYTHONPATH=src python -m pytest tests -v                 # full suite
+PYTHONPATH=src python -m pytest tests -m "not crossproc_slow"   # skip the long stress test
+```
+
+Or in Docker:
+
+```bash
+docker build -t globalbuffer . && docker run --rm globalbuffer
+docker compose up   # two-process writer/reader demo
+```
+
+## Jetson / aarch64
+
+Wheels are built for `manylinux aarch64`. Atomics and process spawn behaviour can
+differ from x86; run the suite on the target device once as a smoke test.
+
+## Design
+
+Full documentation is in [`docs/`](docs/index.md); design rationale and the
+on-disk segment layout are in [`docs/design.md`](docs/design.md).
+
+## License
+
+MIT © 2026 Izzet Sezer

global_buffer-1.0.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=64", "wheel", "Cython>=3.0", "numpy>=1.23"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "global_buffer"
+dynamic = ["version"]
+description = "Cross-platform cross-process shared-memory ring buffer: zero-copy numpy arrays + pydantic messages, 0-CPU blocking callbacks."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Izzet Sezer" }]
+keywords = ["shared-memory", "ipc", "ring-buffer", "numpy", "pydantic", "zero-copy"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Operating System :: OS Independent",
+  "Topic :: System :: Hardware",
+  "Topic :: System :: Networking",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+]
+dependencies = ["numpy>=1.23", "msgspec>=0.18", "pydantic>=2"]
+
+[project.urls]
+Homepage = "https://github.com/sezer-muhammed/GlobalBuffer"
+Repository = "https://github.com/sezer-muhammed/GlobalBuffer"
+Documentation = "https://github.com/sezer-muhammed/GlobalBuffer/tree/main/docs"
+Changelog = "https://github.com/sezer-muhammed/GlobalBuffer/blob/main/CHANGELOG.md"
+"Bug Tracker" = "https://github.com/sezer-muhammed/GlobalBuffer/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "Cython>=3.0"]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+packages = ["global_buffer"]
+
+[tool.setuptools.dynamic]
+version = { attr = "global_buffer._version.__version__" }
+
+[tool.cibuildwheel]
+build = "cp39-* cp310-* cp311-* cp312-* cp313-*"
+skip = "*-musllinux_i686 *_i686 pp*"
+test-requires = ["pytest", "numpy", "msgspec", "pydantic"]
+test-command = "pytest {project}/tests -m 'not crossproc_slow'"
+archs = ["auto64"]
+
+[tool.cibuildwheel.linux]
+archs = ["x86_64", "aarch64"]
+
+[tool.pytest.ini_options]
+markers = ["crossproc_slow: long cross-process stress tests"]

global_buffer-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

global_buffer-1.0.0/setup.py

@@ -0,0 +1,19 @@
+import sys
+
+import numpy
+from setuptools import Extension, setup
+from Cython.Build import cythonize
+
+if sys.platform == "win32":
+    extra = ["/std:c11", "/O2"]
+else:
+    extra = ["-std=c11", "-O3"]
+
+ext = Extension(
+    "global_buffer._core",
+    sources=["src/global_buffer/_core.pyx"],
+    include_dirs=[numpy.get_include(), "src/global_buffer"],
+    extra_compile_args=extra,
+)
+
+setup(ext_modules=cythonize([ext], language_level=3))

global_buffer-1.0.0/src/global_buffer/__init__.py

@@ -0,0 +1,46 @@
+"""GlobalBuffer: cross-platform, cross-process shared-memory ring buffer.
+
+Zero-copy numpy array streams and pydantic message streams, last-value or
+in-order reads, and background callbacks. See the README for the full API.
+"""
+from ._version import __version__
+from .buffer import GlobalBuffer, open_shm, shm_name
+from .consumer import Consumer
+from .exceptions import (BufferClosed, BufferExists, BufferNotFound, Empty,
+                         GlobalBufferError, SchemaMismatch)
+from .reader import Reader
+from .spec import ArraySpec
+
+
+def create(name, schema, capacity, max_bytes=None):
+    """Create and own a named buffer (writer). ``schema`` is an
+    :class:`ArraySpec` or a ``pydantic.BaseModel`` subclass."""
+    return GlobalBuffer(name, schema, capacity, max_bytes=max_bytes)
+
+
+def attach(name, model=None, poll_min=None, poll_max=None):
+    """Attach to an existing named buffer (reader). For message buffers, pass
+    ``model=`` to get validated instances and a schema-compatibility check.
+
+    ``poll_max`` raises the wakeup poll-backoff cap (seconds); a larger value
+    lowers idle CPU when running many readers, at the cost of up to that much
+    extra wake latency (default ~2 ms). ``poll_min`` sets the busy floor."""
+    return Reader(name, model=model, poll_min=poll_min, poll_max=poll_max)
+
+
+def unlink(name):
+    """Remove a named segment by name (e.g. to clean up after a crash)."""
+    try:
+        shm = open_shm(shm_name(name))
+    except FileNotFoundError:
+        return
+    shm.close()
+    shm.unlink()
+
+
+__all__ = [
+    "__version__", "ArraySpec", "GlobalBuffer", "Reader", "Consumer",
+    "create", "attach", "unlink",
+    "GlobalBufferError", "Empty", "SchemaMismatch", "BufferClosed",
+    "BufferExists", "BufferNotFound",
+]