Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

Click here to view the latest version of this page.
PrevUpHomeNext

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);
  template<typename Functor> bool consume_one(Functor &);
  template<typename Functor> bool consume_one(Functor const &);
  template<typename Functor> size_type consume_all(Functor &);
  template<typename Functor> size_type consume_all(Functor 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

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] 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] 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] 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] 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] 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] 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] 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] Note

    Thread-safe and wait-free

    Requires:

    only one thread is allowed to pop data to the spsc_queue

    Returns:

    number of popped items

  9. 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] Note

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

    Returns:

    true, if one element was consumed

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

    consumes one element via a functor

    pops one element from the queue and applies the functor on this object

    [Note] Note

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

    Returns:

    true, if one element was consumed

  11. 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] Note

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

    Returns:

    number of elements that are consumed

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

    consumes all elements via a functor

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

    [Note] Note

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

    Returns:

    number of elements that are consumed


PrevUpHomeNext