cds  2.3.0
cds::container::WeakRingBuffer< T, Traits > Class Template Reference

Single-producer single-consumer ring buffer. More...

#include <cds/container/weak_ringbuffer.h>

Inheritance diagram for cds::container::WeakRingBuffer< T, Traits >:
cds::bounded_container

Data Structures

struct  rebind
 Rebind template arguments. More...
 

Public Types

typedef T value_type
 Value type to be stored in the ring buffer.
 
typedef Traits traits
 Ring buffer traits.
 
typedef traits::memory_model memory_model
 Memory ordering. See cds::opt::memory_model option.
 
typedef traits::value_cleaner value_cleaner
 Value cleaner, see weak_ringbuffer::traits::value_cleaner.
 

Public Member Functions

 WeakRingBuffer (size_t capacity=0)
 Creates the ring buffer of capacity. More...
 
 ~WeakRingBuffer ()
 Destroys the ring buffer.
 
template<typename Q , typename CopyFunc >
bool push (Q *arr, size_t count, CopyFunc copy)
 Batch push - push array arr of size count. More...
 
template<typename Q >
std::enable_if< std::is_constructible< value_type, Q >::value, bool >::type push (Q *arr, size_t count)
 Batch push - push array arr of size count with assignment as copy functor. More...
 
template<typename... Args>
std::enable_if< std::is_constructible< value_type, Args... >::value, bool >::type emplace (Args &&... args)
 Push one element created from args. More...
 
template<typename Func >
bool enqueue_with (Func f)
 Enqueues data to the ring using a functor. More...
 
bool enqueue (value_type const &val)
 Enqueues val value into the queue. More...
 
bool enqueue (value_type &&val)
 Enqueues val value into the queue, move semantics.
 
bool push (value_type const &val)
 Synonym for enqueue( value_type const& )
 
bool push (value_type &&val)
 Synonym for enqueue( value_type&& )
 
template<typename Func >
bool push_with (Func f)
 Synonym for enqueue_with()
 
template<typename Q , typename CopyFunc >
bool pop (Q *arr, size_t count, CopyFunc copy)
 Batch pop count element from the ring buffer into arr. More...
 
template<typename Q >
std::enable_if< std::is_assignable< Q &, value_type const & >::value, bool >::type pop (Q *arr, size_t count)
 Batch pop - push array arr of size count with assignment as copy functor. More...
 
template<typename Q >
std::enable_if< std::is_assignable< Q &, value_type const & >::value, bool >::type dequeue (Q &val)
 Dequeues an element from the ring to val. More...
 
template<typename Q >
std::enable_if< std::is_assignable< Q &, value_type const & >::value, bool >::type pop (Q &val)
 Synonym for dequeue( Q& )
 
template<typename Func >
bool dequeue_with (Func f)
 Dequeues a value using a functor. More...
 
template<typename Func >
bool pop_with (Func f)
 Synonym for dequeue_with()
 
value_typefront ()
 Gets pointer to first element of ring buffer. More...
 
bool pop_front ()
 Removes front element of ring-buffer. More...
 
void clear ()
 Clears the ring buffer (only consumer can call this function!)
 
bool empty () const
 Checks if the ring-buffer is empty.
 
bool full () const
 Checks if the ring-buffer is full.
 
size_t size () const
 Returns the current size of ring buffer.
 
size_t capacity () const
 Returns capacity of the ring buffer.
 

Detailed Description

template<typename T, typename Traits = weak_ringbuffer::traits>
class cds::container::WeakRingBuffer< T, Traits >

Single-producer single-consumer ring buffer.

Source: [2013] Nhat Minh Le, Adrien Guatto, Albert Cohen, Antoniu Pop. Correct and Effcient Bounded FIFO Queues. [Research Report] RR-8365, INRIA. 2013. <hal-00862450>

Ring buffer is a bounded queue. Additionally, WeakRingBuffer supports batch operations - you can push/pop an array of elements.

There are a specialization WeakRingBuffer<void, Traits> that is not a queue but a "memory pool" between producer and consumer threads. WeakRingBuffer<void> supports variable-sized data.

Warning
: WeakRingBuffer is developed for 64-bit architecture. 32-bit platform must provide support for 64-bit atomics.

Constructor & Destructor Documentation

◆ WeakRingBuffer()

template<typename T , typename Traits = weak_ringbuffer::traits>
cds::container::WeakRingBuffer< T, Traits >::WeakRingBuffer ( size_t  capacity = 0)
inline

Creates the ring buffer of capacity.

For cds::opt::v::uninitialized_static_buffer the nCapacity parameter is ignored.

If the buffer capacity is a power of two, lightweight binary arithmetics is used instead of modulo arithmetics.

Member Function Documentation

◆ dequeue()

template<typename T , typename Traits = weak_ringbuffer::traits>
template<typename Q >
std::enable_if< std::is_assignable<Q&, value_type const&>::value, bool>::type cds::container::WeakRingBuffer< T, Traits >::dequeue ( Q &  val)
inline

Dequeues an element from the ring to val.

The function is available only if std::is_assignable<Q&, value_type const&>::value is true.

Returns false if the ring is full or true otherwise.

◆ dequeue_with()

template<typename T , typename Traits = weak_ringbuffer::traits>
template<typename Func >
bool cds::container::WeakRingBuffer< T, Traits >::dequeue_with ( Func  f)
inline

