OGRE: Ogre::WorkQueue Class Reference

| OGRE 14.5 Object-Oriented Graphics Rendering Engine

Loading...
Searching...
No Matches
Ogre::WorkQueue Class Referenceabstract
Core » General

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

`#include <OgreWorkQueue.h>`

Inheritance diagram for Ogre::WorkQueue:
[legend]

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

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.

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.

Note
  This is automatically called by Root::renderOneFrame.

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.

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