it implements a producer/consumer(s) queue design pattern. More...

#include <NPLMessageQueue.h>

Inheritance diagram for NPL::concurrent_ptr_queue< Data, Condition >:

Public Types
enum	BufferStatus { BufferOverFlow = 0, BufferFull = 1, BufferNormal = 2, BufferEmpty = 3, BufferFirst = 3 }

Public Member Functions
	concurrent_ptr_queue (size_type capacity)

void	SetUseEvent (bool bUseEvent)
	whether to use event to inform consumer when new data items are added to the queue. More...

BufferStatus	try_push (value_type &item)
	try push to back of the queue. More...

BufferStatus	try_push_get_front (value_type &item, value_type **ppFrontItem)
	same as try_push, except that it also returns pointer to the front object. More...

void	push (value_type &data)
	add a data item to the back of the queue. More...

void	push_front (value_type &data)
	add a data item to the front of the queue. More...

bool	try_pop (value_type &popped_value)

void	wait_and_pop (value_type &popped_value)

void	wait (int nMessageCount=-1)
	simply wait for the next message to arrive. More...

value_type	peek (size_type nIndex)

bool	try_pop_at (size_type nIndex, value_type &popped_value)
	pop message at given index. More...

value_type *	try_front ()

bool	try_next (value_type **ppValueFront)
	try pop from the front of the queue and return the front object after the pop. More...

bool	empty () const

bool	full () const

size_type	size () const
	Get the number of elements currently stored in the circular_buffer.

size_type	capacity () const
	Get the number of elements that can be stored in the circular_buffer.

void	set_capacity (size_type new_capacity)
	Set the max number of elements that can be stored in the circular_buffer.

Protected Types
typedef boost::circular_buffer< Data >	container_type

typedef container_type::size_type	size_type

typedef container_type::value_type	value_type

Protected Attributes
boost::mutex	m_mutex

Condition	m_condition_variable

bool	m_use_event
	whether to use event to inform consumer when new data items are added to the queue. More...

container_type	m_container

Detailed Description

template<typename Data, typename Condition>
class NPL::concurrent_ptr_queue< Data, Condition >

it implements a producer/consumer(s) queue design pattern.

this is similar to concurrent_queue, except it will call reset() after push and pop operation.

Note: : typename Data must be shared_ptr or intrusive_ptr with reset() method, because we will call reset when push and pop operation returns. This allows non-thread-safe reference counted object to work as data items. for an example, please see NPLMessage_ptr.

Member Function Documentation

§ peek()

template<typename Data, typename Condition>

value_type NPL::concurrent_ptr_queue< Data, Condition >::peek ( size_type nIndex )

inline

Returns: : get a pointer to the object at given index, if exist, or NULL.

Note: this is thread safe, however the returned object may be invalid if it is popped by another thread when you use it.

§ push()

template<typename Data, typename Condition>

void NPL::concurrent_ptr_queue< Data, Condition >::push ( value_type & data )

inline

add a data item to the back of the queue.

if buffer is full, the more recent messages remain in the queue.

Parameters

data	the object to add. It is usually a reference counted object. item.reset() is called when the function is returned. so one should not use item any more after the function returns.

§ push_front()

template<typename Data, typename Condition>

void NPL::concurrent_ptr_queue< Data, Condition >::push_front ( value_type & data )

inline

add a data item to the front of the queue.

This ensures that message is always added even queue is full, where the recent message are dropped. This function is only used to insert high priority command, otherwise use push() function instead.

Parameters

data	the object to add. It is usually a reference counted object. item.reset() is called when the function is returned. so one should not use item any more after the function returns.

§ SetUseEvent()

template<typename Data, typename Condition>

void NPL::concurrent_ptr_queue< Data, Condition >::SetUseEvent ( bool bUseEvent )

inline

whether to use event to inform consumer when new data items are added to the queue.

Default to true. if one uses polling,such as in the main game thread, there is no need to enable use_event. when enabled, there is a performance hit.

§ try_front()

template<typename Data, typename Condition>

value_type* NPL::concurrent_ptr_queue< Data, Condition >::try_front ( )

inline

Returns: : get a pointer to the front object if exist, or NULL.

Note: this is thread safe, however the returned object may be invalid if it is popped by another thread when you use it.

§ try_next()

template<typename Data, typename Condition>

bool NPL::concurrent_ptr_queue< Data, Condition >::try_next ( value_type ** ppValueFront )

inline

try pop from the front of the queue and return the front object after the pop.

Parameters

ppValueFront get a pointer to the front object after the operation. Please note the returned object may be invalid if it is popped by another thread when you use it.

Returns: : return true if succeed, false if queue is empty.

Note: : thread safe

§ try_pop_at()

template<typename Data, typename Condition>

bool NPL::concurrent_ptr_queue< Data, Condition >::try_pop_at	(	size_type	nIndex,
		value_type &	popped_value
	)

inline

pop message at given index.

usually we need to call peek() first.

Returns: true if popped.

§ try_push()

template<typename Data, typename Condition>

BufferStatus NPL::concurrent_ptr_queue< Data, Condition >::try_push ( value_type & item )

inline

try push to back of the queue.

Parameters

item	the object to add. It is usually a reference counted object. item.reset() is called when the function is returned. so one should not use item any more after the function returns.

Returns: : return buffer status after the item is added. If BufferOverFlow, it means adding is failed; if BufferFirst, this is the first item added. if BufferFull, the buffer is full after inserting the new one, in other cases, BufferNormal is returned.

Note: : thread safe

§ try_push_get_front()

template<typename Data, typename Condition>

BufferStatus NPL::concurrent_ptr_queue< Data, Condition >::try_push_get_front	(	value_type &	item,
		value_type **	ppFrontItem
	)

inline

same as try_push, except that it also returns pointer to the front object.

Parameters

item	the object to add. It is usually a reference counted object. item.reset() is called when the function is returned. so one should not use item any more after the function returns.
ppFrontItem	there is no guarantee that the front object pointer is valid after return. please ensure no other thread is popping items when you are accessing the front item or when the this function is called.

§ wait()

template<typename Data, typename Condition>

void NPL::concurrent_ptr_queue< Data, Condition >::wait ( int nMessageCount = -1 )

inline

simply wait for the next message to arrive.

the caller may be calling try_XXX() afterwards.

Parameters

nMessageCount if not negative, this function will immediately return when the message queue size not equal to this value.

Member Data Documentation

§ m_use_event

template<typename Data, typename Condition>

bool NPL::concurrent_ptr_queue< Data, Condition >::m_use_event

protected

whether to use event to inform consumer when new data items are added to the queue.

Default to true. if one uses polling,such as in the main game thread, there is no need to enable use_event. when enabled, there is a performance hit.

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

Client/trunk/ParaEngineClient/NPL/NPLMessageQueue.h

Public Types

Public Member Functions

Protected Types

Protected Attributes

Detailed Description

template<typename Data, typename Condition> class NPL::concurrent_ptr_queue< Data, Condition >

Member Function Documentation

§ peek()

§ push()

§ push_front()

§ SetUseEvent()

§ try_front()

§ try_next()

§ try_pop_at()

§ try_push()

§ try_push_get_front()

§ wait()

Member Data Documentation

§ m_use_event

template<typename Data, typename Condition>
class NPL::concurrent_ptr_queue< Data, Condition >