Ogre::ResourceBackgroundQueue Class Reference
Core » Resources

This class is used to perform Resource operations in a background thread. More...

`#include <OgreResourceBackgroundQueue.h>`

Inheritance diagram for Ogre::ResourceBackgroundQueue:
[legend]

## Classes

class | Listener
| This abstract listener interface lets you get notifications of completed background processes instead of having to poll ticket statuses. More...
struct | ResourceRequest
| Encapsulates a queued request for the background queue. More...
struct | ResourceResponse
| Struct that holds details of queued notifications. More...

## Public Member Functions

| ResourceBackgroundQueue ()
virtual | ~ResourceBackgroundQueue ()
void | abortRequest (BackgroundProcessTicket ticket)
| Aborts background process. More...
bool | canHandleRequest (const WorkQueue::Request *req, const WorkQueue *srcQ)
| Implementation for WorkQueue::RequestHandler. More...
bool | canHandleResponse (const WorkQueue::Response *res, const WorkQueue *srcQ)
| Implementation for WorkQueue::ResponseHandler. More...
WorkQueue::Response * | handleRequest (const WorkQueue::Request *req, const WorkQueue *srcQ)
| Implementation for WorkQueue::RequestHandler. More...
void | handleResponse (const WorkQueue::Response *res, const WorkQueue *srcQ)
| Implementation for WorkQueue::ResponseHandler. More...
virtual void | initialise (void)
| Initialise the background queue system. More...
virtual BackgroundProcessTicket | initialiseAllResourceGroups (Listener *listener=0)
| Initialise all resource groups which are yet to be initialised in the background. More...
virtual BackgroundProcessTicket | initialiseResourceGroup (const String &name, Listener *listener=0)
| Initialise a resource group in the background. More...
virtual bool | isProcessComplete (BackgroundProcessTicket ticket)
| Returns whether a previously queued process has completed or not. More...
virtual BackgroundProcessTicket | load (const String &resType, const String &name, const String &group, bool isManual=false, ManualResourceLoader *loader=0, const NameValuePairList *loadParams=0, Listener *listener=0)
| Load a single resource in the background. More...
virtual BackgroundProcessTicket | loadResourceGroup (const String &name, Listener *listener=0)
| Loads a resource group in the background. More...
void | operator delete (void *ptr)
void | operator delete (void *ptr, void *)
void | operator delete (void *ptr, const char *, int, const char *)
void | operator delete[] (void *ptr)
void | operator delete[] (void *ptr, const char *, int, const char *)
void * | operator new (size_t sz, const char *file, int line, const char *func)
| operator new, with debug line info More...
void * | operator new (size_t sz)
void * | operator new (size_t sz, void *ptr)
| placement operator new More...
void * | operator new[] (size_t sz, const char *file, int line, const char *func)
| array operator new, with debug line info More...
void * | operator new[] (size_t sz)
virtual BackgroundProcessTicket | prepare (const String &resType, const String &name, const String &group, bool isManual=false, ManualResourceLoader *loader=0, const NameValuePairList *loadParams=0, Listener *listener=0)
| Prepare a single resource in the background. More...
virtual BackgroundProcessTicket | prepareResourceGroup (const String &name, Listener *listener=0)
| Prepares a resource group in the background. More...
virtual void | shutdown (void)
| Shut down the background queue system. More...
virtual BackgroundProcessTicket | unload (const String &resType, const String &name, Listener *listener=0)
| Unload a single resource in the background. More...
virtual BackgroundProcessTicket | unload (const String &resType, ResourceHandle handle, Listener *listener=0)
| Unload a single resource in the background. More...
virtual BackgroundProcessTicket | unloadResourceGroup (const String &name, Listener *listener=0)
| Unloads a resource group in the background. More...

## Static Public Member Functions

static ResourceBackgroundQueue & | getSingleton (void)
| Override standard Singleton retrieval. More...
static ResourceBackgroundQueue * | getSingletonPtr (void)
| Override standard Singleton retrieval. More...

## Protected Types

typedef set< BackgroundProcessTicket >::type | OutstandingRequestSet
enum | RequestType { RT_INITIALISE_GROUP = 0, RT_INITIALISE_ALL_GROUPS = 1, RT_PREPARE_GROUP = 2, RT_PREPARE_RESOURCE = 3, RT_LOAD_GROUP = 4, RT_LOAD_RESOURCE = 5, RT_UNLOAD_GROUP = 6, RT_UNLOAD_RESOURCE = 7 }
| Enumerates the type of requests. More...

## Protected Member Functions

BackgroundProcessTicket | addRequest (ResourceRequest &req)

## Protected Attributes

OutstandingRequestSet | mOutstandingRequestSet
uint16 | mWorkQueueChannel

