Ogre::DefaultWorkQueueBase Class Reference

Base implementation of a general purpose task-based background work queue. More...

#include <OgreWorkQueue.h>

Inheritance diagram for Ogre::DefaultWorkQueueBase:

Public Member Functions
	DefaultWorkQueueBase (const String &name=BLANKSTRING)
	Constructor.
virtual	~DefaultWorkQueueBase ()
virtual void	_processNextRequest ()
	Pop and execute the next task from the background queue.
virtual void	_threadMain ()=0
	Main function for each thread spawned.
void	addMainThreadTask (std::function< void()> task) override
	Add a task that will be processed on the main render thread.
void	addTask (std::function< void()> task) override
	Add a new task to the background queue.
const String &	getName () const
	Get the name of the work queue.
virtual bool	getRequestsAccepted () const override
	Returns whether tasks are being accepted right now.
unsigned long	getResponseProcessingTimeLimit () const override
virtual bool	getWorkersCanAccessRenderSystem () const
	Get whether worker threads will be allowed to access render system resources.
size_t	getWorkerThreadCount () const override
	Get the number of worker threads that this queue will start when startup() is called.
bool	isPaused () const override
	Return whether the queue is paused ie not sending more work to workers.
virtual bool	isShuttingDown () const
	Returns whether the queue is trying to shut down.
void	processMainThreadTasks () override
	Process the tasks in the main-thread queue.
void	setPaused (bool pause) override
	Set whether to pause further processing of tasks.
void	setRequestsAccepted (bool accept) override
	Set whether to accept new tasks or not.
void	setResponseProcessingTimeLimit (unsigned long ms) override
virtual void	setWorkersCanAccessRenderSystem (bool access)
	Set whether worker threads will be allowed to access render system resources.
void	setWorkerThreadCount (size_t c) override
	Set the number of worker threads that this queue will start when startup() is called (default 1).
Public Member Functions inherited from Ogre::WorkQueue
	WorkQueue ()
virtual	~WorkQueue ()
uint64	getMainThreadProcessingTimeLimit () const
	Get the time limit imposed on the processing of tasks in a single frame, in milliseconds (0 indicates no limit).
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	shutdown ()=0
	Shut down the queue.
virtual void	startup (bool forceRestart=true)=0
	Start up the queue with the options that have been set.

Additional Inherited Members
Public Types inherited from Ogre::WorkQueue
typedef unsigned long long int	RequestID
	Legacy identifier type of the request/response API.

Detailed Description

Base implementation of a general purpose task-based background work queue.

It provides the two FIFO queues, the accept/pause flags and the main-thread processing loop. Concrete implementations only have to provide the thread management via _threadMain() and notifyWorkers(), plus startup / shutdown.

See also

Background Resource Loading

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

References Ogre::BLANKSTRING.

~DefaultWorkQueueBase()

virtual Ogre::DefaultWorkQueueBase::~DefaultWorkQueueBase ( )

virtual

Member Function Documentation

getName()

const String & Ogre::DefaultWorkQueueBase::getName

(

)

const

Get the name of the work queue.

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

Pop and execute the next task from the background queue.

This method is public, but only intended for advanced users. The only reason you would call it is if you drive the worker processing with your own thread. The task runs on the calling thread; an exception escaping it is not caught here.

_threadMain()

virtual void Ogre::DefaultWorkQueueBase::_threadMain ( )

pure virtual

Main function for each thread spawned.

Implemented in Ogre::DefaultWorkQueue.

isShuttingDown()

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

inlinevirtual

Returns whether the queue is trying to shut down.

setPaused()

void Ogre::DefaultWorkQueueBase::setPaused ( bool pause )

overridevirtual

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.

Implements Ogre::WorkQueue.

isPaused()

bool Ogre::DefaultWorkQueueBase::isPaused ( ) const

overridevirtual

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

Implements Ogre::WorkQueue.

setRequestsAccepted()

void Ogre::DefaultWorkQueueBase::setRequestsAccepted ( bool accept )

overridevirtual

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.

Implements Ogre::WorkQueue.

getRequestsAccepted()

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

overridevirtual

Returns whether tasks are being accepted right now.

Implements Ogre::WorkQueue.

processMainThreadTasks()

void Ogre::DefaultWorkQueueBase::processMainThreadTasks ( )

overridevirtual

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 from Ogre::WorkQueue.

getResponseProcessingTimeLimit()

unsigned long Ogre::DefaultWorkQueueBase::getResponseProcessingTimeLimit ( ) const

inlineoverridevirtual

Deprecated

use getMainThreadProcessingTimeLimit()

Implements Ogre::WorkQueue.

setResponseProcessingTimeLimit()

void Ogre::DefaultWorkQueueBase::setResponseProcessingTimeLimit ( unsigned long ms )

inlineoverridevirtual

Deprecated

use setMainThreadProcessingTimeLimit

Implements Ogre::WorkQueue.

getWorkerThreadCount()

size_t Ogre::DefaultWorkQueueBase::getWorkerThreadCount ( ) const

inlineoverridevirtual

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 from Ogre::WorkQueue.

setWorkerThreadCount()

void Ogre::DefaultWorkQueueBase::setWorkerThreadCount ( size_t c )

inlineoverridevirtual

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 from Ogre::WorkQueue.

addMainThreadTask()

void Ogre::DefaultWorkQueueBase::addMainThreadTask ( std::function< void()> task )

overridevirtual

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.

Implements Ogre::WorkQueue.

addTask()

void Ogre::DefaultWorkQueueBase::addTask ( std::function< void()> task )

overridevirtual

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.

Implements Ogre::WorkQueue.

---

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

• OgreWorkQueue.h