| Home | Libraries | People | FAQ | More

## Class template spsc_queue

boost::lockfree::spsc_queue

## Synopsis

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

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

      // construct/copy/destruct
      spsc_queue(void);
      template<typename U>
        explicit spsc_queue(typename allocator::template rebind< U >::other const &);
      explicit spsc_queue(allocator const &);
      explicit spsc_queue(size_type);
      template<typename U>
        spsc_queue(size_type,
                   typename allocator::template rebind< U >::other const &);
      spsc_queue(size_type, allocator_arg const &);

      // public member functions
      bool push(T const &);
      bool pop(T &);
      size_type push(T const *, size_type);
      template<size_type size> size_type push(T const (&));
      template<typename ConstIterator>
        ConstIterator push(ConstIterator, ConstIterator);
      size_type pop(T *, size_type);
      template<size_type size> size_type pop(T(&));
      template<typename OutputIterator> size_type pop(OutputIterator);
    };

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

### `spsc_queue` public construct/copy/destruct

1.     spsc_queue(void);

   Constructs a `spsc_queue`

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

2.     template<typename U>
         explicit spsc_queue(typename allocator::template rebind< U >::other const & alloc);

3.     explicit spsc_queue(allocator const & alloc);

4.     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>
         spsc_queue(size_type element_count,
                    typename allocator::template rebind< U >::other const & alloc);

6.     spsc_queue(size_type element_count, allocator_arg const & alloc);

### `spsc_queue` public member functions

1.     bool push(T const & 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.

2.     bool pop(T & ret);

   Pops one object from ringbuffer.

   | Note
   Thread-safe and wait-free

   Requires: | only one thread is allowed to pop data to 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.

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

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

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

6.     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 to the spsc_queue
   Returns: | number of popped items

7.     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 to the spsc_queue
   Returns: | number of popped items

8.     template<typename OutputIterator> size_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 to the spsc_queue
   Returns: | number of popped items