nblf-queue 0.1.0__cp312-abi3-win_amd64.whl

nblf_queue/__init__.py

@@ -0,0 +1,3 @@
+from ._nblf_queue_py import Queue, DynamicQueue
+
+__all__ = ["Queue", "DynamicQueue"]

nblf_queue/__init__.pyi

@@ -0,0 +1,183 @@
+from typing import Callable, Generic, TypeVar
+
+_T = TypeVar("_T")
+
+class DynamicQueue(Generic[_T]):
+    """
+    A dynamically growable, lock-free non-blocking MPMC queue.
+
+    Core operations detach from the python GIL, to ensure concurrent performance.
+    """
+
+    def __init__(self, size: int) -> None:
+        """
+        Constructs a new `DynamicQueue` with initial capacity `size`.
+        """
+        ...
+
+    def push(self, item: _T) -> _T | None:
+        """
+        Attempts to push an element into the queue.
+
+        Returns the item, if the queue was full.
+        """
+        ...
+
+    def pop(self) -> _T | None:
+        """
+        Attempts to pop an item from the queue.
+
+        Returns `None` if the queue was empty.
+        """
+        ...
+
+    def len(self) -> int:
+        """
+        Returns the current length of the queue.
+
+        This method should not be used for synchronization.
+        """
+        ...
+
+    def capacity(self) -> int:
+        """
+        Returns the current capacity of the queue.
+
+        This method should not be used for synchronization.
+        """
+        ...
+
+    def is_empty(self) -> bool:
+        """
+        Indicates whether the queue is currently empty.
+
+        This method should not be used for synchronization.
+        """
+        ...
+
+    def is_full(self) -> bool:
+        """
+        Indicates whether the queue is currently full.
+
+        This method should not be used for synchronization.
+        """
+        ...
+
+    def force_push(self, item: _T) -> _T | None:
+        """
+        Pushes an item into the queue.
+        This method may take some time under heavy contention.
+        This method may pop an arbitrary amount of items from the queue.
+
+        Returns the last popped item, if the queue was full. All other items are dropped.
+        """
+        ...
+
+    def force_push_and_do(self, item: _T, f: Callable[[_T], None]) -> None:
+        """
+        Pushes an item into the queue.
+        This method may take some time under heavy contention.
+        This method may pop an arbitrary amount of items from the queue.
+        Applies `f` to each popped item.
+        """
+        ...
+
+    def grow_by(self, by: int) -> bool:
+        """
+        Attempts to grow the queue's capacity by `by` items.
+
+        This method may spuriously fail.
+
+        Returns `True` if the capacity was successfully grown.
+        """
+        ...
+
+    def grow(self) -> bool:
+        """
+        Attempts to grow the queue's capacity using limited exponential growth.
+
+        This method may spuriously fail.
+
+        Returns `True` if the capacity was successfully grown.
+        """
+        ...
+
+class Queue(Generic[_T]):
+    """
+    A lock-free non-blocking MPMC queue.
+
+    Core operations detach from the python GIL, to ensure concurrent performance.
+    """
+
+    def __init__(self, size: int) -> None:
+        """
+        Constructs a new `Queue` with initial capacity `size`.
+        """
+        ...
+
+    def push(self, item: _T) -> _T | None:
+        """
+        Attempts to push an element into the queue.
+
+        Returns the item, if the queue was full.
+        """
+        ...
+
+    def pop(self) -> _T | None:
+        """
+        Attempts to pop an item from the queue.
+
+        Returns `None` if the queue was empty.
+        """
+        ...
+
+    def len(self) -> int:
+        """
+        Returns the current length of the queue.
+
+        This method should not be used for synchronization.
+        """
+        ...
+
+    def capacity(self) -> int:
+        """
+        Returns the current capacity of the queue.
+
+        This method should not be used for synchronization.
+        """
+        ...
+
+    def is_empty(self) -> bool:
+        """
+        Indicates whether the queue is currently empty.
+
+        This method should not be used for synchronization.
+        """
+        ...
+
+    def is_full(self) -> bool:
+        """
+        Indicates whether the queue is currently full.
+
+        This method should not be used for synchronization.
+        """
+        ...
+
+    def force_push(self, item: _T) -> _T | None:
+        """
+        Pushes an item into the queue.
+        This method may take some time under heavy contention.
+        This method may pop an arbitrary amount of items from the queue.
+
+        Returns the last popped item, if the queue was full. All other items are dropped.
+        """
+        ...
+
+    def force_push_and_do(self, item: _T, f: Callable[[_T], None]) -> None:
+        """
+        Pushes an item into the queue.
+        This method may take some time under heavy contention.
+        This method may pop an arbitrary amount of items from the queue.
+        Applies `f` to each popped item.
+        """
+        ...

