OGRE  1.8
Object-Oriented Graphics Rendering Engine
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
Ogre::DefaultWorkQueueBase Class Referenceabstract

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

#include <OgreWorkQueue.h>

+ Inheritance diagram for Ogre::DefaultWorkQueueBase:
+ Collaboration 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. More...
 

Public Member Functions

 DefaultWorkQueueBase (const String &name=StringUtil::BLANK)
 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...
 
virtual void abortAllRequests ()
 Abort all previously issued requests. More...
 
virtual void abortRequest (RequestID id)
 Abort a previously issued request. More...
 
virtual void abortRequestsByChannel (uint16 channel)
 Abort all previously issued requests in a given channel. More...
 
virtual RequestID addRequest (uint16 channel, uint16 requestType, const Any &rData, uint8 retryCount=0, bool forceSynchronous=false)
 Add a new request to the queue. More...
 
virtual void addRequestHandler (uint16 channel, RequestHandler *rh)
 Add a request handler instance to the queue. More...
 
virtual void addResponseHandler (uint16 channel, ResponseHandler *rh)
 Add a response handler instance to the queue. More...
 
virtual uint16 getChannel (const String &channelName)
 Get a channel ID for a given channel name. More...
 
const StringgetName () const
 Get the name of the work queue. More...
 
virtual bool getRequestsAccepted () const
 Returns whether requests are being accepted right now. More...
 
virtual unsigned long getResponseProcessingTimeLimit () const
 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...
 
virtual bool isPaused () const
 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 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 More...
 
void * operator new (size_t sz)
 
void * operator new (size_t sz, void *ptr)
 placement operator new More...
 
void * operator new[] (size_t sz, const char *file, int line, const char *func)
 array operator new, with debug line info More...
 
void * operator new[] (size_t sz)
 
virtual void processResponses ()
 Process the responses in the queue. More...
 
virtual void removeRequestHandler (uint16 channel, RequestHandler *rh)
 Remove a request handler. More...
 
virtual void removeResponseHandler (uint16 channel, ResponseHandler *rh)
 Remove a Response handler. More...
 
virtual void setPaused (bool pause)
 Set whether to pause further processing of any requests. More...
 
virtual void setRequestsAccepted (bool accept)
 Set whether to accept new requests or not. More...
 
virtual void setResponseProcessingTimeLimit (unsigned long ms)
 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...
 
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...
 

Protected Types

typedef std::map< String, uint16ChannelMap
 
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. More...
 
virtual void notifyWorkers ()=0
 Notify workers about a new request. More...
 
ResponseprocessRequest (Request *r)
 
void processRequestResponse (Request *r, bool synchronous)
 
void processResponse (Response *r)
 

Protected Attributes

bool mAcceptRequests
 
ChannelMap mChannelMap
 
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 345 of file OgreWorkQueue.h.

Member Typedef Documentation

typedef std::map<String, uint16> Ogre::WorkQueue::ChannelMap
protectedinherited

Definition at line 72 of file OgreWorkQueue.h.

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

Numeric identifier for a request.

Definition at line 78 of file OgreWorkQueue.h.

Definition at line 448 of file OgreWorkQueue.h.

Definition at line 518 of file OgreWorkQueue.h.

Definition at line 449 of file OgreWorkQueue.h.

Constructor & Destructor Documentation

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

Constructor.

Call startup() to initialise.

Parameters
nameOptional 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::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
idThe 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.

Parameters
channelThe 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 
)
virtual

Add a new request to the queue.

Parameters
channelThe channel this request will go into = 0; the channel is the top-level categorisation of the request
requestTypeAn identifier that's unique within this queue which identifies the type of the request (user decides the actual value)
rDataThe data required by the request process.
retryCountThe number of times the request should be retried if it fails.
forceSynchronousForces the request to be processed immediately even if threading is enabled.
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
channelThe channel for requests you want to handle
rhYour 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
channelThe channel for responses you want to handle
rhYour handler

Implements Ogre::WorkQueue.

virtual uint16 Ogre::WorkQueue::getChannel ( const String channelName)
virtualinherited

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
inlinevirtual

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 438 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
inlinevirtual