Dequeues a value using a functor.

Func is a functor called to copy dequeued value. The functor takes one argument - a reference to removed node:

cds:container::WeakRingBuffer< Foo > myRing;
Bar bar;
myRing.dequeue_with( [&bar]( Foo& src ) { bar = std::move( src );});

Returns true if the ring is not empty, false otherwise. The functor is called only if the ring is not empty.

◆ emplace()

template<typename T , typename Traits = weak_ringbuffer::traits>
template<typename... Args>
std::enable_if< std::is_constructible<value_type, Args...>::value, bool>::type cds::container::WeakRingBuffer< T, Traits >::emplace ( Args &&...  args)
inline

Push one element created from args.

The function is available only if std::is_constructible<value_type, Args...>::value is true.

Returns false if the ring is full or true otherwise.

◆ enqueue()

template<typename T , typename Traits = weak_ringbuffer::traits>
bool cds::container::WeakRingBuffer< T, Traits >::enqueue ( value_type const &  val)
inline

Enqueues val value into the queue.

The new queue item is created by calling placement new in free cell. Returns true if success, false if the ring is full.

◆ enqueue_with()

template<typename T , typename Traits = weak_ringbuffer::traits>
template<typename Func >
bool cds::container::WeakRingBuffer< T, Traits >::enqueue_with ( Func  f)
inline

Enqueues data to the ring using a functor.

Func is a functor called to copy a value to the ring element. The functor f takes one argument - a reference to a empty cell of type value_type :

Bar bar;
myRing.enqueue_with( [&bar]( Foo& dest ) { dest = std::move(bar); } );

◆ front()

template<typename T, typename Traits = weak_ringbuffer::traits>
value_type* cds::container::WeakRingBuffer< T, Traits >::front ( )
inline

Gets pointer to first element of ring buffer.

If the ring buffer is empty, returns nullptr

The function is thread-safe since there is only one consumer. Recall, WeakRingBuffer is single-producer/single consumer container.

◆ pop() [1/2]

template<typename T, typename Traits = weak_ringbuffer::traits>
template<typename Q , typename CopyFunc >
bool cds::container::WeakRingBuffer< T, Traits >::pop ( Q *  arr,
size_t  count,
CopyFunc  copy 
)
inline

Batch pop count element from the ring buffer into arr.

CopyFunc is a per-element copy functor: for each element of arr copy( arr[i], source ) is called. The CopyFunc signature:

void copy_func( Q& dest, value_type& elemen );

Returns true if success or false if not enough space in the ring

◆ pop() [2/2]

template<typename T, typename Traits = weak_ringbuffer::traits>
template<typename Q >
std::enable_if< std::is_assignable<Q&, value_type const&>::value, bool>::type cds::container::WeakRingBuffer< T, Traits >::pop ( Q *  arr,
size_t  count 
)
inline

Batch pop - push array arr of size count with assignment as copy functor.

This function is equivalent for:

pop( arr, count, []( Q& dest, value_type& src ) { dest = src; } );

The function is available only if std::is_assignable<Q&, value_type const&>::value is true.

Returns true if success or false if not enough space in the ring

◆ pop_front()

template<typename T, typename Traits = weak_ringbuffer::traits>
bool cds::container::WeakRingBuffer< T, Traits >::pop_front ( )
inline

Removes front element of ring-buffer.

If the ring-buffer is empty, returns false. Otherwise, pops the first element from the ring.

◆ push() [1/2]

template<typename T, typename Traits = weak_ringbuffer::traits>
template<typename Q , typename CopyFunc >
bool cds::container::WeakRingBuffer< T, Traits >::push ( Q *  arr,
size_t  count,
CopyFunc  copy 
)
inline

Batch push - push array arr of size count.

CopyFunc is a per-element copy functor: for each element of arr copy( dest, arr[i] ) is called. The CopyFunc signature:

void copy_func( value_type& element, Q const& source );

Here element is uninitialized so you should construct it using placement new if needed; for example, if the element type is str::string and Q is char const*, copy functor can be:

char const* arr[10];
ringbuf.push( arr, 10,
[]( std::string& element, char const* src ) {
new( &element ) std::string( src );
});

You may use move semantics if appropriate:

std::string arr[10];
ringbuf.push( arr, 10,
[]( std::string& element, std:string& src ) {
new( &element ) std::string( std::move( src ));
});

Returns true if success or false if not enough space in the ring

◆ push() [2/2]

template<typename T, typename Traits = weak_ringbuffer::traits>
template<typename Q >
std::enable_if< std::is_constructible<value_type, Q>::value, bool>::type cds::container::WeakRingBuffer< T, Traits >::push ( Q *  arr,
size_t  count 
)
inline

Batch push - push array arr of size count with assignment as copy functor.

This function is equivalent for:

push( arr, count, []( value_type& dest, Q const& src ) { dest = src; } );

The function is available only if std::is_constructible<value_type, Q>::value is true.

Returns true if success or false if not enough space in the ring


The documentation for this class was generated from the following file:

cds 2.3.0 Developed by Maxim Khizhinsky aka khizmax 2007 - 2017
Autogenerated Mon Jul 31 2017 10:10:56 by Doxygen 1.8.13