slick-stream-buffer-multiplexer-py 0.1.0__tar.gz → 2.0.0__tar.gz

slick_stream_buffer_multiplexer_py-2.0.0/API_DIFFERENCES.md

@@ -0,0 +1,146 @@
+# API Differences: Python vs C++
+
+The Python implementation is binary-compatible with the C++
+`slick::stream_buffer_multiplexer` at the shared memory level — the shared record queue
+('SLQ1', or 'SLQ0' with `enable_read_last` off; 16-byte elements) and every producer segment
+('SSB1') match byte-for-byte. Peers must agree on `enable_read_last`, the one trait recorded in
+the queue's header (see [Traits](#traits-are-a-constructor-argument-not-a-template-parameter)).
+The *language-level* API differs in the following ways.
+
+## Construction
+
+| C++ | Python |
+|---|---|
+| `stream_buffer_multiplexer mux(size)` | `StreamBufferMultiplexer(shared_queue_size=size)` |
+| `stream_buffer_multiplexer mux(size, "name")` | `StreamBufferMultiplexer(shared_queue_size=size, name="name")` |
+| `stream_buffer_multiplexer mux("name")` | `StreamBufferMultiplexer(name="name")` |
+| `add_producer(id, cap, ctl)` | `add_producer(id, capacity=cap, control_size=ctl)` |
+| `add_producer(id, cap, ctl, "name")` | `add_producer(id, capacity=cap, control_size=ctl, name="name")` |
+| `add_producer(id, "name")` | `add_producer(id, name="name")` |
+| throws `std::invalid_argument` (duplicate id, bad sizes) | raises `ValueError` |
+| `uint32_t producer_id` (range enforced by the type) | raises `ValueError` outside `0..0xFFFFFFFF`, `TypeError` for a non-integer |
+| throws `std::runtime_error` (shm failures) | raises `RuntimeError`, `ValueError` (queue geometry mismatch), or `FileNotFoundError` (missing segment) |
+
+## Consumer cursor is passed by value
+
+```cpp
+// C++
+uint64_t cursor = 0;
+auto rec = mux.read(cursor);              // cursor updated in place
+```
+
+```python
+# Python
+cursor = 0
+rec, cursor = mux.read(cursor)            # updated cursor returned
+```
+
+For the work-stealing overload, pass an `AtomicCursor` (from slick-queue-py); the second
+return value is then the claimed shared-queue index (`-1` when nothing was available):
+
+```python
+rec, idx = mux.read(shared_cursor)
+```
+
+## Zero-copy vs copies
+
+Same policy as slick-stream-buffer-py: `prepare()` and `data()` return zero-copy
+memoryviews into the producer's ring; `read()` results (`MultiplexRecord.data`) and
+`consume()` results are **bytes copies**, safe by default under the lossy overwrite
+semantics.
+
+## Producer buffer accessors
+
+C++ exposes both `stream_buffer()` (reference) and `stream_buffer_ptr()`
+(`std::shared_ptr`); Python has no owning/non-owning distinction, so there is a single
+`producer.stream_buffer` property returning the underlying `SlickStreamBuffer`.
+Similarly, `get_producer_buffer()` and `find_producer()` both return the same
+`ProducerBuffer` object (or `None`).
+
+## Producer lookup
+
+C++ uses a dense vector for producer ids < 4096 with a hash-map fallback; Python uses a
+plain dict for all ids (already O(1) — the dense-path micro-optimization is meaningless
+in Python).
+
+`get_producer_buffers()` returns a `const` map reference in C++; Python returns a cached
+read-only `types.MappingProxyType` over the same dict — mutation raises, later
+`add_producer()` calls still show through, and the call allocates nothing. Iteration order
+is insertion order, which C++'s `unordered_map` does not promise.
+
+## Traits are a constructor argument, not a template parameter
+
+C++ spells the configuration `basic_stream_buffer_multiplexer<Traits = default_queue_traits>`;
+Python passes the same `QueueTraits` class as a `traits=` keyword argument, matching how
+slick-queue-py does it:
+
+```cpp
+// C++
+slick::basic_stream_buffer_multiplexer<slick::debug_queue_traits> mux(1024);
+```
+
+```python
+# Python
+mux = StreamBufferMultiplexer(shared_queue_size=1024, traits=MyTraits)
+```
+
+`mux.traits` returns the shared queue's frozen snapshot (C++ spells this
+`using traits = Traits`). One behavioural difference, inherited from slick-queue-py:
+C++'s `default_queue_traits` follows `NDEBUG`, so loss counting is off in release builds;
+Python has no debug/release split and defaults `enable_loss_detection` to on.
+
+That difference is harmless across processes because only one trait reaches shared memory:
+`enable_read_last`. The queue's creator records it in the layout marker (`'SLQ1'` on, `'SLQ0'`
+off) and every attacher in either language must be configured the same way, or construction fails
+with "Shared memory feature mismatch" (`RuntimeError` / `std::runtime_error`). Both sides default
+it to on; a peer that turns it off needs its counterparts to do the same:
+
+```cpp
+// C++
+struct no_read_last_traits : slick::default_queue_traits {
+    static constexpr bool enable_read_last = false;
+};
+slick::basic_stream_buffer_multiplexer<no_read_last_traits> mux("mux_records");
+```
+
+```python
+# Python
+class NoReadLast(QueueTraits):
+    enable_read_last = False
+
+mux = StreamBufferMultiplexer(name="mux_records", traits=NoReadLast)
+```
+
+## loss_count()
+
+Same semantics on both sides: `traits.enable_loss_detection` switches the shared queue's
+wrap-loss term and the multiplexer-level term together, and both read 0 when it is off. Only
+the multiplexer-level term is filtered by producer registration. Records are skipped correctly
+either way. All counters are per-instance, not shared through the segments.
+
+`ProducerBuffer.loss_count()` is likewise identical: the multiplexer dereferences through
+traits with `count_loss` off, so that counter only moves for reads the caller makes directly
+through `producer.stream_buffer.read(cursor, traits)`.
+
+## producer_buffer is not movable in C++
+
+C++ deletes `producer_buffer`'s copy and move operations, because the multiplexer keeps a raw
+pointer to the same object its `shared_ptr` names, and moving one out would leave both pointing
+at an emptied object. Python has no moves and rebinding a name copies a reference, so there is
+nothing to delete — `ProducerBuffer` has no equivalent restriction.
+
+## Lifecycle
+
+Python adds explicit lifecycle management that C++ handles via RAII:
+
+- `close()` — detach from all producer segments and the queue segment; the registration table is
+  kept, so a later `unlink()` still reaches every producer
+- `unlink()` — delete the queue segment and all registered producers' segments; valid before or
+  after `close()` (close every handle, then unlink once), and a no-op when repeated
+- context manager support: `with StreamBufferMultiplexer(...) as mux: ...`
+- `get_shm_name()` — on the multiplexer (queue segment) and on each `ProducerBuffer`,
+  the exact names to pass to C++ (`/`-prefixed on POSIX)
+
+`remove(name)` is the one lifecycle call both sides share, with the same contract: unlink a
+segment by name without attaching to it, returning `True` on success and, on Windows, always
+`True` because a section dies with its last handle.

