slick-stream-buffer-multiplexer-py 0.1.0__py3-none-any.whl

slick_stream_buffer_multiplexer_py-0.1.0.dist-info/METADATA

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: slick-stream-buffer-multiplexer-py
+Version: 0.1.0
+Summary: Lock-free MPMC byte stream multiplexer with C++ interoperability via shared memory
+Home-page: https://github.com/SlickQuant/slick-stream-buffer-multiplexer-py
+Author: Slick Quant
+Author-email: Slick Quant <slickquant@slickquant.com>
+License: MIT
+Project-URL: Homepage, https://github.com/SlickQuant/slick-stream-buffer-multiplexer-py
+Project-URL: Documentation, https://github.com/SlickQuant/slick-stream-buffer-multiplexer-py#readme
+Project-URL: Repository, https://github.com/SlickQuant/slick-stream-buffer-multiplexer-py
+Project-URL: Bug Tracker, https://github.com/SlickQuant/slick-stream-buffer-multiplexer-py/issues
+Keywords: stream-buffer,multiplexer,lock-free,atomic,shared-memory,ipc,multiprocessing,mpmc
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: slick-queue-py>=1.2.0
+Requires-Dist: slick-stream-buffer-py>=0.1.0
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# slick-stream-buffer-multiplexer-py
+
+A Python implementation of [slick-stream-buffer-multiplexer](https://github.com/SlickQuant/slick-stream-buffer-multiplexer) —
+a lock-free multi-producer multi-consumer (MPMC) byte stream multiplexer with shared memory support.
+
+**Maintains exact binary compatibility with the C++ version**: Python and C++ producers and
+consumers can be mixed freely across processes, fanning into the same shared memory segments.
+
+## Concept
+
+Each producer owns its own [slick-stream-buffer](https://github.com/SlickQuant/slick-stream-buffer)
+(an independently-sized byte ring with per-producer lap/loss detection). `consume()` additionally
+publishes a small 16-byte `{sequence, producer_id}` record into one shared
+[slick-queue](https://github.com/SlickQuant/slick-queue), which acts as the lock-free MPMC
+fan-in / global ordering point. Consumers read from the shared queue and dereference each record
+back into the matching producer's buffer.
+
+```
+Producer A ──prepare/commit/consume──▶ [StreamBuffer A] ──┐
+Producer B ──prepare/commit/consume──▶ [StreamBuffer B] ──┼─▶ {sequence, producer_id}
+Producer N ──prepare/commit/consume──▶ [StreamBuffer N] ──┘        16-byte records
+                                                                         │
+                                                              [shared SlickQueue]
+                                                                         │
+                                          consumers read(cursor) and dereference
+                                          into StreamBuffer[producer_id]
+```
+
+Producers and the shared queue each independently choose local memory or shared memory (IPC).
+A cross-process consumer only registers the producer ids whose shared memory it can access;
+records referencing other producer ids are silently skipped (not counted as loss).
+
+## Requirements
+
+- Python 3.8+
+- [slick-queue-py](https://github.com/SlickQuant/slick-queue-py) >= 1.2.0
+- [slick-stream-buffer-py](https://github.com/SlickQuant/slick-stream-buffer-py) >= 0.1.0
+
+Both dependencies bundle a small C++ extension for `std::atomic` operations; this package itself
+is pure Python.
+
+## Installation
+
+```bash
+pip install slick-queue-py slick-stream-buffer-py
+pip install -e .
+```
+
+## Quick Start
+
+### Producers (any process, any language)
+
+```python
+from slick_stream_buffer_multiplexer_py import StreamBufferMultiplexer
+
+# create the shared record queue (the fan-in ordering point)
+mux = StreamBufferMultiplexer(shared_queue_size=1 << 16, name="mux_records")
+
+# each producer gets its own independently-sized stream buffer
+feed_a = mux.add_producer(0, capacity=1 << 26, control_size=1 << 16, name="feed_a")
+feed_b = mux.add_producer(1, capacity=1 << 20, control_size=1 << 10, name="feed_b")
+
+mv = feed_a.prepare(64 * 1024)     # contiguous writable memoryview (zero-copy)
+n = sock.recv_into(mv)             # write network bytes directly into the ring
+feed_a.commit(n)
+feed_a.consume(n)                  # publish as ONE message + fan into the shared queue
+```
+
+### Consumer (opens everything created elsewhere — Python or C++)
+
+```python
+mux = StreamBufferMultiplexer(name="mux_records")     # open the shared record queue
+mux.add_producer(0, name="feed_a")                    # register the producers to follow
+mux.add_producer(1, name="feed_b")                    # (geometry read from each header)
+
+cursor = mux.initial_reading_index()                  # or 0 to read history
+while True:
+    rec, cursor = mux.read(cursor)
+    if not rec:
+        continue
+    handle_message(rec.producer_id, rec.data, rec.length)
+```
+
+### Work-stealing consumers (each message to exactly one consumer)
+
+```python
+from slick_stream_buffer_multiplexer_py import AtomicCursor
+from multiprocessing.shared_memory import SharedMemory
+
+cursor_shm = SharedMemory(name="mux_cursor", create=True, size=8)
+shared_cursor = AtomicCursor(cursor_shm.buf, 0)
+
+rec, idx = mux.read(shared_cursor)   # atomically claims the next message
+```
+
+## Three Loss Counters
+
+| Counter | Meaning |
+|---|---|
+| `mux.loss_count()` | shared-queue wrap loss **plus** multiplexer-level loss (registered producers lapped before dereference) |
+| `producer.loss_count()` | that producer's own inner-ring loss |
+| unregistered producer ids | **never counted** — silently skipped |
+
+## C++ Interoperability
+
+The C++ side composes the identical primitives — either language can create any segment:
+
+```cpp
+#include <slick/stream_buffer_multiplexer.hpp>
+
+slick::stream_buffer_multiplexer mux("mux_records");   // open queue created by Python
+auto feed = mux.add_producer(0, "feed_a");             // open Python's producer segment
+
+uint64_t cursor = mux.initial_reading_index();
+for (;;) {
+    auto rec = mux.read(cursor);
+    if (!rec) continue;
+    handle_message(rec.producer_id, rec.data, rec.length);
+}
+```
+
+Use `get_shm_name()` on the multiplexer (queue segment) and each producer buffer to get the
+exact names to pass to C++ (POSIX names include the required leading `/`).
+
+### Binary layout
+
+The multiplexer adds no shared-memory structures of its own:
+
+- The shared queue is a standard slick-queue segment (`'SLQ1'`, `element_size=16`) whose
+  elements are `uint64 sequence | uint32 producer_id | uint32 pad0`
+- Each producer buffer is a standard slick-stream-buffer segment (`'SSB1'`)
+
+## Caveats (same as C++)
+
+- `add_producer()` is single-threaded setup: call it before producer/consumer threads start.
+- Each producer's `prepare/commit/consume/...` must be called from a single thread.
+- Lossy semantics: slow consumers skip overwritten data (see the loss counters above).
+- A single message (one `consume()` call) is limited to < 4 GiB.
+
+See [API_DIFFERENCES.md](API_DIFFERENCES.md) for exact deviations from the C++ API.
+
+## Building and Testing
+
+```bash
+# Pure-Python tests (sibling repos slick-queue-py / slick-stream-buffer-py are
+# picked up automatically from ../ if not pip-installed)
+python tests/test_multiplexer.py
+python tests/test_multiplexer_mpmc.py
+python tests/test_multiplexer_shm.py
+
+# C++ interop tests (requires CMake + a C++20 compiler)
+cmake -S . -B build
+cmake --build build --config Debug
+cd build && ctest -C Debug --output-on-failure
+```
+
+The interop tests fetch slick-stream-buffer-multiplexer (which pulls slick-stream-buffer,
+slick-queue, and slick-shm) from GitHub and build real C++ producer/consumer binaries against
+the actual header. To build against local checkouts instead (no network):
+
+```bash
+cmake -S . -B build \
+  -DFETCHCONTENT_SOURCE_DIR_SLICK-STREAM-BUFFER-MULTIPLEXER=/path/to/slick-stream-buffer-multiplexer \
+  -DFETCHCONTENT_SOURCE_DIR_SLICK-STREAM-BUFFER=/path/to/slick-stream-buffer \
+  -DFETCHCONTENT_SOURCE_DIR_SLICK-QUEUE=/path/to/slick-queue \
+  -DFETCHCONTENT_SOURCE_DIR_SLICK-SHM=/path/to/slick-shm
+```
+
+If a failed test run leaves segments behind: `python tests/cleanup_shm.py`
+
+## Related Projects
+
+- [slick-stream-buffer-multiplexer](https://github.com/SlickQuant/slick-stream-buffer-multiplexer) — the C++ implementation
+- [slick-stream-buffer-py](https://github.com/SlickQuant/slick-stream-buffer-py) / [slick-stream-buffer](https://github.com/SlickQuant/slick-stream-buffer) — the per-producer SPMC byte stream buffer
+- [slick-queue-py](https://github.com/SlickQuant/slick-queue-py) / [slick-queue](https://github.com/SlickQuant/slick-queue) — the shared MPMC record queue
+
+## License
+
+MIT

slick_stream_buffer_multiplexer_py-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+slick_stream_buffer_multiplexer_py.py,sha256=alaL4mZ3Fl3NyMnoQOYiTikEyNvHos_KmnQr1CZe9Gg,16823
+slick_stream_buffer_multiplexer_py-0.1.0.dist-info/licenses/LICENSE,sha256=6kgljIbXmMwPF6yv8Foa-s6D9F7CanDaBZF4Jjv_N6M,1068
+slick_stream_buffer_multiplexer_py-0.1.0.dist-info/METADATA,sha256=BMfEobHK3KIf_uSzeiGqL9PJr_tGki1ZVsDn0cq_55c,9227
+slick_stream_buffer_multiplexer_py-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+slick_stream_buffer_multiplexer_py-0.1.0.dist-info/top_level.txt,sha256=mwlFHSOpYq-PbIRIpL84oLK6JxFe145iIPEocRydAmE,35
+slick_stream_buffer_multiplexer_py-0.1.0.dist-info/RECORD,,

slick_stream_buffer_multiplexer_py-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

slick_stream_buffer_multiplexer_py-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Slick Quant
+
+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.

slick_stream_buffer_multiplexer_py-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+slick_stream_buffer_multiplexer_py

slick_stream_buffer_multiplexer_py.py

@@ -0,0 +1,407 @@
+"""
+slick-stream-buffer-multiplexer-py: A lock-free multi-producer multi-consumer
+byte stream multiplexer, binary-compatible with the C++
+slick::stream_buffer_multiplexer (slick/stream_buffer_multiplexer.hpp v1.0.x).
+
+Each producer owns its own SlickStreamBuffer (an independently-sized data ring
+with its own control ring). consume() additionally publishes a small 16-byte
+{sequence, producer_id} record into one shared SlickQueue, which acts as the
+lock-free MPMC fan-in / global ordering point.
+
+Consumers call read(cursor), which dequeues the next shared-queue record and
+dereferences it back into the matching producer's stream buffer, returning a
+(data, length, producer_id) message.
+
+Producers and the shared queue each independently choose local memory or
+shared memory (IPC): see add_producer() and the constructor. A cross-process
+consumer only needs to register (via add_producer) the producer ids whose
+shared memory it has access to; records referencing other producer ids are
+silently skipped (not counted as loss - see loss_count()).
+
+Binary compatibility: the multiplexer layer adds no shared-memory structures
+of its own. The shared queue is a standard slick-queue segment ('SLQ1',
+element_size=16) whose elements hold:
+
+    Offset 0-7  (8 bytes): uint64 sequence     - record seq in the producer's buffer
+    Offset 8-11 (4 bytes): uint32 producer_id
+    Offset 12-15 (4 bytes): uint32 pad0
+
+Each producer buffer is a standard slick-stream-buffer segment ('SSB1').
+A C++ slick::stream_buffer_multiplexer and this class interoperate through
+the same segments in any combination of producer/consumer roles.
+
+Caveats (same as C++):
+- add_producer() is single-threaded setup: call it before any producer or
+  consumer threads start.
+- Each ProducerBuffer's producer-side methods (prepare/commit/consume/...)
+  must be called from a single thread, same as SlickStreamBuffer.
+- Three independent loss counters exist: the shared queue's own
+  queue-wrap loss, this multiplexer's loss_count() (which adds
+  multiplexer-level loss: shared-queue entries whose producer_id is registered
+  on this instance but were lapped by that producer's own ring before being
+  dereferenced), and each ProducerBuffer's own loss_count() (inner ring loss).
+  Entries whose producer_id is unregistered on this instance are never counted
+  as loss.
+- A single message (one consume() call) is limited to < 4 GiB.
+"""
+from __future__ import annotations
+
+__version__ = '0.1.0'
+
+import struct
+from typing import Dict, Optional, Tuple, Union
+
+from slick_queue_py import SlickQueue
+from slick_stream_buffer_py import SlickStreamBuffer, PublishedRecord
+from atomic_ops import AtomicCursor  # from slick-queue-py
+
+# Shared-queue element (matches stream_buffer_multiplexer.hpp:80-85):
+#   uint64 sequence @0 | uint32 producer_id @8 | uint32 pad0 @12
+RECORD_FMT = "<QII"
+RECORD_SIZE = struct.calcsize(RECORD_FMT)
+assert RECORD_SIZE == 16, "record must be 16 bytes"
+
+
+class MultiplexRecord:
+    """A dereferenced message as returned by read(). Mirrors C++
+    multiplex_record (stream_buffer_multiplexer.hpp:88-93).
+
+    Evaluates to False if no message was available. Unlike C++, `data` is a
+    bytes copy, not a pointer into the producer's ring.
+    """
+    __slots__ = ('data', 'length', 'producer_id')
+
+    def __init__(self, data: Optional[bytes] = None, length: int = 0,
+                 producer_id: int = 0):
+        self.data = data
+        self.length = length
+        self.producer_id = producer_id
+
+    def __bool__(self) -> bool:
+        return self.data is not None
+
+    def __repr__(self) -> str:
+        return (f"MultiplexRecord(producer_id={self.producer_id}, "
+                f"length={self.length})")
+
+
+class ProducerBuffer:
+    """Per-producer handle: wraps one SlickStreamBuffer and publishes into the
+    shared record queue. Mirrors C++ producer_buffer
+    (stream_buffer_multiplexer.hpp:96-168).
+
+    Created only by StreamBufferMultiplexer.add_producer().
+    """
+
+    def __init__(self, producer_id: int, shared_queue: SlickQueue,
+                 buffer: SlickStreamBuffer):
+        self._producer_id = producer_id
+        self._shared_queue = shared_queue
+        self._buffer = buffer
+
+    # ------------------------------------------------------------------
+    # Producer side (single thread only) - forwards to the inner stream buffer
+    # ------------------------------------------------------------------
+
+    def prepare(self, n: int) -> memoryview:
+        """Get a contiguous writable region of n bytes (zero-copy memoryview)."""
+        return self._buffer.prepare(n)
+
+    def commit(self, n: int) -> None:
+        """Move n prepared bytes into the readable region (clamped)."""
+        self._buffer.commit(n)
+
+    def consume(self, n: int) -> PublishedRecord:
+        """Publish the first n committed bytes as one message, and fan it into
+        the shared record queue so multiplexer consumers can find it.
+        (Matches C++ stream_buffer_multiplexer.hpp:116-127.)
+        """
+        rec = self._buffer.consume(n)
+        if rec:
+            idx = self._shared_queue.reserve()
+            struct.pack_into(RECORD_FMT, self._shared_queue[idx], 0,
+                             rec.sequence, self._producer_id, 0)
+            self._shared_queue.publish(idx)
+        return rec
+
+    def discard(self) -> None:
+        """Drop unconsumed + prepared bytes without publishing."""
+        self._buffer.discard()
+
+    def data(self) -> memoryview:
+        """Read-only view of the committed-but-unconsumed region."""
+        return self._buffer.data()
+
+    def size(self) -> int:
+        """Number of committed-but-unconsumed bytes."""
+        return self._buffer.size()
+
+    # ------------------------------------------------------------------
+    # Shared accessors
+    # ------------------------------------------------------------------
+
+    @property
+    def capacity(self) -> int:
+        return self._buffer.capacity
+
+    @property
+    def control_size(self) -> int:
+        return self._buffer.control_size
+
+    def loss_count(self) -> int:
+        """THIS producer's inner ring loss only (not multiplexer-level loss)."""
+        return self._buffer.loss_count()
+
+    def initial_reading_index(self) -> int:
+        return self._buffer.initial_reading_index()
+
+    @property
+    def own_buffer(self) -> bool:
+        return self._buffer.own_buffer
+
+    @property
+    def use_shm(self) -> bool:
+        return self._buffer.use_shm
+
+    @property
+    def producer_id(self) -> int:
+        return self._producer_id
+
+    @property
+    def stream_buffer(self) -> SlickStreamBuffer:
+        """The underlying SlickStreamBuffer (C++ exposes both stream_buffer()
+        and stream_buffer_ptr(); Python needs only one accessor)."""
+        return self._buffer
+
+    def get_shm_name(self) -> Optional[str]:
+        """The producer segment's name for C++ interop (see
+        SlickStreamBuffer.get_shm_name())."""
+        return self._buffer.get_shm_name()
+
+    def close(self) -> None:
+        """Close the underlying stream buffer connection."""
+        self._buffer.close()
+
+    def unlink(self) -> None:
+        """Unlink (delete) the underlying shared memory segment, if any."""
+        self._buffer.unlink()
+
+
+class StreamBufferMultiplexer:
+    """A lock-free MPMC byte stream multiplexer compatible with C++
+    slick::stream_buffer_multiplexer.
+
+    Construction modes (mirroring the three C++ constructors,
+    stream_buffer_multiplexer.hpp:175-184):
+
+    - ``StreamBufferMultiplexer(shared_queue_size=1024)``
+      local-memory shared record queue
+    - ``StreamBufferMultiplexer(shared_queue_size=1024, name="mux_q")``
+      shared-memory record queue (create or open)
+    - ``StreamBufferMultiplexer(name="mux_q")``
+      open an existing shared-memory record queue (geometry self-described)
+
+    Args:
+        shared_queue_size: Shared record queue capacity (must be a power of 2).
+        name: Shared memory name for the record queue. If None, local memory.
+    """
+
+    def __init__(self, *, shared_queue_size: Optional[int] = None,
+                 name: Optional[str] = None):
+        if shared_queue_size is not None and (
+                shared_queue_size == 0 or shared_queue_size & (shared_queue_size - 1)):
+            raise ValueError("shared_queue_size must be a power of two")
+        if shared_queue_size is not None:
+            if name is not None:
+                self._shared_queue = SlickQueue(
+                    name=name, size=shared_queue_size, element_size=RECORD_SIZE)
+            else:
+                self._shared_queue = SlickQueue(
+                    size=shared_queue_size, element_size=RECORD_SIZE)
+        else:
+            if name is None:
+                raise ValueError("shared_queue_size or name must be provided")
+            self._shared_queue = SlickQueue(name=name, element_size=RECORD_SIZE)
+
+        self._producers: Dict[int, ProducerBuffer] = {}
+        # multiplexer-level loss (registered producer lapped before dereference);
+        # per-instance, like the C++ loss_count_ member. Always counted in Python.
+        self._loss_count = 0
+
+    # ------------------------------------------------------------------
+    # Producer registration (single-threaded setup)
+    # ------------------------------------------------------------------
+
+    def add_producer(self, producer_id: int, *, capacity: Optional[int] = None,
+                     control_size: Optional[int] = None,
+                     name: Optional[str] = None) -> ProducerBuffer:
+        """Register a producer, mirroring the three C++ overloads
+        (stream_buffer_multiplexer.hpp:194-206):
+
+        - ``add_producer(id, capacity=..., control_size=...)`` local memory
+        - ``add_producer(id, capacity=..., control_size=..., name=...)`` shm creator
+        - ``add_producer(id, name=...)`` open existing shm (geometry self-described)
+
+        Raises:
+            ValueError: if producer_id is already registered, or sizes invalid.
+        """
+        if self.has_producer(producer_id):
+            raise ValueError(f"producer_id {producer_id} already registered")
+        buffer = SlickStreamBuffer(capacity=capacity, control_size=control_size,
+                                   name=name)
+        producer = ProducerBuffer(producer_id, self._shared_queue, buffer)
+        self._producers[producer_id] = producer
+        return producer
+
+    def has_producer(self, producer_id: int) -> bool:
+        return producer_id in self._producers
+
+    def get_producer_buffer(self, producer_id: int) -> Optional[ProducerBuffer]:
+        """The registered producer, or None if producer_id is unregistered."""
+        return self._producers.get(producer_id)
+
+    def find_producer(self, producer_id: int) -> Optional[ProducerBuffer]:
+        """Alias of get_producer_buffer() (C++ has both; Python has no
+        owning/non-owning pointer distinction)."""
+        return self._producers.get(producer_id)
+
+    def producer_count(self) -> int:
+        """Number of registered producers on this multiplexer instance."""
+        return len(self._producers)
+
+    # ------------------------------------------------------------------
+    # Consumer side
+    # ------------------------------------------------------------------
+
+    def read(self, cursor: Union[int, AtomicCursor]) -> Tuple[MultiplexRecord, int]:
+        """Read the next message in global order.
+
+        Two modes, mirroring the two C++ overloads
+        (stream_buffer_multiplexer.hpp:237-248):
+
+        - int cursor (per-consumer): ``rec, cursor = mux.read(cursor)`` -
+          the updated cursor is returned (Python has no by-ref ints)
+        - AtomicCursor (work-stealing across consumers): ``rec, idx = mux.read(cursor)`` -
+          the cursor advances atomically inside the shared queue; idx is the
+          claimed shared-queue index (-1 when no message was available)
+
+        Returns:
+            (record, cursor_or_index) - record is falsy when no message is
+            available. Records from unregistered producer ids are silently
+            skipped (not loss); records lapped by their producer's ring are
+            skipped and counted in loss_count().
+        """
+        if isinstance(cursor, AtomicCursor):
+            return self._read_atomic(cursor)
+        return self._read_int(cursor)
+
+    def loss_count(self) -> int:
+        """Shared-queue wrap loss plus multiplexer-level loss (shared-queue
+        entries whose producer_id is registered on this instance but were
+        lapped by that producer's own ring before being dereferenced).
+        Entries whose producer_id is unregistered are never counted.
+        (Matches C++ stream_buffer_multiplexer.hpp:255-261; Python always
+        counts, C++ only when the loss-detection macros are enabled.)
+        """
+        return self._shared_queue.loss_count() + self._loss_count
+
+    def initial_reading_index(self) -> int:
+        """Initial reading cursor for a late-joining consumer
+        (see SlickQueue.initial_reading_index())."""
+        return self._shared_queue.initial_reading_index()
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    @property
+    def shared_queue(self) -> SlickQueue:
+        """The underlying shared record queue."""
+        return self._shared_queue
+
+    def get_shm_name(self) -> Optional[str]:
+        """The shared record queue's segment name for C++ interop."""
+        return self._shared_queue.get_shm_name()
+
+    def close(self) -> None:
+        """Close all producer buffers and the shared record queue."""
+        for producer in self._producers.values():
+            try:
+                producer.close()
+            except Exception:
+                pass
+        self._producers = {}
+        try:
+            self._shared_queue.close()
+        except Exception:
+            pass
+
+    def unlink(self) -> None:
+        """Unlink (delete) the shared record queue segment and all registered
+        producers' segments. Call once, after all users have closed."""
+        for producer in self._producers.values():
+            try:
+                producer.unlink()
+            except Exception:
+                pass
+        try:
+            self._shared_queue.unlink()
+        except Exception:
+            pass
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):  # noqa: U100
+        self.close()
+        return False
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _dereference(self, producer: ProducerBuffer, sequence: int,
+                     producer_id: int) -> MultiplexRecord:
+        """Dereference a shared-queue record into the matching producer's
+        stream buffer. Falsy if the record was lapped before being
+        dereferenced. (Matches C++ stream_buffer_multiplexer.hpp:315-322.)"""
+        data, length, new_cursor = producer.stream_buffer.read(sequence)
+        if data is not None and new_cursor == sequence + 1:
+            return MultiplexRecord(data, length, producer_id)
+        return MultiplexRecord()
+
+    def _read_int(self, cursor: int) -> Tuple[MultiplexRecord, int]:
+        """read_impl with a per-consumer int cursor
+        (stream_buffer_multiplexer.hpp:324-345)."""
+        while True:
+            data, _, cursor = self._shared_queue.read(cursor)
+            if data is None:
+                return MultiplexRecord(), cursor
+            sequence, producer_id, _ = struct.unpack(RECORD_FMT, data)
+            producer = self._producers.get(producer_id)
+            if producer is None:
+                continue  # not registered on this instance: ignored, not loss
+            result = self._dereference(producer, sequence, producer_id)
+            if result:
+                return result, cursor
+            self._loss_count += 1
+
+    def _read_atomic(self, cursor: AtomicCursor) -> Tuple[MultiplexRecord, int]:
+        """read_impl with a shared atomic work-stealing cursor
+        (stream_buffer_multiplexer.hpp:246-248, 324-345)."""
+        while True:
+            data, _, idx = self._shared_queue.read(cursor)
+            if data is None:
+                return MultiplexRecord(), -1
+            sequence, producer_id, _ = struct.unpack(RECORD_FMT, data)
+            producer = self._producers.get(producer_id)
+            if producer is None:
+                continue
+            result = self._dereference(producer, sequence, producer_id)
+            if result:
+                return result, idx
+            self._loss_count += 1
+
+
+__all__ = ["StreamBufferMultiplexer", "ProducerBuffer", "MultiplexRecord",
+           "AtomicCursor", "RECORD_SIZE", "__version__"]