nblf_queue-0.1.0.dist-info/METADATA

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: nblf-queue
+Version: 0.1.0
+License-File: LICENSE
+Summary: Lock-free, non-blocking MPMC queues.
+Keywords: queue,mpmc,atomic,lock-free
+Author-email: Louis Meller <louis.meller@icloud.com>
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Repository, https://github.com/lmeller-git/nblf-queue
+Project-URL: Documentation, https://docs.rs/nblf-queue
+
+[![Codecov](https://codecov.io/github/lmeller-git/nblf-queue/coverage.svg?branch=main)](https://codecov.io/gh/lmeller-git/nblf-queue)
+![CI Test](https://github.com/lmeller-git/nblf-queue/actions/workflows/test.yml/badge.svg?branch=main)
+![Safety Test](https://github.com/lmeller-git/nblf-queue/actions/workflows/safety.yml/badge.svg?branch=main)
+![no_std Test](https://github.com/lmeller-git/nblf-queue/actions/workflows/nostd.yml/badge.svg?branch=main)
+[![Crates.io](https://img.shields.io/crates/v/nblf-queue)](https://crates.io/crates/nblf-queue)
+[![Docs.rs](https://docs.rs/nblf-queue/badge.svg)](https://docs.rs/nblf-queue)
+
+# nblf-queue
+
+> Non-Blocking Lock-Free Queue
+
+An atomic lock-free MPMC queue based on the NBLFQ algorithm.
+
+This repository provides multiple queue implementations with different storage and allocation strategies.
+
+All queues in this repository are safe to use in a concurrent context and will never block the calling thread.
+
+## Queue variants
+
+- **Static queues**: fixed-capacity queues backed by static storage
+- **Allocated queues**: fixed-capacity queues backed by dynamically allocated storage, only available on feature `alloc`
+- **Dynamic queues**: dynamically growable queues, only available on feature `dynamic`
+- **Pooled Queues**: variants of other queues, which may store arbitrary types, only available on feature `pool`
+
+Non-pooled queues store items in atomically updated slots, restricting the stored items to small, pointer-like values.
+
+
+## Usage
+
+`nblf_queue::StaticQueue`:
+
+```rust
+  use nblf_queue::{StaticQueue, MPMCQueue};
+
+  let q: StaticQueue<_, 2> = StaticQueue::new();
+
+  assert!(q.push(&42).is_ok());
+  assert!(q.push(&1).is_ok());
+  assert!(q.push(&4242).is_err());
+
+  assert_eq!(q.pop(), Some(&42));
+  assert_eq!(q.pop(), Some(&1));
+  assert!(q.pop().is_none());
+```
+
+
+`nblf_queue::PooledStaticQueue`:
+
+```rust
+  #[cfg(feature = "pool")]
+  fn run() {
+    use nblf_queue::{PooledStaticQueue, MPMCQueue};
+
+    let q: PooledStaticQueue<_, 2> = PooledStaticQueue::new();
+
+    assert!(q.push(42).is_ok());
+    assert!(q.push(1).is_ok());
+    assert!(q.push(4242).is_err());
+
+    assert_eq!(q.pop(), Some(42));
+    assert_eq!(q.pop(), Some(1));
+    assert!(q.pop().is_none());
+  }
+
+  #[cfg(feature = "pool")]
+  run();
+```
+
+
+## Choosing a queue type
+
+`StaticQueue` and `Queue` may only store small values and are optimized for this use case.
+
+`PooledStaticQueue` and `PooledQueue` may store arbitrary types, at the cost of higher memory usage and runtime cost.
+
+`DynamicQueue` and `PooledDynamicQueue` may be grown dynamically, at the cost of higher total memory usage and runtime cost. This is cost is even higher for `PooledDynamicQueue`.
+
+## Platform Support
+
+Multiple storage types are available, dependent on platform:
+
+- **Tagged64** - platforms with native 64-bit atomic operations or feature `atomic-fallback`
+
+- **Tagged128** - platforms with native 128-bit atomic operations or feature `atomic-fallback`
+
+Storage types will be chosen automatically, unless sepcified explicitly.
+
+> [!NOTE]
+> **ABA Safety & Storage Selection**
+> If it is plausible that other threads could perform `(2^15 - 1) * queue_size`
+> pop and push operations while a single thread is paused/preempted in pop/push, `Tagged128` slots should be used to ensure ABA safety.
+
+## Feature Flags
+
+- `std`: Enables `std` and `alloc` support
+
+- `alloc`: Enables `alloc` support, allowing usage of some dynamically allocated queues
+
+- `pool`: Enables pooled queues, which may store any type
+
+- `dynamic`: Enables dynamic queues, which may dynamically grow
+
+- `atomic-fallback`: Uses `portable-atomic` `fallback` feature for atomics if necessary. It is discouraged to use this feature, as `fallback` internally uses locks
+
+- `default`: `pool`
+
+
+## Python Bindings
+
+Python bindings backed by `PooledQueue` and `PooledDynamicQueue` are available for concurrent applications.
+Core operations detach from the GIL to allow parallel execution.
+
+> [!NOTE]
+> The Python bindings strictly use `Auto` slots without feature `atomic-fallback`.
+> As a result, these bindings are only supported on platforms with native 64-bit or 128-bit atomic operations.
+
+```python
+  from nblf_queue import Queue, DynamicQueue
+
+  q: Queue[int] = Queue(10)
+
+  q.push(42)
+  item = q.pop()
+  assert item == 42
+
+  dq: DynamicQueue[str] = DynamicQueue(5)
+  dq.push("hello")
+
+  dq.grow()
+```
+
+
+## Testing
+
+The core test-suite of this crate was adapted from [`crossbeam-queue`](https://github.com/crossbeam-rs/crossbeam/tree/main/crossbeam-queue).
+
+Current testing is based on:
+
+- **Miri** - to validate pointer arithmetic and catch UB
+- **Loom and Shuttle** - to test for race conditions
+- **ASan** - to check for memory corruption and leakage
+
+
+## References
+
+Alexandre Denis, Charles Goedefroit. NBLFQ: a lock-free MPMC queue optimized for low contention.
+IPDPS 2025 - 39th International Parallel & Distributed Processing Symposium, IEEE, Jun 2025,
+Milan, Italy. hal-04851700v2
+

nblf_queue-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+nblf_queue-0.1.0.dist-info/METADATA,sha256=pvYPZmvwKvKzD9FKNOqlHHsqO9IbLMHqq0RQALEbRQg,5571
+nblf_queue-0.1.0.dist-info/WHEEL,sha256=VRUGISFtmkUtogJQvMvdBlw5mQA2s0VSEJD4NOAK5wg,95
+nblf_queue-0.1.0.dist-info/licenses/LICENSE,sha256=kQATdwljoFZxExTADvtRsqU58Wk4a4ivtDYG9kDyguY,1089
+nblf_queue/__init__.py,sha256=gvsdy0JDHG8vHbCBhmUKk-9riZt91Wo4BwXp9MxM_40,88
+nblf_queue/__init__.pyi,sha256=hEuiImBpxEF28eyXrDhih6FjUHrsG8_mC8i1cluvX4M,4902
+nblf_queue/_nblf_queue_py.pyd,sha256=F2P5OE98RqegyHZU-ex9NH-gGZm1JdsUCKpg_9gHtCw,273408
+nblf_queue-0.1.0.dist-info/RECORD,,

nblf_queue-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.9.4)
+Root-Is-Purelib: false
+Tag: cp312-abi3-win_amd64

nblf_queue-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 lmeller-git
+
+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.