{slick_stream_buffer_multiplexer_py-0.1.0 → slick_stream_buffer_multiplexer_py-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slick-stream-buffer-multiplexer-py
-Version: 0.1.0
+Version: 2.0.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
@@ -28,8 +28,8 @@ 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
+Requires-Dist: slick-queue-py>=2.0.0
+Requires-Dist: slick-stream-buffer-py>=2.0.0
 Dynamic: author
 Dynamic: home-page
 Dynamic: license-file
@@ -41,7 +41,14 @@ A Python implementation of [slick-stream-buffer-multiplexer](https://github.com/
 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.
+consumers can be mixed across processes, fanning into the same shared memory segments — provided
+every peer of a shared queue agrees on `enable_read_last` (see
+[`enable_read_last` must match on every peer](#enable_read_last-must-match-on-every-peer)).
+
+Tracks C++ `slick/stream_buffer_multiplexer.hpp` **v2.0.0**, and requires slick-queue-py >=
+2.0.0 and slick-stream-buffer-py >= 2.0.0. The shared-memory formats are unchanged
+(`'SLQ1'` / `'SSB1'`), so segments written by v0.1.0 or by a C++ v1.x process are still
+readable with the default traits.
 
 ## Concept
 
@@ -70,8 +77,8 @@ 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
+- [slick-queue-py](https://github.com/SlickQuant/slick-queue-py) >= 2.0.0
+- [slick-stream-buffer-py](https://github.com/SlickQuant/slick-stream-buffer-py) >= 2.0.0
 
 Both dependencies bundle a small C++ extension for `std::atomic` operations; this package itself
 is pure Python.
@@ -130,14 +137,116 @@ shared_cursor = AtomicCursor(cursor_shm.buf, 0)
 rec, idx = mux.read(shared_cursor)   # atomically claims the next message
 ```
 
+## Traits
+
+Feature configuration is a `traits` constructor argument — and it is slick-queue-py's
+`QueueTraits`, the traits of the shared record queue the multiplexer is built on, not a traits
+type of its own:
+
+```python
+from slick_stream_buffer_multiplexer_py import StreamBufferMultiplexer, QueueTraits
+
+class Silent(QueueTraits):
+    enable_loss_detection = False       # both loss terms go quiet together
+
+mux = StreamBufferMultiplexer(shared_queue_size=1024, traits=Silent)
+```
+
+Every knob the multiplexer has beyond that queue is a passthrough, and its one real tunable
+asks the same question `enable_loss_detection` already asks — so a separate flag would only let
+the two disagree. That matters because `loss_count()` **sums** the two counters: a
+half-configured pair would return a partial total that reads like a complete one. One flag, one
+number. `mux.traits` is the queue's own frozen snapshot, not a second copy.
+
+Unlike C++ — where `default_queue_traits` follows `NDEBUG` — slick-queue-py defaults
+`enable_loss_detection` to **on**, so the counters work out of the box.
+
+### `enable_read_last` must match on every peer
+
+The other traits are local to one instance and may differ freely between processes, but
+`enable_read_last` is part of the shared record queue's header protocol. The queue's creator
+stamps it into the segment's layout marker — `'SLQ1'` when the last-published index is maintained,
+`'SLQ0'` when it is not — and every attacher, Python or C++, checks the marker against its own
+traits. A peer that disagrees is refused at construction (`RuntimeError` in Python,
+`std::runtime_error` in C++, both reading *"Shared memory feature mismatch"*) rather than
+misreading the header: a Python queue created with `enable_read_last = False` cannot be opened by a
+C++ `slick::stream_buffer_multiplexer`, whose default traits have it on.
+
+Both languages default it to on, so only turning it off needs coordinating — do it identically on
+every peer of the queue:
+
+```python
+class NoReadLast(QueueTraits):
+    enable_read_last = False
+
+mux = StreamBufferMultiplexer(shared_queue_size=1 << 16, name="mux_records", traits=NoReadLast)
+```
+
+```cpp
+struct no_read_last_traits : slick::default_queue_traits {
+    static constexpr bool enable_read_last = false;
+};
+slick::basic_stream_buffer_multiplexer<no_read_last_traits> mux("mux_records");
+```
+
+The multiplexer itself never calls `read_last()` (`initial_reading_index()` reads the reservation
+counter instead), so turning it off only drops one CAS from each `consume()`'s publish into the
+shared queue. Producer segments (`'SSB1'`) carry no such flag.
+
 ## 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 |
+| `mux.loss_count()` | shared-queue wrap loss **plus** multiplexer-level loss (registered producers lapped before dereference); both terms switched by `traits.enable_loss_detection` |
+| `producer.loss_count()` | that producer's own inner-ring loss — **only** for reads the caller makes through `producer.stream_buffer.read(cursor, traits)` with counting traits |
 | unregistered producer ids | **never counted** — silently skipped |
 
+Only the multiplexer-level term is filtered by registration. The wrap-loss term counts entries
+the shared queue dropped by wrapping, and a lapped slot has already been overwritten, so nothing
+is left to say which producer it named — an instance registering a subset of producers therefore
+sees wrap loss for producers it ignores, making the total an upper bound on what it missed. Size
+the shared queue so it does not wrap and that term goes to 0.
+
+`producer.loss_count()` stays at 0 under multiplexer traffic by design: the multiplexer
+dereferences through traits with `count_loss` off, because `read()`'s counter measures how far
+a *sequential scan* jumped, which for a jump-read is a distance every later lapped dereference
+would add all over again. The multiplexer counts one loss per lapped record instead.
+
+`mux.get_producer_buffers()` returns every registered producer keyed by `producer_id` — a
+read-only live view of the registration table, cheap enough for a monitoring loop:
+
+```python
+inner_loss = sum(p.loss_count() for p in mux.get_producer_buffers().values())
+```
+
+## Shutdown
+
+Close every handle, then unlink once — the usual `shared_memory` idiom:
+
+```python
+mux.close()      # or leave a `with StreamBufferMultiplexer(...) as mux:` block
+mux.unlink()     # deletes the record queue and every registered producer's segment
+```
+
+`close()` keeps the registration table so `unlink()` can still reach each producer's segment, and
+`unlink()` runs once: repeating it never deletes a segment a later run has created under the same
+name. On Windows `unlink()` is a no-op — a section disappears once its last handle closes.
+
+## Stale-segment recovery
+
+`StreamBufferMultiplexer.remove(name)` unlinks a segment by name — it works for both kinds this
+class creates, a shared record queue's and a producer stream buffer's, since both are plain
+shared memory segments underneath. Use it when a previous run died mid-initialization and left a
+segment wedged, which construction over that name reports by raising:
+
+```python
+StreamBufferMultiplexer.remove("md_records")        # clear what a dead run left
+mux = StreamBufferMultiplexer(shared_queue_size=1024, name="md_records")
+```
+
+Only call it when no process is using the segment. On Windows it is a no-op returning `True` —
+a section there disappears once the last handle closes.
+
 ## C++ Interoperability
 
 The C++ side composes the identical primitives — either language can create any segment:
@@ -163,16 +272,23 @@ exact names to pass to C++ (POSIX names include the required leading `/`).
 
 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`
+- The shared queue is a standard slick-queue segment (`'SLQ1'`, or `'SLQ0'` when created with
+  `enable_read_last` off; `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.
+- A `producer_id` must fit the record's `uint32` field: `add_producer()` raises `ValueError`
+  for one outside `0..0xFFFFFFFF` (and `TypeError` for a non-integer), before any segment is
+  created.
 - 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.
+  Records are skipped correctly whatever the traits say; only the counters go quiet.
+- A single message (one `consume()` call) is limited to < 4 GiB: `consume()` raises
+  `ValueError` rather than truncating one that is not, before any state moves — so nothing is
+  published to either the producer's ring or the shared record queue.
 
 See [API_DIFFERENCES.md](API_DIFFERENCES.md) for exact deviations from the C++ API.
 

{slick_stream_buffer_multiplexer_py-0.1.0 → slick_stream_buffer_multiplexer_py-2.0.0}/README.md

@@ -4,7 +4,14 @@ A Python implementation of [slick-stream-buffer-multiplexer](https://github.com/
 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.
+consumers can be mixed across processes, fanning into the same shared memory segments — provided
+every peer of a shared queue agrees on `enable_read_last` (see
+[`enable_read_last` must match on every peer](#enable_read_last-must-match-on-every-peer)).
+
+Tracks C++ `slick/stream_buffer_multiplexer.hpp` **v2.0.0**, and requires slick-queue-py >=
+2.0.0 and slick-stream-buffer-py >= 2.0.0. The shared-memory formats are unchanged
+(`'SLQ1'` / `'SSB1'`), so segments written by v0.1.0 or by a C++ v1.x process are still
+readable with the default traits.
 
 ## Concept
 
@@ -33,8 +40,8 @@ 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
+- [slick-queue-py](https://github.com/SlickQuant/slick-queue-py) >= 2.0.0
+- [slick-stream-buffer-py](https://github.com/SlickQuant/slick-stream-buffer-py) >= 2.0.0
 
 Both dependencies bundle a small C++ extension for `std::atomic` operations; this package itself
 is pure Python.
@@ -93,14 +100,116 @@ shared_cursor = AtomicCursor(cursor_shm.buf, 0)
 rec, idx = mux.read(shared_cursor)   # atomically claims the next message
 ```
 
+## Traits
+
+Feature configuration is a `traits` constructor argument — and it is slick-queue-py's
+`QueueTraits`, the traits of the shared record queue the multiplexer is built on, not a traits
+type of its own:
+
+```python
+from slick_stream_buffer_multiplexer_py import StreamBufferMultiplexer, QueueTraits
+
+class Silent(QueueTraits):
+    enable_loss_detection = False       # both loss terms go quiet together
+
+mux = StreamBufferMultiplexer(shared_queue_size=1024, traits=Silent)
+```
+
+Every knob the multiplexer has beyond that queue is a passthrough, and its one real tunable
+asks the same question `enable_loss_detection` already asks — so a separate flag would only let
+the two disagree. That matters because `loss_count()` **sums** the two counters: a
+half-configured pair would return a partial total that reads like a complete one. One flag, one
+number. `mux.traits` is the queue's own frozen snapshot, not a second copy.
+
+Unlike C++ — where `default_queue_traits` follows `NDEBUG` — slick-queue-py defaults
+`enable_loss_detection` to **on**, so the counters work out of the box.
+
+### `enable_read_last` must match on every peer
+
+The other traits are local to one instance and may differ freely between processes, but
+`enable_read_last` is part of the shared record queue's header protocol. The queue's creator
+stamps it into the segment's layout marker — `'SLQ1'` when the last-published index is maintained,
+`'SLQ0'` when it is not — and every attacher, Python or C++, checks the marker against its own
+traits. A peer that disagrees is refused at construction (`RuntimeError` in Python,
+`std::runtime_error` in C++, both reading *"Shared memory feature mismatch"*) rather than
+misreading the header: a Python queue created with `enable_read_last = False` cannot be opened by a
+C++ `slick::stream_buffer_multiplexer`, whose default traits have it on.
+
+Both languages default it to on, so only turning it off needs coordinating — do it identically on
+every peer of the queue:
+
+```python
+class NoReadLast(QueueTraits):
+    enable_read_last = False
+
+mux = StreamBufferMultiplexer(shared_queue_size=1 << 16, name="mux_records", traits=NoReadLast)
+```
+
+```cpp
+struct no_read_last_traits : slick::default_queue_traits {
+    static constexpr bool enable_read_last = false;
+};
+slick::basic_stream_buffer_multiplexer<no_read_last_traits> mux("mux_records");
+```
+
+The multiplexer itself never calls `read_last()` (`initial_reading_index()` reads the reservation
+counter instead), so turning it off only drops one CAS from each `consume()`'s publish into the
+shared queue. Producer segments (`'SSB1'`) carry no such flag.
+
 ## 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 |
+| `mux.loss_count()` | shared-queue wrap loss **plus** multiplexer-level loss (registered producers lapped before dereference); both terms switched by `traits.enable_loss_detection` |
+| `producer.loss_count()` | that producer's own inner-ring loss — **only** for reads the caller makes through `producer.stream_buffer.read(cursor, traits)` with counting traits |
 | unregistered producer ids | **never counted** — silently skipped |
 
+Only the multiplexer-level term is filtered by registration. The wrap-loss term counts entries
+the shared queue dropped by wrapping, and a lapped slot has already been overwritten, so nothing
+is left to say which producer it named — an instance registering a subset of producers therefore
+sees wrap loss for producers it ignores, making the total an upper bound on what it missed. Size
+the shared queue so it does not wrap and that term goes to 0.
+
+`producer.loss_count()` stays at 0 under multiplexer traffic by design: the multiplexer
+dereferences through traits with `count_loss` off, because `read()`'s counter measures how far
+a *sequential scan* jumped, which for a jump-read is a distance every later lapped dereference
+would add all over again. The multiplexer counts one loss per lapped record instead.
+
+`mux.get_producer_buffers()` returns every registered producer keyed by `producer_id` — a
+read-only live view of the registration table, cheap enough for a monitoring loop:
+
+```python
+inner_loss = sum(p.loss_count() for p in mux.get_producer_buffers().values())
+```
+
+## Shutdown
+
+Close every handle, then unlink once — the usual `shared_memory` idiom:
+
+```python
+mux.close()      # or leave a `with StreamBufferMultiplexer(...) as mux:` block
+mux.unlink()     # deletes the record queue and every registered producer's segment
+```
+
+`close()` keeps the registration table so `unlink()` can still reach each producer's segment, and
+`unlink()` runs once: repeating it never deletes a segment a later run has created under the same
+name. On Windows `unlink()` is a no-op — a section disappears once its last handle closes.
+
+## Stale-segment recovery
+
+`StreamBufferMultiplexer.remove(name)` unlinks a segment by name — it works for both kinds this
+class creates, a shared record queue's and a producer stream buffer's, since both are plain
+shared memory segments underneath. Use it when a previous run died mid-initialization and left a
+segment wedged, which construction over that name reports by raising:
+
+```python
+StreamBufferMultiplexer.remove("md_records")        # clear what a dead run left
+mux = StreamBufferMultiplexer(shared_queue_size=1024, name="md_records")
+```
+
+Only call it when no process is using the segment. On Windows it is a no-op returning `True` —
+a section there disappears once the last handle closes.
+
 ## C++ Interoperability
 
 The C++ side composes the identical primitives — either language can create any segment:
@@ -126,16 +235,23 @@ exact names to pass to C++ (POSIX names include the required leading `/`).
 
 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`
+- The shared queue is a standard slick-queue segment (`'SLQ1'`, or `'SLQ0'` when created with
+  `enable_read_last` off; `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.
+- A `producer_id` must fit the record's `uint32` field: `add_producer()` raises `ValueError`
+  for one outside `0..0xFFFFFFFF` (and `TypeError` for a non-integer), before any segment is
+  created.
 - 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.
+  Records are skipped correctly whatever the traits say; only the counters go quiet.
+- A single message (one `consume()` call) is limited to < 4 GiB: `consume()` raises
+  `ValueError` rather than truncating one that is not, before any state moves — so nothing is
+  published to either the producer's ring or the shared record queue.
 
 See [API_DIFFERENCES.md](API_DIFFERENCES.md) for exact deviations from the C++ API.
 

{slick_stream_buffer_multiplexer_py-0.1.0 → slick_stream_buffer_multiplexer_py-2.0.0}/pyproject.toml

@@ -30,8 +30,8 @@ classifiers = [
     "Operating System :: MacOS",
 ]
 dependencies = [
-    "slick-queue-py>=1.2.0",
-    "slick-stream-buffer-py>=0.1.0",
+    "slick-queue-py>=2.0.0",
+    "slick-stream-buffer-py>=2.0.0",
 ]
 
 [project.urls]

{slick_stream_buffer_multiplexer_py-0.1.0 → slick_stream_buffer_multiplexer_py-2.0.0}/requirements.txt

@@ -1,3 +1,3 @@
 # Runtime dependencies (binary-compatible Python ports of the C++ dependencies)
-slick-queue-py>=1.2.0
-slick-stream-buffer-py>=0.1.0
+slick-queue-py>=2.0.0
+slick-stream-buffer-py>=2.0.0

{slick_stream_buffer_multiplexer_py-0.1.0 → slick_stream_buffer_multiplexer_py-2.0.0}/setup.py

@@ -52,8 +52,8 @@ setup(
     keywords='stream-buffer, multiplexer, lock-free, atomic, shared-memory, ipc, multiprocessing, mpmc',
     py_modules=['slick_stream_buffer_multiplexer_py'],
     install_requires=[
-        'slick-queue-py>=1.2.0',
-        'slick-stream-buffer-py>=0.1.0',
+        'slick-queue-py>=2.0.0',
+        'slick-stream-buffer-py>=2.0.0',
     ],
     python_requires='>=3.8',
     license='MIT',