Ogre::WorkQueue Class Reference
[General]

Interface to a general purpose request / response style background work queue. More...

#include <OgreWorkQueue.h>

Inheritance diagram for Ogre::WorkQueue:

Classes
class	Request
	General purpose request structure. More...
class	RequestHandler
	Interface definition for a handler of requests. More...
struct	Response
	General purpose response structure. More...
class	ResponseHandler
	Interface definition for a handler of responses. More...
Public Types
typedef unsigned long long int	RequestID
	Numeric identifier for a request.
Public Member Functions
	WorkQueue ()
virtual	~WorkQueue ()
virtual void	startup (bool forceRestart=true)=0
	Start up the queue with the options that have been set.
virtual void	addRequestHandler (uint16 channel, RequestHandler *rh)=0
	Add a request handler instance to the queue.
virtual void	removeRequestHandler (uint16 channel, RequestHandler *rh)=0
	Remove a request handler.
virtual void	addResponseHandler (uint16 channel, ResponseHandler *rh)=0
	Add a response handler instance to the queue.
virtual void	removeResponseHandler (uint16 channel, ResponseHandler *rh)=0
	Remove a Response handler.
virtual RequestID	addRequest (uint16 channel, uint16 requestType, const Any &rData, uint8 retryCount=0, bool forceSynchronous=false)=0
	Add a new request to the queue.
virtual void	abortRequest (RequestID id)=0
	Abort a previously issued request.
virtual void	abortRequestsByChannel (uint16 channel)=0
	Abort all previously issued requests in a given channel.
virtual void	abortAllRequests ()=0
	Abort all previously issued requests.
virtual void	setPaused (bool pause)=0
	Set whether to pause further processing of any requests.
virtual bool	isPaused () const =0
	Return whether the queue is paused ie not sending more work to workers.
virtual void	setRequestsAccepted (bool accept)=0
	Set whether to accept new requests or not.
virtual bool	getRequestsAccepted () const =0
	Returns whether requests are being accepted right now.
virtual void	processResponses ()=0
	Process the responses in the queue.
virtual unsigned long	getResponseProcessingTimeLimit () const =0
	Get the time limit imposed on the processing of responses in a single frame, in milliseconds (0 indicates no limit).
virtual void	setResponseProcessingTimeLimit (unsigned long ms)=0
	Set the time limit imposed on the processing of responses in a single frame, in milliseconds (0 indicates no limit).
virtual void	shutdown ()=0
	Shut down the queue.
virtual uint16	getChannel (const String &channelName)
	Get a channel ID for a given channel name.
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)
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 *)
Protected Types
typedef std::map< String, uint16 >	ChannelMap
Protected Attributes
ChannelMap	mChannelMap
uint16	mNextChannel

Detailed Description

Interface to a general purpose request / response style background work queue.

Remarks:: A work queue is a simple structure, where requests for work are placed onto the queue, then removed by a worker for processing, then finally a response is placed on the result queue for the originator to pick up at their leisure. The typical use for this is in a threaded environment, although any kind of deferred processing could use this approach to decouple and distribute work over a period of time even if it was single threaded.

: WorkQueues also incorporate thread pools. One or more background worker threads can wait on the queue and be notified when a request is waiting to be processed. For maximal thread usage, a WorkQueue instance should be shared among many sources of work, rather than many work queues being created. This way, you can share a small number of hardware threads among a large number of background tasks. This doesn't mean you have to implement all the request processing in one class, you can plug in many handlers in order to process the requests.

: This is an abstract interface definition; users can subclass this and provide their own implementation if required to centralise task management in their own subsystems. We also provide a default implementation in the form of DefaultWorkQueue.

Definition at line 69 of file OgreWorkQueue.h.

Member Typedef Documentation

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

Definition at line 72 of file OgreWorkQueue.h.

typedef unsigned long long int Ogre::WorkQueue::RequestID

Numeric identifier for a request.

Definition at line 78 of file OgreWorkQueue.h.

Constructor & Destructor Documentation

Ogre::WorkQueue::WorkQueue ( )

Definition at line 220 of file OgreWorkQueue.h.

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

Definition at line 221 of file OgreWorkQueue.h.

Member Function Documentation

virtual void Ogre::WorkQueue::abortAllRequests ( ) [pure 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.

Implemented in Ogre::DefaultWorkQueueBase.

virtual void Ogre::WorkQueue::abortRequest ( RequestID id ) [pure 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.

Implemented in Ogre::DefaultWorkQueueBase.

virtual void Ogre::WorkQueue::abortRequestsByChannel ( uint16 channel ) [pure 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.

Parameters:

channel

The type of request to be aborted

Implemented in Ogre::DefaultWorkQueueBase.

virtual RequestID Ogre::WorkQueue::addRequest	(	uint16	channel,
		uint16	requestType,
		const Any &	rData,
		uint8	retryCount = `0`,
		bool	forceSynchronous = `false`
	)			`[pure 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.

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

Implemented in Ogre::DefaultWorkQueueBase.

virtual void Ogre::WorkQueue::addRequestHandler	(	uint16	channel,
		RequestHandler *	rh
	)			`[pure 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

Implemented in Ogre::DefaultWorkQueueBase.

virtual void Ogre::WorkQueue::addResponseHandler	(	uint16	channel,
		ResponseHandler *	rh
	)			`[pure 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

Implemented in Ogre::DefaultWorkQueueBase.

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

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.

virtual bool Ogre::WorkQueue::getRequestsAccepted ( ) const [pure virtual]

Returns whether requests are being accepted right now.

Implemented in Ogre::DefaultWorkQueueBase.

virtual unsigned long Ogre::WorkQueue::getResponseProcessingTimeLimit ( ) const [pure virtual]

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

Implemented in Ogre::DefaultWorkQueueBase.

virtual bool Ogre::WorkQueue::isPaused ( ) const [pure virtual]

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

Implemented in Ogre::DefaultWorkQueueBase.

template<class Alloc >

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

Definition at line 107 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

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

Definition at line 101 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

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

Definition at line 95 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

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

Definition at line 118 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

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

Definition at line 112 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 78 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

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

Definition at line 72 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 67 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

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

Definition at line 90 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 85 of file OgreMemoryAllocatedObject.h.

virtual void Ogre::WorkQueue::processResponses ( ) [pure 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.

Implemented in Ogre::DefaultWorkQueueBase.

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

Remove a request handler.

Implemented in Ogre::DefaultWorkQueueBase.

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

Remove a Response handler.

Implemented in Ogre::DefaultWorkQueueBase.

virtual void Ogre::WorkQueue::setPaused ( bool pause ) [pure 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.

Implemented in Ogre::DefaultWorkQueueBase.

virtual void Ogre::WorkQueue::setRequestsAccepted ( bool accept ) [pure 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.

Implemented in Ogre::DefaultWorkQueueBase.

virtual void Ogre::WorkQueue::setResponseProcessingTimeLimit ( unsigned long ms ) [pure 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.

Implemented in Ogre::DefaultWorkQueueBase.

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

Shut down the queue.

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