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

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/container/weak_ringbuffer.h