# Ogre::DefaultWorkQueueBase Class Reference
[General]

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

`#include <OgreWorkQueue.h>`

Inheritance diagram for Ogre::DefaultWorkQueueBase:
[legend]

List of all members.

## 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 ()
const String & | getName () const
| Get the name of the work queue.
virtual size_t | getWorkerThreadCount () const
| Get the number of worker threads that this queue will start when startup() is called.
virtual void | setWorkerThreadCount (size_t c)
| Set the number of worker threads that this queue will start when startup() is called (default 1).
virtual bool | getWorkersCanAccessRenderSystem () const
| Get whether worker threads will be allowed to access render system resources.
virtual void | setWorkersCanAccessRenderSystem (bool access)
| Set whether worker threads will be allowed to access render system resources.
virtual void | _processNextRequest ()
| Process the next request on the queue.
virtual void | _threadMain ()=0
| Main function for each thread spawned.
virtual bool | isShuttingDown () const
| Returns whether the queue is trying to shut down.
virtual void | addRequestHandler (uint16 channel, RequestHandler *rh)
virtual void | removeRequestHandler (uint16 channel, RequestHandler *rh)
virtual void | addResponseHandler (uint16 channel, ResponseHandler *rh)
virtual void | removeResponseHandler (uint16 channel, ResponseHandler *rh)
virtual RequestID | addRequest (uint16 channel, uint16 requestType, const Any &rData, uint8 retryCount=0, bool forceSynchronous=false)
virtual void | abortRequest (RequestID id)
virtual void | abortRequestsByChannel (uint16 channel)
virtual void | abortAllRequests ()
virtual void | setPaused (bool pause)
virtual bool | isPaused () const
virtual void | setRequestsAccepted (bool accept)
virtual bool | getRequestsAccepted () const
virtual void | processResponses ()
virtual unsigned long | getResponseProcessingTimeLimit () const
virtual void | setResponseProcessingTimeLimit (unsigned long ms)
virtual void | startup (bool forceRestart=true)=0
| Start up the queue with the options that have been set.
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 deque< Request * >::type | RequestQueue
typedef deque< Response * >::type | ResponseQueue
typedef SharedPtr < RequestHandlerHolder > | RequestHandlerHolderPtr
typedef list < RequestHandlerHolderPtr > ::type | RequestHandlerList
typedef list< ResponseHandler * > ::type | ResponseHandlerList
typedef map< uint16, RequestHandlerList >::type | RequestHandlerListByChannel
typedef map< uint16, ResponseHandlerList >::type | ResponseHandlerListByChannel
typedef std::map< String, uint16 > | ChannelMap

## Protected Member Functions

| OGRE_RW_MUTEX (mRequestHandlerMutex)
void | processRequestResponse (Request *r, bool synchronous)
Response * | processRequest (Request *r)
void | processResponse (Response *r)
virtual void | notifyWorkers ()=0
| Notify workers about a new request.
void | addRequestWithRID (RequestID rid, uint16 channel, uint16 requestType, const Any &rData, uint8 retryCount)
| Put a Request on the queue with a specific RequestID.

## Protected Attributes

String | mName
size_t | mWorkerThreadCount
bool | mWorkerRenderSystemAccess
bool | mIsRunning
unsigned long | mResposeTimeLimitMS
RequestQueue | mRequestQueue
RequestQueue | mProcessQueue
ResponseQueue | mResponseQueue
WorkerFunc * | mWorkerFunc
RequestHandlerListByChannel | mRequestHandlers
ResponseHandlerListByChannel | mResponseHandlers
RequestID | mRequestCount
bool | mPaused
bool | mAcceptRequests
bool | mShuttingDown
ChannelMap | mChannelMap
uint16 | mNextChannel

## 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 `[protected, inherited]`

Definition at line 72 of file OgreWorkQueue.h.

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

Definition at line 515 of file OgreWorkQueue.h.

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

Definition at line 517 of file OgreWorkQueue.h.

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

Definition at line 519 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.

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

Definition at line 448 of file OgreWorkQueue.h.

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

Definition at line 518 of file OgreWorkQueue.h.

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

Definition at line 520 of file OgreWorkQueue.h.

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

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:

  | 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::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.

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` |
| ) |  |  | `[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

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 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`[virtual]`

Returns whether the queue is trying to shut down.

Definition at line 407 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::DefaultWorkQueueBase::OGRE_RW_MUTEX | ( | mRequestHandlerMutex |  | ) | `[protected]`

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 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 112 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 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,
|  | 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,
|  | 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.

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

## Member Data Documentation

bool Ogre::DefaultWorkQueueBase::mAcceptRequests `[protected]`

Definition at line 526 of file OgreWorkQueue.h.

ChannelMap Ogre::WorkQueue::mChannelMap `[protected, inherited]`

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 `[protected, inherited]`

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:

- OgreWorkQueue.h

Copyright © 2008 Torus Knot Software Ltd
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.
Last modified Wed Nov 3 2010 19:25:03