Base for a general purpose request / response style background work queue. More...

#include <OgreWorkQueue.h>

Inheritance diagram for Ogre::DefaultWorkQueueBase:

Classes
struct	OGRE_THREAD_WORKER_INHERIT
	Thread function. More...
class	RequestHandlerHolder
	Intermediate structure to hold a pointer to a request handler which provides insurance against the handler itself being disconnected while the list remains unchanged. More...
Public Types
typedef unsigned long long int	RequestID
	Numeric identifier for a request.
Public Member Functions
	DefaultWorkQueueBase (const String &name=StringUtil::BLANK)
	Constructor.
virtual	~DefaultWorkQueueBase ()
virtual void	_processNextRequest ()
	Process the next request on the queue.
virtual void	_threadMain ()=0
	Main function for each thread spawned.
virtual void	abortAllRequests ()
virtual void	abortPendingRequestsByChannel (uint16 channel)
virtual void	abortRequest (RequestID id)
virtual void	abortRequestsByChannel (uint16 channel)
virtual RequestID	addRequest (uint16 channel, uint16 requestType, const Any &rData, uint8 retryCount=0, bool forceSynchronous=false, bool idleThread=false)
virtual void	addRequestHandler (uint16 channel, RequestHandler *rh)
virtual void	addResponseHandler (uint16 channel, ResponseHandler *rh)
virtual uint16	getChannel (const String &channelName)
	Get a channel ID for a given channel name.
const String &	getName () const
	Get the name of the work queue.
virtual bool	getRequestsAccepted () const
virtual unsigned long	getResponseProcessingTimeLimit () const
virtual bool	getWorkersCanAccessRenderSystem () const
	Get whether worker threads will be allowed to access render system resources.
virtual size_t	getWorkerThreadCount () const
	Get the number of worker threads that this queue will start when startup() is called.
virtual bool	isPaused () const
virtual bool	isShuttingDown () const
	Returns whether the queue is trying to shut down.
void	operator delete (void *ptr)
void	operator delete (void ptr, void )
void	operator delete (void ptr, const char , int, const char *)
void	operator delete[] (void *ptr)
void	operator delete[] (void ptr, const char , int, const char *)
void *	operator new (size_t sz, const char file, int line, const char func)
	operator new, with debug line info
void *	operator new (size_t sz)
void *	operator new (size_t sz, void *ptr)
	placement operator new
void *	operator new[] (size_t sz, const char file, int line, const char func)
	array operator new, with debug line info
void *	operator new[] (size_t sz)
virtual void	processResponses ()
virtual void	removeRequestHandler (uint16 channel, RequestHandler *rh)
virtual void	removeResponseHandler (uint16 channel, ResponseHandler *rh)
virtual void	setPaused (bool pause)
virtual void	setRequestsAccepted (bool accept)
virtual void	setResponseProcessingTimeLimit (unsigned long ms)
virtual void	setWorkersCanAccessRenderSystem (bool access)
	Set whether worker threads will be allowed to access render system resources.
virtual void	setWorkerThreadCount (size_t c)
	Set the number of worker threads that this queue will start when startup() is called (default 1).
virtual void	shutdown ()=0
	Shut down the queue.
virtual void	startup (bool forceRestart=true)=0
	Start up the queue with the options that have been set.
Protected Types
typedef map< String, uint16 >::type	ChannelMap
typedef SharedPtr < RequestHandlerHolder >	RequestHandlerHolderPtr
typedef list < RequestHandlerHolderPtr > ::type	RequestHandlerList
typedef map< uint16, RequestHandlerList >::type	RequestHandlerListByChannel
typedef deque< Request * >::type	RequestQueue
typedef list< ResponseHandler * > ::type	ResponseHandlerList
typedef map< uint16, ResponseHandlerList >::type	ResponseHandlerListByChannel
typedef deque< Response * >::type	ResponseQueue
Protected Member Functions
void	addRequestWithRID (RequestID rid, uint16 channel, uint16 requestType, const Any &rData, uint8 retryCount)
	Put a Request on the queue with a specific RequestID.
virtual void	notifyWorkers ()=0
	Notify workers about a new request.
	OGRE_MUTEX (mChannelMapMutex)
	OGRE_MUTEX (mIdleMutex)
	OGRE_MUTEX (mRequestMutex)
	OGRE_MUTEX (mProcessMutex)
	OGRE_MUTEX (mResponseMutex)
	OGRE_RW_MUTEX (mRequestHandlerMutex)
