Boost C++ Libraries Home Libraries People FAQ More

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                                  ;
  typedef  ; 
  typedef  ; 

  // public member functions
  ();
  template<typename U, typename Enabler> 
    ();
  template<typename Enabler> 
    ();
  template<typename Enabler> 
    ();
  template<typename U, typename Enabler> 
    (, 
               );
  template<typename Enabler> 
    (, );
  (spsc_queue &) = ;
  spsc_queue & (spsc_queue &) = ;
  (spsc_queue &&) = ;
  spsc_queue & (spsc_queue &&) = ;
   ();
   ();
   ();
  template<typename U, 
           typename Enabler> 
     ();
   ();
  template<typename U>  ();
   (, );
  template< size>  ();
  template< Extent>  ();
  template<typename ConstIterator> 
     (, );
   (, );
  template< size>  ();
  template<typename OutputIterator> 
     
    ();
  template<typename Functor>  ();
  template<typename Functor>  ();
   () ;
   () ;
   () ;
   ();
   ();
};

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. ();

    Constructs a spsc_queue

    Requires:

    spsc_queue must be configured to be sized at compile-time

  2. template<typename U, typename Enabler> 
      ();

    Constructs a spsc_queue with a custom allocator

    [Note] 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> 
      ();

    Constructs a spsc_queue with a custom allocator

    [Note] 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> 
      ( 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> 
      ( element_count, 
                  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> 
      ( element_count,  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 &) = ;
  8. spsc_queue & (spsc_queue &) = ;
  9. (spsc_queue &&) = ;
  10. spsc_queue & (spsc_queue &&) = ;
  11.  ( 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.

  12.  ( 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.

  13.  ();

    Pops one object from ringbuffer.

    [Note] 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> 
       ( ret);

    Pops one object from ringbuffer.

    [Note] 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.  ();

    Pops object from spsc_queue, returning a std::optional<>

    [Note] Note

    Thread-safe and non-blocking

    Returns:

    std::optional with value if successful, std::nullopt if spsc_queue is empty.

  16. template<typename U>  ();

    Pops object from spsc_queue, returning a std::optional<>

    [Note] 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.  ( t,  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

  18. template< size>  ( 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

  19. template< Extent>  ( t);

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

  20. template<typename ConstIterator> 
       ( begin,  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

  21.  ( ret,  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 from the spsc_queue

    Returns:

    number of popped items

  22. template< size>  ( 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 from the spsc_queue

    Returns:

    number of popped items

  23. template<typename 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 from the spsc_queue

    Returns:

    number of popped items

  24. template<typename 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

  25. template<typename 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

  26.  () ;

    get number of elements that are available for read

    [Note] 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.  () ;

    get write space to write elements

    [Note] 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.  () ;

    get reference to element in the front of the queue

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

    [Note] 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.  ();

    get reference to element in the front of the queue

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

    [Note] 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.  ();

    reset the ringbuffer

    [Note] Note

    Not thread-safe


PrevUpHomeNext