OGRE  master
Object-Oriented Graphics Rendering Engine
Ogre::WorkQueue Class Referenceabstract

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

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. More...
 
virtual void addTask (std::function< void()> task)=0
 Add a new task to the queue. More...
 
uint64 getMainThreadProcessingTimeLimit () const
 Get the time limit imposed on the processing of tasks in a single frame, in milliseconds (0 indicates no limit). More...
 
virtual bool getRequestsAccepted () const =0
 Returns whether requests are being accepted right now. More...
 
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. More...
 
virtual bool isPaused () const =0
 Return whether the queue is paused ie not sending more work to workers. More...
 
virtual void processMainThreadTasks ()
 Process the tasks in the main-thread queue. More...
 
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). 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
 
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

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
forceRestartIf 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

◆ 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

◆ 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

◆ 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: