cds  2.3.1
cds::container::WeakRingBuffer< void, Traits > Class Template Reference

Single-producer single-consumer ring buffer for untyped variable-sized data. More...

#include <cds/container/weak_ringbuffer.h>

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

Public Types

typedef Traits traits
 Ring buffer traits.
 
typedef traits::memory_model memory_model
 Memory ordering. See cds::opt::memory_model option.
 

Public Member Functions

 WeakRingBuffer (size_t capacity=0)
 Creates the ring buffer of capacity bytes. More...
 
void * back (size_t size)
 [producer] Reserve size bytes More...
 
void push_back ()
 [producer] Push reserved bytes into ring More...
 
bool push_back (void const *data, size_t size)
 [producer] Push data of size bytes into ring More...
 
std::pair< void *, size_t > front ()
 [consumer] Get top data from the ring More...
 
bool pop_front ()
 [consumer] Pops top data More...
 
void clear ()
 [consumer] Clears the ring buffer
 
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 Traits = weak_ringbuffer::traits>
class cds::container::WeakRingBuffer< void, Traits >

Single-producer single-consumer ring buffer for untyped variable-sized data.

This SPSC ring-buffer is intended for data of variable size. The producer allocates a buffer from ring, you fill it with data and pushes them back to ring. The consumer thread reads data from front-end and then pops them:

// allocates 1M ring buffer
WeakRingBuffer<void> theRing( 1024 * 1024 );
void producer_thread()
{
// Get data of size N bytes
size_t size;
void* data;
while ( true ) {
// Get external data
std::tie( data, size ) = get_data();
if ( data == nullptr )
break;
// Allocates a buffer from the ring
void* buf = theRing.back( size );
if ( !buf ) {
std::cout << "The ring is full" << std::endl;
break;
}
memcpy( buf, data, size );
// Push data into the ring
theRing.push_back();
}
}
void consumer_thread()
{
while ( true ) {
auto buf = theRing.front();
if ( buf.first == nullptr ) {
std::cout << "The ring is empty" << std::endl;
break;
}
// Process data
process_data( buf.first, buf.second );
// Free buffer
theRing.pop_front();
}
}
Warning
: WeakRingBuffer is developed for 64-bit architecture. 32-bit platform must provide support for 64-bit atomics.

Constructor & Destructor Documentation

◆ WeakRingBuffer()

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

Creates the ring buffer of capacity bytes.

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

◆ back()

template<typename Traits = weak_ringbuffer::traits>
void* cds::container::WeakRingBuffer< void, Traits >::back ( size_t  size)
inline

[producer] Reserve size bytes

The function returns a pointer to reserved buffer of size bytes. If no enough space in the ring buffer the function returns nullptr.

After successful back() you should fill the buffer provided and call push_back():

// allocates 1M ring buffer
WeakRingBuffer<void> theRing( 1024 * 1024 );
void producer_thread()
{
// Get data of size N bytes
size_t size;1
void* data;
while ( true ) {
// Get external data
std::tie( data, size ) = get_data();
if ( data == nullptr )
break;
// Allocates a buffer from the ring
void* buf = theRing.back( size );
if ( !buf ) {
std::cout << "The ring is full" << std::endl;
break;
}
memcpy( buf, data, size );
// Push data into the ring
theRing.push_back();
}
}

◆ front()

template<typename Traits = weak_ringbuffer::traits>
std::pair<void*, size_t> cds::container::WeakRingBuffer< void, Traits >::front ( )
inline

[consumer] Get top data from the ring

If the ring is empty, the function returns nullptr in std:pair::first.

◆ pop_front()

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

[consumer] Pops top data

Typical consumer workloop:

// allocates 1M ring buffer
WeakRingBuffer<void> theRing( 1024 * 1024 );
void consumer_thread()
{
while ( true ) {
auto buf = theRing.front();
if ( buf.first == nullptr ) {
std::cout << "The ring is empty" << std::endl;
break;
}
// Process data
process_data( buf.first, buf.second );
// Free buffer
theRing.pop_front();
}
}

◆ push_back() [1/2]

template<typename Traits = weak_ringbuffer::traits>
void cds::container::WeakRingBuffer< void, Traits >::push_back ( )
inline

[producer] Push reserved bytes into ring

The function pushes reserved buffer into the ring. Afte this call, the buffer becomes visible by a consumer:

// allocates 1M ring buffer
WeakRingBuffer<void> theRing( 1024 * 1024 );
void producer_thread()
{
// Get data of size N bytes
size_t size;1
void* data;
while ( true ) {
// Get external data
std::tie( data, size ) = get_data();
if ( data == nullptr )
break;
// Allocates a buffer from the ring
void* buf = theRing.back( size );
if ( !buf ) {
std::cout << "The ring is full" << std::endl;
break;
}
memcpy( buf, data, size );
// Push data into the ring
theRing.push_back();
}
}

◆ push_back() [2/2]

template<typename Traits = weak_ringbuffer::traits>
bool cds::container::WeakRingBuffer< void, Traits >::push_back ( void const *  data,
size_t  size 
)
inline

[producer] Push data of size bytes into ring

This function invokes back( size ), memcpy( buf, data, size ) and push_back() in one call.


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

cds 2.3.1 Developed by Maxim Khizhinsky aka khizmax 2007 - 2017
Autogenerated Fri Sep 1 2017 08:47:11 by Doxygen 1.8.13