A light-weight C++ toolkit for building concurrent, lock-free, message-passing programs.
Switch branches/tags
Clone or download
RossBencina ALGORITHMS.txt updates: whitespace, add modified version of IBM freel…
…ist used for node pools, with discussion about C++ atomicity requirements
Latest commit 94d5974 Nov 21, 2018

README.md

Queue World

A light-weight C++ toolkit for building concurrent, lock-free, message-passing programs.

Queue World is a little collection of light-weight C++ data structures for lock-free multi-threaded programming. The focus is on providing simple primitives using well-known algorithms. Queue World makes heavy use of endogenous linking (links embedded in client structures). This avoids allocator overhead. In addition to concurrent queues, a variety of non-re-entrant endogenous linked-lists are also provided.

Concurrent data structures

QwMpmcPopAllLifoStack -- a multiple-producer multiple-consumer LIFO stack that supports push() and pop_all() operations, but not pop().

QwMpscFifoQueue -- a multiple-producer single-consumer FIFO stack. Useful for a server thread that receives requests sent from many client threads.

QwSpscUnorderedResultQueue -- a single-producer single-consumer "relaxed order" queue for returning results from a server thread to a client. Includes a client-side counter for tracking expected vs. received results.

QwNodePool -- a concurrent freelist that allocates and frees fixed-size nodes from a fixed-size node pool. Guarantees cache-line alignment of each node to avoid false sharing.

Single threaded (non-reentrant) data structures

QwSList -- a singly linked list

QwSTailList -- a singly linked "tail list" (supports constant-time insertion at back)

QwList -- a doubly linked list

The single threaded data structures provide an STL-like interface.

Philosophy

Queue World is envisaged as an inter-thread communication library for real-time audio applications, where mutexes are not an option due to the risk of priority inversion. The typical use-cases involve relatively low queue contention. The main goals have been to keep things simple and to provide infrastructure for avoiding priority inversion.

If you're looking for water-tight abstractions you might be in the wrong place. The goal here is simple and efficient implementations, even if that means having a few "pipes on the outside of the building." This is most strongly reflected in the use of endogenous linking.

Implementation Details

For simplicity of implementation, the lock-free data structures are currently built out of variations on the well-known "IBM Freelist" (see ALGORITHMS.txt for details). The main advantage of this approach is that it avoids the need to manage additional link nodes.

In the future we plan to experiment with other algorithms and to evaluate performance. In particular, an MS-queue is desirable for use as an MPMC FIFO.

All Queue World classes are provided with unit tests written using Catch (https://github.com/philsquared/Catch).

As of September 2018, Queue World will migrate to using C++11 and C++11 atomics.

The original C++03 version of Queue World used Mintomic (https://github.com/mintomic) for atomic operations and memory barriers (C++11 atomics not required). The original C++03 version of Queue World is available in the C++03-legacy branch.

Licence

Queue World is copyright (c) 2014-2018 Ross Bencina.

Queue World is licensed under The MIT Licence: http://opensource.org/licenses/MIT