Ogre::WorkQueue Class Referenceabstract
Core » General

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

`#include <OgreWorkQueue.h>`

Inheritance diagram for Ogre::WorkQueue:
[legend]

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

## Public Member Functions

| WorkQueue ()
virtual | ~WorkQueue ()
virtual void | abortAllRequests ()=0
| Abort all previously issued requests. More...
virtual void | abortPendingRequestsByChannel (uint16 channel)=0
| Abort all previously issued requests in a given channel. More...
virtual void | abortRequest (RequestID id)=0
| Abort a previously issued request. More...
virtual void | abortRequestsByChannel (uint16 channel)=0
| 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)=0
| Add a new request to the queue. More...
virtual void | addRequestHandler (uint16 channel, RequestHandler *rh)=0
| Add a request handler instance to the queue. More...
virtual void | addResponseHandler (uint16 channel, ResponseHandler *rh)=0
| 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...
virtual bool | getRequestsAccepted () const =0
| Returns whether requests are being accepted right now. More...
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). More...
virtual bool | isPaused () const =0
| Return whether the queue is paused ie not sending more work to workers. 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 ()=0
| Process the responses in the queue. More...
virtual void | removeRequestHandler (uint16 channel, RequestHandler *rh)=0
| Remove a request handler. More...
virtual void | removeResponseHandler (uint16 channel, ResponseHandler *rh)=0
| Remove a Response handler. More...
virtual void | setPaused (bool pause)=0
| Set whether to pause further processing of any requests. More...
virtual void | setRequestsAccepted (bool accept)=0
| Set whether to accept new requests or not. More...
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). 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 map< String, uint16 >::type | ChannelMap

## Protected Member Functions

| OGRE_MUTEX (mChannelMapMutex)

## 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 70 of file OgreWorkQueue.h.

## Member Typedef Documentation

## ChannelMap

typedef map<String, uint16>::type Ogre::WorkQueue::ChannelMap

protected

Definition at line 73 of file OgreWorkQueue.h.

## RequestID

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

Numeric identifier for a request.

Definition at line 79 of file OgreWorkQueue.h.

## Constructor & Destructor Documentation

## WorkQueue()

Ogre::WorkQueue::WorkQueue | ( |  | ) |

Definition at line 221 of file OgreWorkQueue.h.

## ~WorkQueue()

virtual Ogre::WorkQueue::~WorkQueue | ( |  | ) |

virtual

Definition at line 222 of file OgreWorkQueue.h.

## Member Function Documentation

## abortAllRequests()

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.

## abortPendingRequestsByChannel()

virtual void Ogre::WorkQueue::abortPendingRequestsByChannel | ( | 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. It will not remove requests, where the request handler is already called.

Parameters

  channel | The type of request to be aborted

Implemented in Ogre::DefaultWorkQueueBase.

## abortRequest()

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.

## abortRequestsByChannel()

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. Requests which are processed, but response handler is not called will also be removed.

Parameters

  channel | The type of request to be aborted

Implemented in Ogre::DefaultWorkQueueBase.

## addRequest()

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

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

Returns
  The ID of the request that has been added

Implemented in Ogre::DefaultWorkQueueBase.

## addRequestHandler()

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.

## addResponseHandler()

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.

## getChannel()

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.

## getRequestsAccepted()

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

pure virtual

Returns whether requests are being accepted right now.

Implemented in Ogre::DefaultWorkQueueBase.

## getResponseProcessingTimeLimit()

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.

## isPaused()

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.

## OGRE_MUTEX()

Ogre::WorkQueue::OGRE_MUTEX | ( | mChannelMapMutex |  | ) |

protected

## operator delete() [1/3]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete | ( | void * | ptr | ) |

inherited

Definition at line 96 of file OgreMemoryAllocatedObject.h.

## operator delete() [2/3]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete | ( | void * | ptr,
|  | void * |
| ) |  |

inherited

Definition at line 102 of file OgreMemoryAllocatedObject.h.

## operator delete() [3/3]

template<class Alloc >

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

inherited

Definition at line 108 of file OgreMemoryAllocatedObject.h.

## operator delete[]() [1/2]

template<class Alloc >

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

inherited

Definition at line 113 of file OgreMemoryAllocatedObject.h.

## operator delete[]() [2/2]

template<class Alloc >

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

inherited

Definition at line 119 of file OgreMemoryAllocatedObject.h.

## operator new() [1/3]

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 68 of file OgreMemoryAllocatedObject.h.

## operator new() [2/3]

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new | ( | size_t | sz | ) |

inherited

Definition at line 73 of file OgreMemoryAllocatedObject.h.

## operator new() [3/3]

template<class Alloc >

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

inherited

placement operator new

Definition at line 79 of file OgreMemoryAllocatedObject.h.

## operator new[]() [1/2]

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 86 of file OgreMemoryAllocatedObject.h.

## operator new[]() [2/2]

template<class Alloc >

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

inherited

Definition at line 91 of file OgreMemoryAllocatedObject.h.

## processResponses()

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.

## removeRequestHandler()

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

pure virtual

Remove a request handler.

Implemented in Ogre::DefaultWorkQueueBase.

## removeResponseHandler()

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

pure virtual

Remove a Response handler.

Implemented in Ogre::DefaultWorkQueueBase.

## setPaused()

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.

## setRequestsAccepted()

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.

## setResponseProcessingTimeLimit()

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.

## shutdown()

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

pure virtual

Shut down the queue.

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

## startup()

virtual void Ogre::WorkQueue::startup | ( | bool | forceRestart = `true` | ) |

pure virtual

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

## mChannelMap

ChannelMap Ogre::WorkQueue::mChannelMap

protected

Definition at line 74 of file OgreWorkQueue.h.

## mNextChannel

uint16 Ogre::WorkQueue::mNextChannel

protected

Definition at line 75 of file OgreWorkQueue.h.

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

- OgreWorkQueue.h

Copyright © 2012 Torus Knot Software Ltd
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.