| Home | Libraries | People | FAQ | More

## 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(void);
      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_arg 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;
      bool push(const T &);
      bool push(T &&);
      bool pop();
      template<typename U,
               typename Enabler = std::enable_if< 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);
      size_type push(T const *, size_type);
      template<size_type size> size_type push(T const (&));
      template<std::size_t Extent> size_type push(boost::span< const T, Extent >);
      template<typename ConstIterator>
        ConstIterator push(ConstIterator, ConstIterator);
      size_type pop(T *, size_type);
      template<size_type size> size_type pop(T(&));
      template<typename OutputIterator>
        std::enable_if<!std::is_convertible< T, OutputIterator >::value, size_type >::type
        pop(OutputIterator);
      template<typename Functor> bool consume_one(Functor &&);
      template<typename Functor> size_type consume_all(Functor &&);
      size_type read_available() const;
      size_type write_available() const;
      const T & front() const;
      T & front();
      void reset(void);
    };

## 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

1.     spsc_queue(void);

   Constructs a spsc_queue

   Requires: | spsc_queue must be configured to be sized at compile-time

2.     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

3.     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

4.     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

5.     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

6.     template<typename Enabler = std::enable_if< runtime_sized > >
         spsc_queue(size_type element_count, allocator_arg 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

7.     spsc_queue(const spsc_queue &) = delete;

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

9.     spsc_queue(spsc_queue &&) = delete;

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

11.     bool push(const T & t);

    Pushes object 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.

12.     bool push(T && t);

    Pushes object 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.

13.     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.

14.     template<typename U,
                 typename Enabler = std::enable_if< 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.

15.     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.

16.     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.

17.     size_type push(T const * t, size_type size);

    Pushes as many objects from the array t 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

18.     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

19.     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

20.     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

21.     size_type pop(T * ret, size_type size);

    Pops a maximum of size 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

22.     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

23.     template<typename OutputIterator>
          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

24.     template<typename Functor> bool consume_one(Functor && f);

    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

25.     template<typename Functor> size_type consume_all(Functor && f);

    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

26.     size_type 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

27.     size_type 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

28.     const T & front() const;

    get reference to element in the front of the queue

    Availability of front element can be checked using read_available().

    | 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

29.     T & front();

    get reference to element in the front of the queue

    Availability of front element can be checked using read_available().

    | 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

30.     void reset(void);

    reset the ringbuffer

    | Note
    Not thread-safe