## Static Protected Attributes

static ResourceBackgroundQueue * | msSingleton

## Detailed Description

This class is used to perform Resource operations in a background thread.

Remarks
  All these requests are now queued via Root::getWorkQueue in order to share the thread pool amongst all background tasks. You should therefore refer to that class for configuring the behaviour of the threads themselves, this class merely provides an interface that is specific to resource loading around this common functionality.

  The general approach here is that on requesting a background resource process, your request is placed on a queue ready for the background thread to be picked up, and you will get a 'ticket' back, identifying the request. Your call will then return and your thread can proceed, knowing that at some point in the background the operation will be performed. In it's own thread, the resource operation will be performed, and once finished the ticket will be marked as complete. You can check the status of tickets by calling isProcessComplete() from your queueing thread.

Definition at line 81 of file OgreResourceBackgroundQueue.h.

## Member Typedef Documentation

## OutstandingRequestSet

typedef set<BackgroundProcessTicket>::type Ogre::ResourceBackgroundQueue::OutstandingRequestSet

protected

Definition at line 141 of file OgreResourceBackgroundQueue.h.

## Member Enumeration Documentation

## RequestType

enum Ogre::ResourceBackgroundQueue::RequestType

protected

Enumerates the type of requests.

Enumerator
RT_INITIALISE_GROUP |
RT_INITIALISE_ALL_GROUPS |
RT_PREPARE_GROUP |
RT_PREPARE_RESOURCE |
RT_LOAD_GROUP |
RT_LOAD_RESOURCE |
RT_UNLOAD_GROUP |
RT_UNLOAD_RESOURCE |

Definition at line 112 of file OgreResourceBackgroundQueue.h.

## Constructor & Destructor Documentation

## ResourceBackgroundQueue()

Ogre::ResourceBackgroundQueue::ResourceBackgroundQueue | ( |  | ) |

## ~ResourceBackgroundQueue()

virtual Ogre::ResourceBackgroundQueue::~ResourceBackgroundQueue | ( |  | ) |

virtual

## Member Function Documentation

## abortRequest()

void Ogre::ResourceBackgroundQueue::abortRequest | ( | BackgroundProcessTicket | ticket | ) |

Aborts background process.

## addRequest()

BackgroundProcessTicket Ogre::ResourceBackgroundQueue::addRequest | ( | ResourceRequest & | req | ) |

protected

## canHandleRequest()

bool Ogre::ResourceBackgroundQueue::canHandleRequest | ( | const WorkQueue::Request * | req,
|  | const WorkQueue * | srcQ
| ) |  |

virtual

Implementation for WorkQueue::RequestHandler.

Reimplemented from Ogre::WorkQueue::RequestHandler.

## canHandleResponse()

bool Ogre::ResourceBackgroundQueue::canHandleResponse | ( | const WorkQueue::Response * | res,
|  | const WorkQueue * | srcQ
| ) |  |

virtual

Implementation for WorkQueue::ResponseHandler.

Reimplemented from Ogre::WorkQueue::ResponseHandler.

## getSingleton()

static ResourceBackgroundQueue& Ogre::ResourceBackgroundQueue::getSingleton | ( | void |  | ) |

static

Override standard Singleton retrieval.

Remarks
  Why do we do this? Well, it's because the Singleton implementation is in a .h file, which means it gets compiled into anybody who includes it. This is needed for the Singleton template to work, but we actually only want it compiled into the implementation of the class based on the Singleton, not all of them. If we don't change this, we get link errors when trying to use the Singleton-based class from an outside dll.

  This method just delegates to the template version anyway, but the implementation stays in this single compilation unit, preventing link errors.

## getSingletonPtr()

static ResourceBackgroundQueue* Ogre::ResourceBackgroundQueue::getSingletonPtr | ( | void |  | ) |

static

Override standard Singleton retrieval.

Remarks
  Why do we do this? Well, it's because the Singleton implementation is in a .h file, which means it gets compiled into anybody who includes it. This is needed for the Singleton template to work, but we actually only want it compiled into the implementation of the class based on the Singleton, not all of them. If we don't change this, we get link errors when trying to use the Singleton-based class from an outside dll.

  This method just delegates to the template version anyway, but the implementation stays in this single compilation unit, preventing link errors.

## handleRequest()

WorkQueue::Response* Ogre::ResourceBackgroundQueue::handleRequest | ( | const WorkQueue::Request * | req,
|  | const WorkQueue * | srcQ
| ) |  |

virtual

Implementation for WorkQueue::RequestHandler.

Implements Ogre::WorkQueue::RequestHandler.

## handleResponse()

