AtomicBufferQueue< T, TSize > Class Template Reference

#include <evo/atomic_buffer_queue.h>

Detailed Description

template<class T, class TSize = SizeT>
class evo::AtomicBufferQueue< T, TSize >

Fast buffer-based queue, implemented with a ring-buffer.

Template Parameters

T	Item type to use, copied with assignment operator
TSize	Size type to use for queue size (must be unsigned integer) – default: SizeT

Features

• This is lock free and thread safe, though pop() may only be called by 1 consumer thread
• Efficient buffer based queue, especially for simple (POD or Byte-Copy) types
• This allocates a fixed size buffer and is not resizable, size is always a power of 2
  • For a dynamic size queue (or stack) see: List
• Adding items does not allocate memory (though this calls the item assignment operator, which could)
• Popped (removed or cleared) items are left as-is in buffer, to be overwritten as new items are added
• All operations take constant time, except copy constructor and assignment operator which often take linear time (to copy items)

Note that this is not a full EvoContainer and doesn't have iterators.

Example

#include <evo/atomic_buffer_queue.h>
using namespace evo;

int main() {
    AtomicBufferQueue<int> queue(20); // rounds to 32 (power of 2)

    queue.add(1);
    queue.add(2);
    queue.add(3);

    int a = 0, b = 0, c = 0;
    queue.pop(a);   // set to 1
    queue.pop(b);   // set to 2
    queue.pop(c);   // set to 3

    return 0;
}

Public Types
typedef T	Item
	Item type. More...
typedef TSize	Size
	Queue size integer type (always unsigned) More...
typedef AtomicBufferQueue< T, TSize >	This
	This type More...

Public Member Functions
	AtomicBufferQueue (Size size=DEFAULT_SIZE)
	Constructor, sets buffer size. More...
	~AtomicBufferQueue ()
	Destructor. More...
void	add (typename DataCopy< Item >::PassType item)
	Add item to queue. More...
void	add_commit (uint64 seq)
	Commit adding an item. More...
Item &	add_start (uint64 &seq)
	Start adding item to queue directly. More...
void	clear ()
	Clear all items from queue, making it empty. More...
bool	empty () const
	Get whether queue is empty. More...
bool	full () const
	Get whether queue is full. More...
bool	pop (Item &item)
	Pop oldest item from queue. More...
Size	size () const
	Get buffer size. More...
Size	used () const
	Get used item count. More...

Static Public Attributes
static const Size	DEFAULT_SIZE = 128
	Default size to use. More...

Member Typedef Documentation

Item

typedef T Item

Item type.

Size

typedef TSize Size

Queue size integer type (always unsigned)

This

typedef AtomicBufferQueue<T,TSize> This

This type

Constructor & Destructor Documentation

AtomicBufferQueue()

AtomicBufferQueue ( Size  size = DEFAULT_SIZE )

inline

Constructor, sets buffer size.

Parameters

size	Buffer size to use as item count, rouned to next power of 2 if needed

~AtomicBufferQueue()

~AtomicBufferQueue ( )

inline

Destructor.

Member Function Documentation

add()

void add ( typename DataCopy< Item >::PassType  item )

inline

Add item to queue.

• Thread safe
• This uses Item::operator=() to copy the item to queue memory
  • Copying should be as fast as possible (use memcpy() and/or swap pointers) – adding further items will block (semi-busy wait) while this is copying
  • For best perforamce, copying should not allocate any memory or involve any expensive processing
  • Not exception safe – item assignment operator must not throw
  • For more control over copying the item see add_start() and add_commit()

Parameters

item	Item to add, copied with assignment operator

add_commit()

void add_commit ( uint64  seq )

inline

Commit adding an item.

• Thread safe
• See add_start(), which must be called first to get the item to overwrite and sequence number to pass here
• Call this immediately after overwriting the claimed item
• Caution: Every add_start() call must have a subsequent matching add_commit() with the same sequence number, otherwise results are undefined (likely hang)

Parameters

seq	Item sequence number from add_start()

add_start()

Item& add_start ( uint64 &  seq )

inline

Start adding item to queue directly.

• Thread safe
• Call this to claim an item, then overwrite the item, then call add_commit() to finish adding the item
  • This returns a reference to the claimed item, which should be overwritten, and also returns (via out param) a sequence number to pass to add_commit()
  • Copying should be as fast as possible (use memcpy() and/or swap pointers) – adding further items will block (semi-busy wait) until add_commit() is called with the same sequence number
  • For best perforamce, copying should not allocate any memory or involve any expensive processing
  • Caution: Every add_start() call must have a subsequent matching add_commit() with the same sequence number, otherwise results are undefined (likely hang)
  • Caution: Make sure an exception while setting the item doesn't prevent the call to add_commit()

Parameters

seq	Stores sequence number for added item, pass this to add_commit() [out]

Returns

Reference to item in queue, which should be reset – items are reused so the state of the item is undefined

clear()

void clear ( )

inline

Clear all items from queue, making it empty.

• Caution: Not thread safe while an add*() method is being called by another thread, otherwise thread safe

empty()

bool empty ( ) const

inline

Get whether queue is empty.

• Thread safe

Returns

Whether empty, same as used() == 0

full()

bool full ( ) const

inline

Get whether queue is full.

• Thread safe

Returns

Whether full, same as used() == size()

pop()

bool pop ( Item &  item )

inline

Pop oldest item from queue.

• This doesn't really remove the item, but copies it and leaves it as-is in buffer to be overwritten later
• This uses Item::operator=() to copy the item from queue memory
  • Copying should be as fast as possible (use memcpy() and/or swap pointers) – adding further items will block (semi-busy wait) while the queue is full
  • Exception safe: Queue is unchanged if item copy throws (though ideally it should not throw)
• Thread safety: Only call from 1 consumer thread at a time, otherwise results are undefined

Parameters

item	Stores popped item, copied with assignment operator [out]

Returns

Whether item popped, false if queue is empty

size()

Size size ( ) const

inline

Get buffer size.

• Thread safe

Returns

Buffer size as item count, always a power of 2

used()

Size used ( ) const

inline

Get used item count.

• Thread safe

Returns

Item count used, 0 if queue is empty

Member Data Documentation

DEFAULT_SIZE

const Size DEFAULT_SIZE = 128

static

Default size to use.

---

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

• evo/atomic_buffer_queue.h