bool	processIdleRequests ()
Response *	processRequest (Request *r)
void	processRequestResponse (Request *r, bool synchronous)
void	processResponse (Response *r)
Protected Attributes
bool	mAcceptRequests
ChannelMap	mChannelMap
Request *	mIdleProcessed
RequestQueue	mIdleRequestQueue
bool	mIdleThreadRunning
bool	mIsRunning
String	mName
uint16	mNextChannel
bool	mPaused
RequestQueue	mProcessQueue
RequestID	mRequestCount
RequestHandlerListByChannel	mRequestHandlers
RequestQueue	mRequestQueue
ResponseHandlerListByChannel	mResponseHandlers
ResponseQueue	mResponseQueue
unsigned long	mResposeTimeLimitMS
bool	mShuttingDown
WorkerFunc *	mWorkerFunc
bool	mWorkerRenderSystemAccess
size_t	mWorkerThreadCount

Detailed Description

Base for a general purpose request / response style background work queue.

Definition at line 360 of file OgreWorkQueue.h.

Member Typedef Documentation

typedef map<String, uint16>::type Ogre::WorkQueue::ChannelMap [protected, inherited]

Definition at line 73 of file OgreWorkQueue.h.

typedef SharedPtr<RequestHandlerHolder> Ogre::DefaultWorkQueueBase::RequestHandlerHolderPtr [protected]

Definition at line 534 of file OgreWorkQueue.h.

typedef list<RequestHandlerHolderPtr>::type Ogre::DefaultWorkQueueBase::RequestHandlerList [protected]

Definition at line 536 of file OgreWorkQueue.h.

typedef map<uint16, RequestHandlerList>::type Ogre::DefaultWorkQueueBase::RequestHandlerListByChannel [protected]

Definition at line 538 of file OgreWorkQueue.h.

typedef unsigned long long int Ogre::WorkQueue::RequestID [inherited]

Numeric identifier for a request.

Definition at line 79 of file OgreWorkQueue.h.

typedef deque<Request*>::type Ogre::DefaultWorkQueueBase::RequestQueue [protected]

Definition at line 465 of file OgreWorkQueue.h.

typedef list<ResponseHandler*>::type Ogre::DefaultWorkQueueBase::ResponseHandlerList [protected]

Definition at line 537 of file OgreWorkQueue.h.

typedef map<uint16, ResponseHandlerList>::type Ogre::DefaultWorkQueueBase::ResponseHandlerListByChannel [protected]

Definition at line 539 of file OgreWorkQueue.h.

typedef deque<Response*>::type Ogre::DefaultWorkQueueBase::ResponseQueue [protected]

Definition at line 466 of file OgreWorkQueue.h.

Constructor & Destructor Documentation

Ogre::DefaultWorkQueueBase::DefaultWorkQueueBase ( const String & name = StringUtil::BLANK )

Constructor.

Call startup() to initialise.

Parameters:

name	Optional name, just helps to identify logging output

virtual Ogre::DefaultWorkQueueBase::~DefaultWorkQueueBase ( ) [virtual]

Member Function Documentation

virtual void Ogre::DefaultWorkQueueBase::_processNextRequest ( ) [virtual]

Process the next request on the queue.

Remarks:: This method is public, but only intended for advanced users to call. The only reason you would call this, is if you were using your own thread to drive the worker processing. The thread calling this method will be the thread used to call the RequestHandler.

virtual void Ogre::DefaultWorkQueueBase::_threadMain ( ) [pure virtual]

Main function for each thread spawned.

Implemented in Ogre::DefaultWorkQueue, and Ogre::DefaultWorkQueue.

virtual void Ogre::DefaultWorkQueueBase::abortAllRequests ( ) [virtual]

Abort all previously issued requests.

Any requests still waiting to be processed will be removed from the queue. Any requests that are being processed will still complete.

Implements Ogre::WorkQueue.

virtual void Ogre::DefaultWorkQueueBase::abortPendingRequestsByChannel ( uint16 channel ) [virtual]

Abort all previously issued requests in a given channel.

Any requests still waiting to be processed of the given channel, will be removed from the queue. It will not remove requests, where the request handler is already called.

Parameters:

channel The type of request to be aborted

Implements Ogre::WorkQueue.

virtual void Ogre::DefaultWorkQueueBase::abortRequest ( RequestID id ) [virtual]

Abort a previously issued request.

If the request is still waiting to be processed, it will be removed from the queue.

Parameters:

id	The ID of the previously issued request.

Implements Ogre::WorkQueue.

virtual void Ogre::DefaultWorkQueueBase::abortRequestsByChannel ( uint16 channel ) [virtual]

Abort all previously issued requests in a given channel.

Any requests still waiting to be processed of the given channel, will be removed from the queue. Requests which are processed, but response handler is not called will also be removed.

Parameters:

channel The type of request to be aborted

Implements Ogre::WorkQueue.

virtual RequestID Ogre::DefaultWorkQueueBase::addRequest	(	uint16	channel,
		uint16	requestType,
		const Any &	rData,
		uint8	retryCount = `0`,
		bool	forceSynchronous = `false`,
		bool	idleThread = `false`
	)		`[virtual]`

