spsc-ring-threadsafe 0.0.2

A thread-safe SPSC queue, implemented on a ring buffer written in C

Lockless thread-safe SPSC queue for Python, implemented on a ring buffer written in C

spsc-ring-threadsafe is a C extension for Python implementing a lockless, threadsafe FIFO queue.

Design

Lamport ring buffer with C11 _Atomic read + write indexes (acquire + release). Producer and consumer never contend with eachother.

Features:

• single producer, single consumer FIFO semantics
• lockless
• non-blocking / async friendly
• suitable for shared memory and IPC
• compatible with no-GIL
• compatible with subinterpreters
• low overhead, especially for small messages
• up to 100x performance when compared to multiprocessing.Queue in the standard library

Benchmarks

Example

import spsc_ring_threadsafe as srt

buf = bytearray(4096)
srt.init(buf) # initialize as ring buffer

item = b"this is a bytestring message"
srt.put(buf, item)

result = srt.get(buf)
print(result.decode())

Output:

this is a bytestring message

API

Exceptions

spsc_ring_threadsafe.QueueFullError

spsc_ring_threadsafe.QueueEmptyError

Functions

spsc_ring_threadsafe.init(buf)

buf: mutable buffer-compatible object containing the ring buffer (e.g. bytearray, memoryview). Size must be a power of two, and between 256 and 2GiB.

WARNING: initializing a buffer is not threadsafe while the ring buffer is being read / written to concurrently. Initialize once beforehand, or use your own locking primitives.

spsc_ring_threadsafe.put(buf, item)

buf: mutable buffer-compatible object containing the ring buffer (e.g. bytearray, memoryview). Size must be a power of two, and between 256 and 2GiB. item: buffer-compatible object to insert into the ring buffer.

This function does not block. If there is no space in the buffer for the inserted value, spsc_ring_threadsafe.QueueFullError will be raised immediately.

WARNING: buffer must be zeroed or initialized before use

spsc_ring_threadsafe.get(buf)

buf: mutable buffer-compatible object containing the ring buffer (e.g. bytearray, memoryview). Size must be a power of two, and between 256 and 2GiB.

Returns: a buffer-compatible object.

This function does not block. If there is no message available in the ring buffer, spsc_ring_threadsafe.QueueEmptyError will be raised immediately.

WARNING: buffer must be zeroed or initialized before use

Installation

uv add spsc-ring-threadsafe

or pip install spsc-ring-threadsafe

Run Tests

uv run python -m unittest discover -s tests -v

Run benchmark

uv pip install -e . --force-reinstall --no-deps && uv run python tests/benchmark.py

Run dev script for testing

uv pip install -e . --force-reinstall --no-deps && uv run python tests/dev.py

LLM usage disclosure

Test & benchmarks were written with assistance from AI models. All C code is written by hand.