void Ogre::ResourceBackgroundQueue::handleResponse | ( | const WorkQueue::Response * | res,
|  | const WorkQueue * | srcQ
| ) |  |

virtual

Implementation for WorkQueue::ResponseHandler.

Implements Ogre::WorkQueue::ResponseHandler.

## initialise()

virtual void Ogre::ResourceBackgroundQueue::initialise | ( | void |  | ) |

virtual

Initialise the background queue system.

Note
  Called automatically by Root::initialise.

## initialiseAllResourceGroups()

virtual BackgroundProcessTicket Ogre::ResourceBackgroundQueue::initialiseAllResourceGroups | ( | Listener * | listener = `0` | ) |

virtual

Initialise all resource groups which are yet to be initialised in the background.

See also
  ResourceGroupManager::intialiseResourceGroup

Parameters

  listener | Optional callback interface, take note of warnings in the header and only use if you understand them.

Returns
  Ticket identifying the request, use isProcessComplete() to determine if completed if not using listener

## initialiseResourceGroup()

virtual BackgroundProcessTicket Ogre::ResourceBackgroundQueue::initialiseResourceGroup | ( | const String & | name,
|  | Listener * | listener = `0`
| ) |  |

virtual

Initialise a resource group in the background.

See also
  ResourceGroupManager::initialiseResourceGroup

Parameters

  name | The name of the resource group to initialise
  listener | Optional callback interface, take note of warnings in the header and only use if you understand them.

Returns
  Ticket identifying the request, use isProcessComplete() to determine if completed if not using listener

## isProcessComplete()

virtual bool Ogre::ResourceBackgroundQueue::isProcessComplete | ( | BackgroundProcessTicket | ticket | ) |

virtual

Returns whether a previously queued process has completed or not.

Remarks
  This method of checking that a background process has completed is the 'polling' approach. Each queued method takes an optional listener parameter to allow you to register a callback instead, which is arguably more efficient.

Parameters

  ticket | The ticket which was returned when the process was queued

Returns
  true if process has completed (or if the ticket is unrecognised), false otherwise

Note
  Tickets are not stored once complete so do not accumulate over time. This is why a non-existent ticket will return 'true'.

## load()

virtual BackgroundProcessTicket Ogre::ResourceBackgroundQueue::load | ( | const String & | resType,
|  | const String & | name,
|  | const String & | group,
|  | bool | isManual = `false`,
|  | ManualResourceLoader * | loader = `0`,
|  | const NameValuePairList * | loadParams = `0`,
|  | Listener * | listener = `0`
| ) |  |

virtual

Load a single resource in the background.

See also
  ResourceManager::load

Parameters

  resType | The type of the resource (from ResourceManager::getResourceType())
  name | The name of the Resource
  group | The resource group to which this resource will belong
  isManual | Is the resource to be manually loaded? If so, you should provide a value for the loader parameter
  loader | The manual loader which is to perform the required actions when this resource is loaded; only applicable when you specify true for the previous parameter. NOTE: must be thread safe!!
  loadParams | Optional pointer to a list of name/value pairs containing loading parameters for this type of resource. Remember that this must have a lifespan longer than the return of this call!

## loadResourceGroup()

virtual BackgroundProcessTicket Ogre::ResourceBackgroundQueue::loadResourceGroup | ( | const String & | name,
|  | Listener * | listener = `0`
| ) |  |

virtual

Loads a resource group in the background.

See also
  ResourceGroupManager::loadResourceGroup

Parameters

  name | The name of the resource group to load
  listener | Optional callback interface, take note of warnings in the header and only use if you understand them.

Returns
  Ticket identifying the request, use isProcessComplete() to determine if completed if not using listener

## operator delete() [1/3]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete | ( | void * | ptr | ) |

inherited

Definition at line 96 of file OgreMemoryAllocatedObject.h.

## operator delete() [2/3]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete | ( | void * | ptr,
|  | void * |
| ) |  |

inherited

Definition at line 102 of file OgreMemoryAllocatedObject.h.

## operator delete() [3/3]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete | ( | void * | ptr,
|  | const char * | ,
|  | int | ,
|  | const char * |
| ) |  |

inherited

Definition at line 108 of file OgreMemoryAllocatedObject.h.

## operator delete[]() [1/2]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete[] | ( | void * | ptr | ) |

inherited

Definition at line 113 of file OgreMemoryAllocatedObject.h.

## operator delete[]() [2/2]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete[] | ( | void * | ptr,
|  | const char * | ,
|  | int | ,
|  | const char * |
| ) |  |

inherited

Definition at line 119 of file OgreMemoryAllocatedObject.h.

## operator new() [1/3]

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new | ( | size_t | sz,
|  | const char * | file,
|  | int | line,
|  | const char * | func
| ) |  |