Add a new request to the queue.

Parameters:

channel	The channel this request will go into = 0; the channel is the top-level categorisation of the request
requestType	An identifier that's unique within this queue which identifies the type of the request (user decides the actual value)
rData	The data required by the request process.
retryCount	The number of times the request should be retried if it fails.
forceSynchronous	Forces the request to be processed immediately even if threading is enabled.
idleThread	Request should be processed on the idle thread. Idle requests will be processed on a single worker thread. You should use this in the following situations: 1. If a request handler can't process multiple requests in parallel. 2. If you add lot of requests, but you want to keep the game fast. 3. If you have lot of more important threads. (example: physics).

Returns:: The ID of the request that has been added

Implements Ogre::WorkQueue.

virtual void Ogre::DefaultWorkQueueBase::addRequestHandler	(	uint16	channel,
		RequestHandler *	rh
	)		`[virtual]`

Add a request handler instance to the queue.

Remarks:: Every queue must have at least one request handler instance for each channel in which requests are raised. If you add more than one handler per channel, then you must implement canHandleRequest differently in each if you wish them to respond to different requests.

Parameters:

channel	The channel for requests you want to handle
rh	Your handler

Implements Ogre::WorkQueue.

void Ogre::DefaultWorkQueueBase::addRequestWithRID	(	RequestID	rid,
		uint16	channel,
		uint16	requestType,
		const Any &	rData,
		uint8	retryCount
	)		`[protected]`

Put a Request on the queue with a specific RequestID.

virtual void Ogre::DefaultWorkQueueBase::addResponseHandler	(	uint16	channel,
		ResponseHandler *	rh
	)		`[virtual]`

Add a response handler instance to the queue.

Remarks:: Every queue must have at least one response handler instance for each channel in which requests are raised. If you add more than one, then you must implement canHandleResponse differently in each if you wish them to respond to different responses.

Parameters:

channel	The channel for responses you want to handle
rh	Your handler

Implements Ogre::WorkQueue.

virtual uint16 Ogre::WorkQueue::getChannel ( const String & channelName ) [virtual, inherited]

Get a channel ID for a given channel name.

Remarks:: Channels are assigned on a first-come, first-served basis and are not persistent across application instances. This method allows applications to not worry about channel clashes through manually assigned channel numbers.

const String& Ogre::DefaultWorkQueueBase::getName ( ) const

Get the name of the work queue.

virtual bool Ogre::DefaultWorkQueueBase::getRequestsAccepted ( ) const [virtual]

Returns whether requests are being accepted right now.

Implements Ogre::WorkQueue.

virtual unsigned long Ogre::DefaultWorkQueueBase::getResponseProcessingTimeLimit ( ) const [virtual]

Get the time limit imposed on the processing of responses in a single frame, in milliseconds (0 indicates no limit).

Implements Ogre::WorkQueue.

Definition at line 455 of file OgreWorkQueue.h.

virtual bool Ogre::DefaultWorkQueueBase::getWorkersCanAccessRenderSystem ( ) const [virtual]

Get whether worker threads will be allowed to access render system resources.

Accessing render system resources from a separate thread can require that a context is maintained for that thread. Also, it requires that the render system is running in threadsafe mode, which only happens when OGRE_THREAD_SUPPORT=1. This option defaults to false, which means that threads can not use GPU resources, and the render system can work in non-threadsafe mode, which is more efficient.

virtual size_t Ogre::DefaultWorkQueueBase::getWorkerThreadCount ( ) const [virtual]

Get the number of worker threads that this queue will start when startup() is called.

virtual bool Ogre::DefaultWorkQueueBase::isPaused ( ) const [virtual]

Return whether the queue is paused ie not sending more work to workers.

Implements Ogre::WorkQueue.

virtual bool Ogre::DefaultWorkQueueBase::isShuttingDown ( ) const [virtual]

Returns whether the queue is trying to shut down.

Definition at line 422 of file OgreWorkQueue.h.

virtual void Ogre::DefaultWorkQueueBase::notifyWorkers ( ) [protected, pure virtual]

Notify workers about a new request.

Implemented in Ogre::DefaultWorkQueue, and Ogre::DefaultWorkQueue.

Ogre::WorkQueue::OGRE_MUTEX ( mChannelMapMutex ) [protected, inherited]

Ogre::DefaultWorkQueueBase::OGRE_MUTEX ( mIdleMutex ) [protected]

Ogre::DefaultWorkQueueBase::OGRE_MUTEX ( mRequestMutex ) [protected]

Ogre::DefaultWorkQueueBase::OGRE_MUTEX ( mProcessMutex ) [protected]

Ogre::DefaultWorkQueueBase::OGRE_MUTEX ( mResponseMutex ) [protected]

