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

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_type *	front ()
	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 :

cds::container::WeakRingBuffer< Foo > myRing;
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:

cds::container::WeakRingBuffer<std::string> ringbuf;
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:

cds::container::WeakRingBuffer<std::string> ringbuf;
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/container/weak_ringbuffer.h