Class template spsc

Class template spsc_queue

boost::lockfree::spsc_queue

Synopsis

// In header: <boost/lockfree/spsc_queue.hpp>

template<typename T, typename... Options> 
class spsc_queue {
public:
  // types
  typedef T                                 value_type;
  typedef implementation_defined::allocator allocator; 
  typedef implementation_defined::size_type size_type; 

  // public member functions
  spsc_queue();
  template<typename U, typename Enabler = std::enable_if< !runtime_sized > > 
    explicit spsc_queue(typename boost::allocator_rebind< allocator, U >::type const &);
  template<typename Enabler = std::enable_if< !runtime_sized > > 
    explicit spsc_queue(allocator const &);
  template<typename Enabler = std::enable_if< runtime_sized > > 
    explicit spsc_queue(size_type);
  template<typename U, typename Enabler = std::enable_if< runtime_sized > > 
    spsc_queue(size_type, 
               typename boost::allocator_rebind< allocator, U >::type const &);
  template<typename Enabler = std::enable_if< runtime_sized > > 
    spsc_queue(size_type, allocator const &);
  spsc_queue(const spsc_queue &) = delete;
  spsc_queue & operator=(const spsc_queue &) = delete;
  spsc_queue(spsc_queue &&) = delete;
  spsc_queue & operator=(spsc_queue &&) = delete;
  ~spsc_queue();
  void reset();
  bool empty();
  bool is_lock_free() const;
  bool push(const T &);
  bool push(T &&);
  size_t push(const T *, size_t);
  template<typename ConstIterator> 
    ConstIterator push(ConstIterator, ConstIterator);
  template<size_type size> size_type push(T const (&));
  template<std::size_t Extent> size_type push(boost::span< const T, Extent >);
  template<typename Functor> bool consume_one(Functor &&);
  bool pop();
  template<typename U, 
           typename Enabler = std::enable_if_t< std::is_convertible< T, U >::value > > 
    bool pop(U &);
  std::optional< T > pop(uses_optional_t);
  template<typename U> std::optional< U > pop(uses_optional_t);
  template<typename Functor> size_t consume_all(Functor &&);
  size_t pop(T *, size_t);
  template<size_type size> size_type pop(T(&));
  template<typename OutputIterator> 
    size_t pop_to_output_iterator(OutputIterator);
  template<typename OutputIterator, 
           typename Enabler = std::enable_if< !std::is_convertible< T, OutputIterator >::value > > 
    std::enable_if<!std::is_convertible< T, OutputIterator >::value, size_type >::type 
    pop(OutputIterator);
  const T & front() const;
  T & front();
  size_t read_available() const;
  size_t write_available() const;
};

Description

The spsc_queue class provides a single-writer/single-reader fifo queue, pushing and popping is wait-free.

Policies:

boost::lockfree::capacity<>, optional
If this template argument is passed to the options, the size of the ringbuffer is set at compile-time.
boost::lockfree::allocator<>, defaults to boost::lockfree::allocator<std::allocator<T>>
Specifies the allocator that is used to allocate the ringbuffer. This option is only valid, if the ringbuffer is configured to be sized at run-time

Requirements:

T must have a default constructor
T must be copyable or movable

`spsc_queue` public member functions

```
spsc_queue();
```
Constructs a spsc_queue

Requires:

spsc_queue must be configured to be sized at compile-time
```
template<typename U, typename Enabler = std::enable_if< !runtime_sized > > 
  explicit spsc_queue(typename boost::allocator_rebind< allocator, U >::type const &);
```
Constructs a spsc_queue with a custom allocator

Note

This is just for API compatibility: an allocator isn't actually needed

Requires:

spsc_queue must be configured to be sized at compile-time
```
template<typename Enabler = std::enable_if< !runtime_sized > > 
  explicit spsc_queue(allocator const &);
```
Constructs a spsc_queue with a custom allocator

Note

This is just for API compatibility: an allocator isn't actually needed

Requires:

spsc_queue must be configured to be sized at compile-time

template<typename Enabler = std::enable_if< runtime_sized > > 
  explicit spsc_queue(size_type element_count);

Constructs a spsc_queue for element_count elements

Requires:

spsc_queue must be configured to be sized at run-time

template<typename U, typename Enabler = std::enable_if< runtime_sized > > 
  spsc_queue(size_type element_count, 
             typename boost::allocator_rebind< allocator, U >::type const & alloc);

Constructs a spsc_queue for element_count elements with a custom allocator

Requires:

spsc_queue must be configured to be sized at run-time

template<typename Enabler = std::enable_if< runtime_sized > > 
  spsc_queue(size_type element_count, allocator const & alloc);

Constructs a spsc_queue for element_count elements with a custom allocator

Requires:

spsc_queue must be configured to be sized at run-time

spsc_queue(const spsc_queue &) = delete;

spsc_queue & operator=(const spsc_queue &) = delete;

```
spsc_queue(spsc_queue &&) = delete;
```

spsc_queue & operator=(spsc_queue &&) = delete;

```
~spsc_queue();
```
Destroys the spsc_queue, calling destructors on all remaining elements.
```
void reset();
```
reset the ringbuffer

Note

Not thread-safe
```
bool empty();
```
Check if the ringbuffer is empty

Note

Due to the concurrent nature of the ringbuffer the result may be inaccurate.

Returns:

true, if the ringbuffer is empty, false otherwise
```
bool is_lock_free() const;
```
Returns:

true, if implementation is lock-free.

bool push(const T & t);

Pushes value t to the ringbuffer.

	Note
	Thread-safe and wait-free

Requires:	only one thread is allowed to push data to the spsc_queue
Postconditions:	object will be pushed to the spsc_queue, unless it is full.
Returns:	true, if the push operation is successful.

