Ogre::WorkQueue Class Reference

Interface to a general purpose task-basedbackground work queue. More...

#include <OgreWorkQueue.h>

Inheritance diagram for Ogre::WorkQueue:

Classes
class	Request
	General purpose request structure. More...
struct	Response
	General purpose response structure. More...

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

Public Member Functions
	WorkQueue ()
virtual	~WorkQueue ()
virtual void	addMainThreadTask (std::function< void()> task)=0
	Add a deferred task that will be processed on the main render thread.
virtual void	addTask (std::function< void()> task)=0
	Add a new task to the queue.
uint64	getMainThreadProcessingTimeLimit () const
	Get the time limit imposed on the processing of tasks in a single frame, in milliseconds (0 indicates no limit).
virtual bool	getRequestsAccepted () const =0
	Returns whether requests are being accepted right now.
virtual unsigned long	getResponseProcessingTimeLimit () const =0
virtual size_t	getWorkerThreadCount () const
	Get the number of worker threads that this queue will start when startup() is called.
virtual bool	isPaused () const =0
	Return whether the queue is paused ie not sending more work to workers.
virtual void	processMainThreadTasks ()
	Process the tasks in the main-thread queue.
virtual void	processResponses ()
void	setMainThreadProcessingTimeLimit (uint64 ms)
	Set the time limit imposed on the processing of tasks in a single frame, in milliseconds (0 indicates no limit).
virtual void	setPaused (bool pause)=0
	Set whether to pause further processing of any requests.
virtual void	setRequestsAccepted (bool accept)=0
	Set whether to accept new requests or not.
virtual void	setResponseProcessingTimeLimit (unsigned long ms)=0
virtual void	setWorkerThreadCount (size_t c)
	Set the number of worker threads that this queue will start when startup() is called (default 1).
virtual void	shutdown ()=0
	Shut down the queue.
virtual void	startup (bool forceRestart=true)=0
	Start up the queue with the options that have been set.

Detailed Description

Interface to a general purpose task-basedbackground work queue.

A work queue is a simple structure, where tasks of work are placed onto the queue, then removed by a worker for processing. 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 tasks.

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.

Member Typedef Documentation

RequestID

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

Numeric identifier for a request.

Constructor & Destructor Documentation

WorkQueue()

Ogre::WorkQueue::WorkQueue ( )

inline

~WorkQueue()

virtual Ogre::WorkQueue::~WorkQueue ( )

inlinevirtual

Member Function Documentation

getWorkerThreadCount()

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

inlinevirtual

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

Reimplemented in Ogre::DefaultWorkQueueBase.

setWorkerThreadCount()

virtual void Ogre::WorkQueue::setWorkerThreadCount ( size_t  c )

inlinevirtual

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.

Reimplemented in Ogre::DefaultWorkQueueBase.

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.

addTask()

virtual void Ogre::WorkQueue::addTask ( std::function< void()>  task )

pure virtual

Add a new task to the queue.

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.

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.

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.

getRequestsAccepted()

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

pure virtual

Returns whether requests are being accepted right now.

Implemented in Ogre::DefaultWorkQueueBase.

processMainThreadTasks()

virtual void Ogre::WorkQueue::processMainThreadTasks ( )

virtual

Process the tasks in the main-thread queue.

This method must be called from the main render thread to 'pump' tasks through the system. The method will usually try to clear all tasks before returning; however, you can specify a time limit on the tasks processing to limit the impact of spikes in demand by calling setMainThreadProcessingTimeLimit.

Reimplemented in Ogre::DefaultWorkQueueBase.

processResponses()

virtual void Ogre::WorkQueue::processResponses ( )

inlinevirtual

Deprecated:

use processMainThreadTasks

getMainThreadProcessingTimeLimit()

uint64 Ogre::WorkQueue::getMainThreadProcessingTimeLimit ( ) const

inline

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

getResponseProcessingTimeLimit()

virtual unsigned long Ogre::WorkQueue::getResponseProcessingTimeLimit ( ) const

pure virtual

Deprecated:

use getMainThreadProcessingTimeLimit()

Implemented in Ogre::DefaultWorkQueueBase.

setMainThreadProcessingTimeLimit()

void Ogre::WorkQueue::setMainThreadProcessingTimeLimit ( uint64  ms )

inline

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

This sets the maximum time that will be spent in processMainThreadTasks() in a single frame. The default is 10ms.

setResponseProcessingTimeLimit()

virtual void Ogre::WorkQueue::setResponseProcessingTimeLimit ( unsigned long  ms )

pure virtual

Deprecated:

use setMainThreadProcessingTimeLimit

Implemented in Ogre::DefaultWorkQueueBase.

addMainThreadTask()

virtual void Ogre::WorkQueue::addMainThreadTask ( std::function< void()>  task )

pure virtual

Add a deferred task that will be processed on the main render thread.

Implemented in Ogre::DefaultWorkQueueBase.

shutdown()

virtual void Ogre::WorkQueue::shutdown ( )

pure virtual

Shut down the queue.

Implemented in Ogre::DefaultWorkQueue.

---

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

• OgreWorkQueue.h