Returns whether the queue is trying to shut down.

Definition at line 407 of file OgreWorkQueue.h.

virtual void Ogre::DefaultWorkQueueBase::notifyWorkers ( )
protectedpure virtual

Notify workers about a new request.

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

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete ( void *  ptr)
inlineinherited

Definition at line 95 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete ( void *  ptr,
void *   
)
inlineinherited

Definition at line 101 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete ( void *  ptr,
const char *  ,
int  ,
const char *   
)
inlineinherited

Definition at line 107 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete[] ( void *  ptr)
inlineinherited

Definition at line 112 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete[] ( void *  ptr,
const char *  ,
int  ,
const char *   
)
inlineinherited

Definition at line 118 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new ( size_t  sz,
const char *  file,
int  line,
const char *  func 
)
inlineinherited

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)
inlineinherited

Definition at line 72 of file OgreMemoryAllocatedObject.h.

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new ( size_t  sz,
void *  ptr 
)
inlineinherited

placement operator new

Definition at line 78 of file OgreMemoryAllocatedObject.h.

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

array operator new, with debug line info

Definition at line 85 of file OgreMemoryAllocatedObject.h.

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

Definition at line 90 of file OgreMemoryAllocatedObject.h.

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)
inlinevirtual

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 440 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 virtualinherited

Shut down the queue.

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

virtual void Ogre::WorkQueue::startup ( bool  forceRestart = true)
pure virtualinherited

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

Parameters
forceRestartIf the queue is already running, whether to shut it down and restart.

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

Member Data Documentation

bool Ogre::DefaultWorkQueueBase::mAcceptRequests
protected

Definition at line 526 of file OgreWorkQueue.h.

ChannelMap Ogre::WorkQueue::mChannelMap
protectedinherited

Definition at line 73 of file OgreWorkQueue.h.

bool Ogre::DefaultWorkQueueBase::mIsRunning
protected

Definition at line 445 of file OgreWorkQueue.h.

String Ogre::DefaultWorkQueueBase::mName
protected

Definition at line 442 of file OgreWorkQueue.h.

uint16 Ogre::WorkQueue::mNextChannel
protectedinherited

Definition at line 74 of file OgreWorkQueue.h.

bool Ogre::DefaultWorkQueueBase::mPaused
protected

Definition at line 525 of file OgreWorkQueue.h.

RequestQueue Ogre::DefaultWorkQueueBase::mProcessQueue
protected

Definition at line 451 of file OgreWorkQueue.h.

RequestID Ogre::DefaultWorkQueueBase::mRequestCount
protected

Definition at line 524 of file OgreWorkQueue.h.

RequestHandlerListByChannel Ogre::DefaultWorkQueueBase::mRequestHandlers
protected

Definition at line 522 of file OgreWorkQueue.h.

RequestQueue Ogre::DefaultWorkQueueBase::mRequestQueue
protected

Definition at line 450 of file OgreWorkQueue.h.

ResponseHandlerListByChannel Ogre::DefaultWorkQueueBase::mResponseHandlers
protected

Definition at line 523 of file OgreWorkQueue.h.

ResponseQueue Ogre::DefaultWorkQueueBase::mResponseQueue
protected

Definition at line 452 of file OgreWorkQueue.h.

unsigned long Ogre::DefaultWorkQueueBase::mResposeTimeLimitMS
protected

Definition at line 446 of file OgreWorkQueue.h.

bool Ogre::DefaultWorkQueueBase::mShuttingDown
protected

Definition at line 527 of file OgreWorkQueue.h.

WorkerFunc* Ogre::DefaultWorkQueueBase::mWorkerFunc
protected

Definition at line 466 of file OgreWorkQueue.h.

bool Ogre::DefaultWorkQueueBase::mWorkerRenderSystemAccess
protected

Definition at line 444 of file OgreWorkQueue.h.

size_t Ogre::DefaultWorkQueueBase::mWorkerThreadCount
protected

Definition at line 443 of file OgreWorkQueue.h.


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