kNet::WaitFreeQueue< T > Class Template Reference

A wait-free queue for communication unidirectionally between two threads. More...

#include <WaitFreeQueue.h>

List of all members.

Public Member Functions
	WaitFreeQueue (size_t maxElements)
int	Capacity () const
	Returns the total capacity of the queue, i.e.
int	CapacityLeft () const
	Returns the number of items that can still be inserted in the queue, i.e.
bool	Insert (const T &value)
	Inserts the new value into the queue. Can be called only by a single producer thread.
void	InsertWithResize (const T &value)
	Inserts the new value into the queue.
void	Resize (size_t newSize)
	Re-allocates the queue to the new maximum size.
void	DoubleCapacity ()
	Resizes this queue to hold twice the amount of maximum elements.
T *	Front ()
	Returns a pointer to the first item in the queue. Can be called only from a single consumer thread.
T *	ItemAt (int index)
	Returns a pointer to the item at the given index. Can be called only from a single consumer thread.
const T *	ItemAt (int index) const
	Returns a pointer to the item at the given index. Can be called only from a single consumer thread.
bool	Contains (const T &item) const
	Returns true if the given element exists in the queue. Can be called only from a single consumer thread.
void	EraseItemAt (int index)
	Removes the element at the given index.
const T *	Front () const
	Returns a pointer to the first item in the queue. Can be called only from a single consumer thread.
T	TakeFront ()
	Returns a copy of the first item in the queue and pops that item off the queue. Can be called only from a single consumer thread.
void	Clear ()
	Removes all elements in the queue.
unsigned long	Size () const
	Returns the number of elements currently filled in the queue. Can be called from either the consumer or producer thread.
void	PopFront ()
	Removes the first item in the queue. Can be called only from a single consumer thread.

---

Detailed Description

template<typename T>
class kNet::WaitFreeQueue< T >

A wait-free queue for communication unidirectionally between two threads.

This data structure is useful for simple and efficient lockless data/message passing between two-threads. It is implemented using a lockless circular ring buffer, and has the following properties:

• At most one thread can act as a publisher/producer/writer and call Insert() to add new items to the queue.
• At most one thread can consume/read the items from the queue by calling Front() and PopFront().
• Does not use locks or spin-waits, and is hence wait-free.
• Does not perform any memory allocation after initialization.
• Only POD types are supported. If you need non-POD objects, store pointers to objects instead.
• The queue has a fixed upper size that must be a power-of-2 and must be speficied in the constructor.

---

Constructor & Destructor Documentation

template<typename T>

kNet::WaitFreeQueue< T >::WaitFreeQueue

(

size_t

maxElements

)

[inline, explicit]

Parameters:

maxElements

A power-of-2 number, > 2, that specifies the size of the ring buffer to construct. The number of elements the queue can store is maxElements-1.

---

Member Function Documentation

template<typename T>

int kNet::WaitFreeQueue< T >::Capacity

(

)

const [inline]

Returns the total capacity of the queue, i.e.

the total maximum number of items that can be contained in it. Thread-safe.

Referenced by kNet::WaitFreeQueue< NetworkMessage * >::CapacityLeft().

template<typename T>

int kNet::WaitFreeQueue< T >::CapacityLeft

(

)

const [inline]

Returns the number of items that can still be inserted in the queue, i.e.

the total space left. Thread-safe.

template<typename T>

void kNet::WaitFreeQueue< T >::InsertWithResize

(

const T &

value

)

[inline]

Inserts the new value into the queue.

Note:

This function is not thread-safe. Do not call this if you cannot guarantee that the other thread will not be accessing the queue at the same time.

Referenced by kNet::MessageConnection::AcceptOutboundMessages(), kNet::MessageConnection::EndAndQueueMessage(), and kNet::MessageConnection::SplitAndQueueMessage().

template<typename T>

void kNet::WaitFreeQueue< T >::Resize

(

size_t

newSize

)

[inline]

Re-allocates the queue to the new maximum size.

All old elements are copied over.

Note:

This function is not thread-safe. Do not call this if you cannot guarantee that the other thread will not be accessing the queue at the same time.

Referenced by kNet::WaitFreeQueue< NetworkMessage * >::DoubleCapacity().

template<typename T>

void kNet::WaitFreeQueue< T >::DoubleCapacity

(

)

[inline]

Resizes this queue to hold twice the amount of maximum elements.

Note:

This function is not thread-safe. Do not call this if you cannot guarantee that the other thread will not be accessing the queue at the same time.

Referenced by kNet::WaitFreeQueue< NetworkMessage * >::InsertWithResize().

template<typename T>

void kNet::WaitFreeQueue< T >::EraseItemAt

(

int

index

)

[inline]

Removes the element at the given index.

Note:

Not thread-safe.

template<typename T>

void kNet::WaitFreeQueue< T >::Clear

(

)

[inline]

Removes all elements in the queue.

Does not call dtors for removed objects, as this queue is only for POD types. Can be called only from a single consumer thread.

---

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

• C:/knet/include/kNet/WaitFreeQueue.h