Ogre::DefaultWorkQueueBase::OGRE_RW_MUTEX ( mRequestHandlerMutex ) [protected]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete ( void * ptr ) [inherited]

Definition at line 96 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete	(	void *	ptr,
		void *
	)		`[inherited]`

Definition at line 102 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete	(	void *	ptr,
		const char *	,
		int	,
		const char *
	)		`[inherited]`

Definition at line 108 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete[] ( void * ptr ) [inherited]

Definition at line 113 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete[]	(	void *	ptr,
		const char *	,
		int	,
		const char *
	)		`[inherited]`

Definition at line 119 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new	(	size_t	sz,
		const char *	file,
		int	line,
		const char *	func
	)		`[inherited]`

operator new, with debug line info

Definition at line 68 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new ( size_t sz ) [inherited]

Definition at line 73 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new	(	size_t	sz,
		void *	ptr
	)		`[inherited]`

placement operator new

Definition at line 79 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new[]	(	size_t	sz,
		const char *	file,
		int	line,
		const char *	func
	)		`[inherited]`

array operator new, with debug line info

Definition at line 86 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new[] ( size_t sz ) [inherited]

Definition at line 91 of file OgreMemoryAllocatedObject.h.

bool Ogre::DefaultWorkQueueBase::processIdleRequests ( ) [protected]

Response* Ogre::DefaultWorkQueueBase::processRequest ( Request * r ) [protected]

void Ogre::DefaultWorkQueueBase::processRequestResponse	(	Request *	r,
		bool	synchronous
	)		`[protected]`

void Ogre::DefaultWorkQueueBase::processResponse ( Response * r ) [protected]

virtual void Ogre::DefaultWorkQueueBase::processResponses ( ) [virtual]

Process the responses in the queue.

Remarks:: This method is public, and must be called from the main render thread to 'pump' responses through the system. The method will usually try to clear all responses before returning = 0; however, you can specify a time limit on the response processing to limit the impact of spikes in demand by calling setResponseProcessingTimeLimit.

Implements Ogre::WorkQueue.

virtual void Ogre::DefaultWorkQueueBase::removeRequestHandler	(	uint16	channel,
		RequestHandler *	rh
	)		`[virtual]`

Remove a request handler.

Implements Ogre::WorkQueue.

virtual void Ogre::DefaultWorkQueueBase::removeResponseHandler	(	uint16	channel,
		ResponseHandler *	rh
	)		`[virtual]`

Remove a Response handler.

Implements Ogre::WorkQueue.

virtual void Ogre::DefaultWorkQueueBase::setPaused ( bool pause ) [virtual]

Set whether to pause further processing of any requests.

If true, any further requests will simply be queued and not processed until setPaused(false) is called. Any requests which are in the process of being worked on already will still continue.

Implements Ogre::WorkQueue.

virtual void Ogre::DefaultWorkQueueBase::setRequestsAccepted ( bool accept ) [virtual]

Set whether to accept new requests or not.

If true, requests are added to the queue as usual. If false, requests are silently ignored until setRequestsAccepted(true) is called.

Implements Ogre::WorkQueue.

virtual void Ogre::DefaultWorkQueueBase::setResponseProcessingTimeLimit ( unsigned long ms ) [virtual]

Set the time limit imposed on the processing of responses in a single frame, in milliseconds (0 indicates no limit).

This sets the maximum time that will be spent in processResponses() in a single frame. The default is 8ms.

Implements Ogre::WorkQueue.

Definition at line 457 of file OgreWorkQueue.h.

virtual void Ogre::DefaultWorkQueueBase::setWorkersCanAccessRenderSystem ( bool access ) [virtual]

Set whether worker threads will be allowed to access render system resources.

Accessing render system resources from a separate thread can require that a context is maintained for that thread. Also, it requires that the render system is running in threadsafe mode, which only happens when OGRE_THREAD_SUPPORT=1. This option defaults to false, which means that threads can not use GPU resources, and the render system can work in non-threadsafe mode, which is more efficient. Calling this will have no effect unless the queue is shut down and restarted.

virtual void Ogre::DefaultWorkQueueBase::setWorkerThreadCount ( size_t c ) [virtual]

Set the number of worker threads that this queue will start when startup() is called (default 1).

Calling this will have no effect unless the queue is shut down and restarted.

virtual void Ogre::WorkQueue::shutdown ( ) [pure virtual, inherited]

Shut down the queue.

Implemented in Ogre::DefaultWorkQueue, and Ogre::DefaultWorkQueue.

virtual void Ogre::WorkQueue::startup ( bool forceRestart = true ) [pure virtual, inherited]

Start up the queue with the options that have been set.

Parameters:

forceRestart If the queue is already running, whether to shut it down and restart.

Implemented in Ogre::DefaultWorkQueue, and Ogre::DefaultWorkQueue.