Ogre::DefaultWorkQueueBase Class Reference

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

#include <OgreWorkQueue.h>

Inheritance diagram for Ogre::DefaultWorkQueueBase:

Public Member Functions
	DefaultWorkQueueBase (const String &name=BLANKSTRING)
	Constructor. More...
virtual	~DefaultWorkQueueBase ()
virtual void	_processNextRequest ()
	Process the next request on the queue. More...
virtual void	_threadMain ()=0
	Main function for each thread spawned. More...
void	abortAllRequests () override
	Abort all previously issued requests. More...
bool	abortPendingRequest (RequestID id) override
	Abort request if it is not being processed currently. More...
void	abortPendingRequestsByChannel (uint16 channel) override
	Abort all previously issued requests in a given channel. More...
void	abortRequest (RequestID id) override
	Abort a previously issued request. More...
void	abortRequestsByChannel (uint16 channel) override
	Abort all previously issued requests in a given channel. More...
RequestID	addRequest (uint16 channel, uint16 requestType, const Any &rData, uint8 retryCount=0, bool forceSynchronous=false, bool idleThread=false) override
	Add a new request to the queue. More...
void	addRequestHandler (uint16 channel, RequestHandler *rh) override
	Add a request handler instance to the queue. More...
void	addResponseHandler (uint16 channel, ResponseHandler *rh) override
	Add a response handler instance to the queue. More...
const String &	getName () const
	Get the name of the work queue. More...
bool	getRequestsAccepted () const override
	Returns whether requests are being accepted right now. More...
unsigned long	getResponseProcessingTimeLimit () const override
	Get the time limit imposed on the processing of responses in a single frame, in milliseconds (0 indicates no limit). More...
virtual bool	getWorkersCanAccessRenderSystem () const
	Get whether worker threads will be allowed to access render system resources. More...
virtual size_t	getWorkerThreadCount () const
	Get the number of worker threads that this queue will start when startup() is called. More...
bool	isPaused () const override
	Return whether the queue is paused ie not sending more work to workers. More...
virtual bool	isShuttingDown () const
	Returns whether the queue is trying to shut down. More...
void	processResponses () override
	Process the responses in the queue. More...
void	removeRequestHandler (uint16 channel, RequestHandler *rh) override
	Remove a request handler. More...
void	removeResponseHandler (uint16 channel, ResponseHandler *rh) override
	Remove a Response handler. More...
void	setPaused (bool pause) override
	Set whether to pause further processing of any requests. More...
void	setRequestsAccepted (bool accept) override
	Set whether to accept new requests or not. More...
void	setResponseProcessingTimeLimit (unsigned long ms) override
	Set the time limit imposed on the processing of responses in a single frame, in milliseconds (0 indicates no limit). More...
virtual void	setWorkersCanAccessRenderSystem (bool access)
	Set whether worker threads will be allowed to access render system resources. More...
virtual void	setWorkerThreadCount (size_t c)
	Set the number of worker threads that this queue will start when startup() is called (default 1). More...
Public Member Functions inherited from Ogre::WorkQueue
	WorkQueue ()
virtual	~WorkQueue ()
virtual uint16	getChannel (const String &channelName)
	Get a channel ID for a given channel name. More...
virtual void	shutdown ()=0
	Shut down the queue. More...
virtual void	startup (bool forceRestart=true)=0
	Start up the queue with the options that have been set. More...

Additional Inherited Members
Public Types inherited from Ogre::WorkQueue
typedef unsigned long long int	RequestID
	Numeric identifier for a request. More...

Detailed Description

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

Constructor & Destructor Documentation

DefaultWorkQueueBase()

Ogre::DefaultWorkQueueBase::DefaultWorkQueueBase

(

const String &

name = BLANKSTRING

)

Constructor.

Call startup() to initialise.

Parameters

name	Optional name, just helps to identify logging output

~DefaultWorkQueueBase()

virtual Ogre::DefaultWorkQueueBase::~DefaultWorkQueueBase ( )

virtual

Member Function Documentation

getName()

const String& Ogre::DefaultWorkQueueBase::getName

(

)

const

Get the name of the work queue.

getWorkerThreadCount()

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

virtual

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

setWorkerThreadCount()

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.

getWorkersCanAccessRenderSystem()

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.

setWorkersCanAccessRenderSystem()

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.

_processNextRequest()

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.

_threadMain()

virtual void Ogre::DefaultWorkQueueBase::_threadMain ( )

pure virtual

Main function for each thread spawned.

isShuttingDown()

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

inlinevirtual

Returns whether the queue is trying to shut down.

addRequestHandler()

void Ogre::DefaultWorkQueueBase::addRequestHandler ( uint16  channel, RequestHandler *  rh  )

overridevirtual

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.

removeRequestHandler()

void Ogre::DefaultWorkQueueBase::removeRequestHandler ( uint16  channel, RequestHandler *  rh  )

overridevirtual

Remove a request handler.

Implements Ogre::WorkQueue.

addResponseHandler()

void Ogre::DefaultWorkQueueBase::addResponseHandler ( uint16  channel, ResponseHandler *  rh  )

overridevirtual

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.

removeResponseHandler()

void Ogre::DefaultWorkQueueBase::removeResponseHandler ( uint16  channel, ResponseHandler *  rh  )

overridevirtual

Remove a Response handler.

Implements Ogre::WorkQueue.

addRequest()

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

overridevirtual

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 channel 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: If a request handler can't process multiple requests in parallel. If you add lot of requests, but you want to keep the game fast. If you have lot of more important threads. (example: physics).

Returns

The ID of the request that has been added

Implements Ogre::WorkQueue.

abortRequest()

void Ogre::DefaultWorkQueueBase::abortRequest ( RequestID  id )

overridevirtual

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.

abortPendingRequest()

bool Ogre::DefaultWorkQueueBase::abortPendingRequest ( RequestID  id )

overridevirtual

Abort request if it is not being processed currently.

Parameters

id	The ID of the previously issued request.

Return values

true	If request was aborted successfully.
false	If request is already being processed so it can not be aborted.

Implements Ogre::WorkQueue.

abortRequestsByChannel()

void Ogre::DefaultWorkQueueBase::abortRequestsByChannel ( uint16  channel )

overridevirtual

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.

abortPendingRequestsByChannel()

void Ogre::DefaultWorkQueueBase::abortPendingRequestsByChannel ( uint16  channel )

overridevirtual

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.

abortAllRequests()

void Ogre::DefaultWorkQueueBase::abortAllRequests ( )

overridevirtual

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.

setPaused()

void Ogre::DefaultWorkQueueBase::setPaused ( bool  pause )

overridevirtual

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.

isPaused()

bool Ogre::DefaultWorkQueueBase::isPaused ( ) const

overridevirtual

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

Implements Ogre::WorkQueue.

setRequestsAccepted()

void Ogre::DefaultWorkQueueBase::setRequestsAccepted ( bool  accept )

overridevirtual

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.

getRequestsAccepted()

bool Ogre::DefaultWorkQueueBase::getRequestsAccepted ( ) const

overridevirtual

Returns whether requests are being accepted right now.

Implements Ogre::WorkQueue.

processResponses()

void Ogre::DefaultWorkQueueBase::processResponses ( )

overridevirtual

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.

getResponseProcessingTimeLimit()

unsigned long Ogre::DefaultWorkQueueBase::getResponseProcessingTimeLimit ( ) const

inlineoverridevirtual

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

Implements Ogre::WorkQueue.

setResponseProcessingTimeLimit()

void Ogre::DefaultWorkQueueBase::setResponseProcessingTimeLimit ( unsigned long  ms )

inlineoverridevirtual

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 10ms.

Implements Ogre::WorkQueue.

---

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

• OgreWorkQueue.h