bool push(T && t);

Pushes value t to the ringbuffer.

	Note
	Thread-safe and wait-free

Requires:	only one thread is allowed to push data to the spsc_queue
Postconditions:	object will be pushed to the spsc_queue, unless it is full.
Returns:	true, if the push operation is successful.

```
size_t push(const T * input_buffer, size_t input_count);
```
Pushes as many objects from the input range as there is space.

Note

Thread-safe and wait-free

Requires:

only one thread is allowed to push data to the spsc_queue

Returns:

number of pushed items
```
template<typename ConstIterator> 
  ConstIterator push(ConstIterator begin, ConstIterator end);
```
Pushes as many objects from the range [begin, end) as there is space.

Note

Thread-safe and wait-free

Requires:

only one thread is allowed to push data to the spsc_queue

Returns:

iterator to the first element, which has not been pushed
```
template<size_type size> size_type push(T const (&) t);
```
Pushes as many objects from the array t as there is space available.

Note

Thread-safe and wait-free

Requires:

only one thread is allowed to push data to the spsc_queue

Returns:

number of pushed items
```
template<std::size_t Extent> size_type push(boost::span< const T, Extent > t);
```
Pushes as many objects from the span t as there is space available.

Note

Thread-safe and wait-free

Requires:

only one thread is allowed to push data to the spsc_queue

Returns:

number of pushed items
```
template<typename Functor> bool consume_one(Functor && functor);
```
Consumes one element via a functor.

Pops one element from the queue and applies the functor on this object.

Note

Thread-safe and non-blocking, if functor is thread-safe and non-blocking

Returns:

true, if one element was consumed

bool pop();

Pops one object from ringbuffer.

	Note
	Thread-safe and wait-free

Requires:	only one thread is allowed to pop data from the spsc_queue
Postconditions:	if ringbuffer is not empty, object will be discarded.
Returns:	true, if the pop operation is successful, false if ringbuffer was empty.

template<typename U, 
         typename Enabler = std::enable_if_t< std::is_convertible< T, U >::value > > 
  bool pop(U & ret);

Pops one object from ringbuffer.

	Note
	Thread-safe and wait-free

Requires:	only one thread is allowed to pop data from the spsc_queue
Postconditions:	if ringbuffer is not empty, object will be copied to ret.
Returns:	true, if the pop operation is successful, false if ringbuffer was empty.

```
std::optional< T > pop(uses_optional_t);
```
Pops object from spsc_queue, returning a std::optional<>

Note

Thread-safe and non-blocking

Returns:

std::optional with value if successful, std::nullopt if spsc_queue is empty.
```
template<typename U> std::optional< U > pop(uses_optional_t);
```
Pops object from spsc_queue, returning a std::optional<>

Note

Thread-safe and non-blocking

Requires:

type T must be convertible to U

Returns:

std::optional with value if successful, std::nullopt if spsc_queue is empty.
```
template<typename Functor> size_t consume_all(Functor && functor);
```
Consumes all elements via a functor.

Sequentially pops all elements from the queue and applies the functor on each object.

Note

Thread-safe and non-blocking, if functor is thread-safe and non-blocking

Returns:

number of elements that are consumed
```
size_t pop(T * output_buffer, size_t output_count);
```
Pops a maximum of count objects from ringbuffer.

Note

Thread-safe and wait-free

Requires:

only one thread is allowed to pop data from the spsc_queue

Returns:

number of popped items
```
template<size_type size> size_type pop(T(&) ret);
```
Pops a maximum of size objects from spsc_queue.

Note

Thread-safe and wait-free

Requires:

only one thread is allowed to pop data from the spsc_queue

Returns:

number of popped items
```
template<typename OutputIterator> 
  size_t pop_to_output_iterator(OutputIterator it);
```
Pops objects to the output iterator it.

Note

Thread-safe and wait-free

Requires:

only one thread is allowed to pop data from the spsc_queue

Returns:

number of popped items

template<typename OutputIterator, 
         typename Enabler = std::enable_if< !std::is_convertible< T, OutputIterator >::value > > 
  std::enable_if<!std::is_convertible< T, OutputIterator >::value, size_type >::type 
  pop(OutputIterator it);

Pops objects to the output iterator it.

	Note
	Thread-safe and wait-free

Requires:	only one thread is allowed to pop data from the spsc_queue
Returns:	number of popped items

const T & front() const;

get reference to element in the front of the queue

	Note
	Thread-safe and wait-free

Requires:	only a consuming thread is allowed to check front element
Requires:	read_available() > 0. If ringbuffer is empty, it's undefined behaviour to invoke this method.
Returns:	reference to the first element in the queue

T & front();

get reference to element in the front of the queue

	Note
	Thread-safe and wait-free

Requires:	only a consuming thread is allowed to check front element
Requires:	read_available() > 0. If ringbuffer is empty, it's undefined behaviour to invoke this method.
Returns:	reference to the first element in the queue

```
size_t read_available() const;
```
get number of elements that are available for read

Note

Thread-safe and wait-free, should only be called from the consumer thread

Returns:

number of available elements that can be popped from the spsc_queue
```
size_t write_available() const;
```
get write space to write elements

Note

Thread-safe and wait-free, should only be called from the producer thread

Returns:

number of elements that can be pushed to the spsc_queue

	Note
	This is just for API compatibility: an allocator isn't actually needed

	Note
	Due to the concurrent nature of the ringbuffer the result may be inaccurate.

	Note
	Thread-safe and non-blocking, if functor is thread-safe and non-blocking

Requires:	type T must be convertible to U
Returns:	`std::optional` with value if successful, `std::nullopt` if spsc_queue is empty.

	Note
	Thread-safe and wait-free, should only be called from the consumer thread

Boost C++ Libraries