inherited

operator new, with debug line info

Definition at line 68 of file OgreMemoryAllocatedObject.h.

## operator new() [2/3]

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new | ( | size_t | sz | ) |

inherited

Definition at line 73 of file OgreMemoryAllocatedObject.h.

## operator new() [3/3]

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new | ( | size_t | sz,
|  | void * | ptr
| ) |  |

inherited

placement operator new

Definition at line 79 of file OgreMemoryAllocatedObject.h.

## operator new[]() [1/2]

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new[] | ( | size_t | sz,
|  | const char * | file,
|  | int | line,
|  | const char * | func
| ) |  |

inherited

array operator new, with debug line info

Definition at line 86 of file OgreMemoryAllocatedObject.h.

## operator new[]() [2/2]

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new[] | ( | size_t | sz | ) |

inherited

Definition at line 91 of file OgreMemoryAllocatedObject.h.

## prepare()

virtual BackgroundProcessTicket Ogre::ResourceBackgroundQueue::prepare | ( | const String & | resType,
|  | const String & | name,
|  | const String & | group,
|  | bool | isManual = `false`,
|  | ManualResourceLoader * | loader = `0`,
|  | const NameValuePairList * | loadParams = `0`,
|  | Listener * | listener = `0`
| ) |  |

virtual

Prepare a single resource in the background.

See also
  ResourceManager::prepare

Parameters

  resType | The type of the resource (from ResourceManager::getResourceType())
  name | The name of the Resource
  group | The resource group to which this resource will belong
  isManual | Is the resource to be manually loaded? If so, you should provide a value for the loader parameter
  loader | The manual loader which is to perform the required actions when this resource is loaded; only applicable when you specify true for the previous parameter. NOTE: must be thread safe!!
  loadParams | Optional pointer to a list of name/value pairs containing loading parameters for this type of resource. Remember that this must have a lifespan longer than the return of this call!

## prepareResourceGroup()

virtual BackgroundProcessTicket Ogre::ResourceBackgroundQueue::prepareResourceGroup | ( | const String & | name,
|  | Listener * | listener = `0`
| ) |  |

virtual

Prepares a resource group in the background.

See also
  ResourceGroupManager::prepareResourceGroup

Parameters

  name | The name of the resource group to prepare
  listener | Optional callback interface, take note of warnings in the header and only use if you understand them.

Returns
  Ticket identifying the request, use isProcessComplete() to determine if completed if not using listener

## shutdown()

virtual void Ogre::ResourceBackgroundQueue::shutdown | ( | void |  | ) |

virtual

Shut down the background queue system.

Note
  Called automatically by Root::shutdown.

## unload() [1/2]

virtual BackgroundProcessTicket Ogre::ResourceBackgroundQueue::unload | ( | const String & | resType,
|  | const String & | name,
|  | Listener * | listener = `0`
| ) |  |

virtual

Unload a single resource in the background.

See also
  ResourceManager::unload

Parameters

  resType | The type of the resource (from ResourceManager::getResourceType())
  name | The name of the Resource

## unload() [2/2]

virtual BackgroundProcessTicket Ogre::ResourceBackgroundQueue::unload | ( | const String & | resType,
|  | ResourceHandle | handle,
|  | Listener * | listener = `0`
| ) |  |

virtual

Unload a single resource in the background.

See also
  ResourceManager::unload

Parameters

  resType | The type of the resource (from ResourceManager::getResourceType())
  handle | Handle to the resource

## unloadResourceGroup()

virtual BackgroundProcessTicket Ogre::ResourceBackgroundQueue::unloadResourceGroup | ( | const String & | name,
|  | Listener * | listener = `0`
| ) |  |

virtual

Unloads a resource group in the background.

See also
  ResourceGroupManager::unloadResourceGroup

Parameters

  name | The name of the resource group to load

Returns
  Ticket identifying the request, use isProcessComplete() to determine if completed if not using listener

## Member Data Documentation

## mOutstandingRequestSet

OutstandingRequestSet Ogre::ResourceBackgroundQueue::mOutstandingRequestSet

protected

Definition at line 142 of file OgreResourceBackgroundQueue.h.

## msSingleton

ResourceBackgroundQueue * Ogre::Singleton< ResourceBackgroundQueue >::msSingleton

static protected inherited

Definition at line 75 of file OgreSingleton.h.

## mWorkQueueChannel

uint16 Ogre::ResourceBackgroundQueue::mWorkQueueChannel

protected

Definition at line 110 of file OgreResourceBackgroundQueue.h.

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

- OgreResourceBackgroundQueue.h

Copyright © 2012 Torus Knot Software Ltd
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.