Ogre::WorkQueue Class Reference

Interface to a general purpose task-based background work queue. More...

#include <OgreWorkQueue.h>

Inheritance diagram for Ogre::WorkQueue:

Classes
class	Request
	Legacy request structure. More...
struct	Response
	Legacy response structure. More...

Public Types
typedef unsigned long long int	RequestID
	Legacy identifier type of the request/response API.

Public Member Functions
	WorkQueue ()
virtual	~WorkQueue ()
virtual void	addMainThreadTask (std::function< void()> task)=0
	Add a task that will be processed on the main render thread.
virtual void	addTask (std::function< void()> task)=0
	Add a new task to the background 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 tasks 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 tasks.
virtual void	setRequestsAccepted (bool accept)=0
	Set whether to accept new tasks 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-based background 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 task 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 task processing in one class, you can submit as many independent tasks as you like.

The WorkQueue distinguishes between two types of tasks:

1. Background tasks: Added via addTask. These are processed by the worker threads.
2. Main thread tasks: Added via addMainThreadTask. These are processed by the main thread when processMainThreadTasks is called. This is useful for tasks that need to access resources that are not thread-safe or must be accessed from the main thread (e.g. GPU resources).

processMainThreadTasks is automatically called by Root::renderOneFrame (via Root::_fireFrameEnded) or can be called manually by the user in the main loop.

Both queues are FIFO and thread-safe; addTask and addMainThreadTask may be called from any thread. There is no priority and no cancellation. With more than one worker thread, background tasks may complete out of order.

Tasks are std::function<void()>, therefore their captures must be copyable.

Task lifetime

A task may run after the object that submitted it has been destroyed. Capture a std::shared_ptr (or check a std::weak_ptr) if no other mechanism guarantees that everything the task accesses is still alive. Keep resource references needed by the task alive in its capture.

Exceptions

An exception thrown by a background task is not caught and will terminate the process. Use a std::packaged_task to capture the exception in a std::future instead. An exception thrown by a main-thread task propagates out of processMainThreadTasks.

See also

Background Resource Loading for a tutorial and usage examples.

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

Legacy identifier type of the request/response API.

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.

Implementations are free to ignore this setting; the default is 1.

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

May be called from any thread. Tasks are executed in submission order, but with more than one worker thread the completion order is unspecified.

The task is silently dropped if the queue is shutting down or if setRequestsAccepted has been called with false.

Tasks are std::function<void()>, so the captures must be copyable. With OGRE_THREAD_SUPPORT == 0 the task is executed inline on the calling thread instead of being queued.

Warning

An exception escaping the task terminates the process. Wrap potentially throwing work in a std::packaged_task.

Implemented in Ogre::DefaultWorkQueueBase.

setPaused()

virtual void Ogre::WorkQueue::setPaused ( bool pause )

pure virtual

Set whether to pause further processing of tasks.

If true, further tasks will simply be queued and not processed until setPaused(false) is called. Tasks which are already being worked on will still continue.

Note

Pausing is not currently implemented by DefaultWorkQueueBase; this flag is retained for custom implementations. Use setRequestsAccepted to stop accepting new tasks.

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 tasks or not.

If true, tasks are added to the queues as usual. If false, both addTask and addMainThreadTask silently ignore new tasks until setRequestsAccepted(true) is called.

Implemented in Ogre::DefaultWorkQueueBase.

getRequestsAccepted()

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

pure virtual

Returns whether tasks 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. Tasks added while the queue is being processed may be picked up in the same call, subject to the time limit.

Note

This is automatically called by Root::renderOneFrame, after the frameEnded listeners.

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

References getResponseProcessingTimeLimit().

getResponseProcessingTimeLimit()

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

pure virtual

Deprecated

use getMainThreadProcessingTimeLimit()

Implemented in Ogre::DefaultWorkQueueBase.

Referenced by getMainThreadProcessingTimeLimit().

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.

The limit is checked after each task completes, so a single long task can overshoot it. Each call to processMainThreadTasks gets its own budget.

References setResponseProcessingTimeLimit().

setResponseProcessingTimeLimit()

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

pure virtual

Deprecated

use setMainThreadProcessingTimeLimit

Implemented in Ogre::DefaultWorkQueueBase.

Referenced by setMainThreadProcessingTimeLimit().

addMainThreadTask()

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

pure virtual

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

May be called from any thread. The task does not run immediately, even when called from the main thread; it runs during the next processMainThreadTasks call.

The task is silently dropped if the queue is shutting down or if setRequestsAccepted has been called with false.

Warning

An exception escaping the task propagates out of processMainThreadTasks.

Implemented in Ogre::DefaultWorkQueueBase.

shutdown()

virtual void Ogre::WorkQueue::shutdown ( )

pure virtual

Shut down the queue.

Stops the worker threads and waits for them to finish. Tasks that are already running complete, but tasks still waiting in the queues are not executed. The queues are not cleared, so starting the queue again may still process them.

Implemented in Ogre::DefaultWorkQueue.

---

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

• OgreWorkQueue.h