| OGRE 1.11.1 Object-Oriented Graphics Rendering Engine

Classes | Public Types | Public Member Functions | List of all members
Ogre::DefaultWorkQueueBase Class Referenceabstract
Core » General

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

`#include <OgreWorkQueue.h>`

Inheritance diagram for Ogre::DefaultWorkQueueBase:
[legend]

## Public Types
typedef unsigned long long int | RequestID
| Numeric identifier for a request. More...

## 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...
virtual void | abortAllRequests ()
| Abort all previously issued requests. More...
virtual bool | abortPendingRequest (RequestID id)
| Abort request if it is not being processed currently. More...
virtual void | abortPendingRequestsByChannel (uint16 channel)
| Abort all previously issued requests in a given channel. 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, bool idleThread=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 String & | getName () 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...
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...

## Detailed Description

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

## Member Typedef Documentation

## ◆ RequestID

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

Numeric identifier for a request.

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

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

## ◆ isShuttingDown()

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

Returns whether the queue is trying to shut down.

## ◆ addRequestHandler()

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.

## ◆ removeRequestHandler()

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

Remove a request handler.

Implements Ogre::WorkQueue.

## ◆ addResponseHandler()

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.

## ◆ removeResponseHandler()

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

Remove a Response handler.

Implements Ogre::WorkQueue.

## ◆ addRequest()

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: 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()

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.

## ◆ abortPendingRequest()

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

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

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.

## ◆ abortPendingRequestsByChannel()

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.

## ◆ abortAllRequests()

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.

## ◆ setPaused()

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.

## ◆ isPaused()

virtual bool Ogre::DefaultWorkQueueBase::isPaused | ( |  | ) | const
| virtual

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

Implements Ogre::WorkQueue.

## ◆ setRequestsAccepted()

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.

## ◆ getRequestsAccepted()

virtual bool Ogre::DefaultWorkQueueBase::getRequestsAccepted | ( |  | ) | const
| virtual

Returns whether requests are being accepted right now.

Implements Ogre::WorkQueue.

## ◆ processResponses()

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.

## ◆ getResponseProcessingTimeLimit()

virtual unsigned long Ogre::DefaultWorkQueueBase::getResponseProcessingTimeLimit | ( |  | ) | const
| inline virtual

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

Implements Ogre::WorkQueue.

## ◆ setResponseProcessingTimeLimit()

virtual void Ogre::DefaultWorkQueueBase::setResponseProcessingTimeLimit | ( | unsigned long | ms | ) |
| inline 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.

## ◆ startup()

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.

## ◆ shutdown()

virtual void Ogre::WorkQueue::shutdown | ( |  | ) |
| pure virtual inherited

Shut down the queue.

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

## ◆ getChannel()

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.

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

- OgreWorkQueue.h