# Ogre::ResourceBackgroundQueue Class Reference

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

`#include <OgreResourceBackgroundQueue.h>`

Inheritance diagram for Ogre::ResourceBackgroundQueue:

List of all members.

## Public Member Functions

| ResourceBackgroundQueue ()
| Private mutex, not allowed to lock from outside.
virtual | ~ResourceBackgroundQueue ()
virtual void | initialise (void)
| Initialise the background queue system.
virtual void | shutdown (void)
| Shut down the background queue system.
virtual BackgroundProcessTicket | initialiseResourceGroup (const String &name, ResourceBackgroundQueueListener *listener=0)
| Initialise a resource group in the background.
virtual BackgroundProcessTicket | initialiseAllResourceGroups (ResourceBackgroundQueueListener *listener=0)
| Initialise all resource groups which are yet to be initialised in the background.
virtual BackgroundProcessTicket | loadResourceGroup (const String &name, ResourceBackgroundQueueListener *listener=0)
| Loads a resource group in the background.
virtual BackgroundProcessTicket | load (const String &resType, const String &name, const String &group, bool isManual=false, ManualResourceLoader *loader=0, const NameValuePairList *loadParams=0, ResourceBackgroundQueueListener *listener=0)
| Load a single resource in the background.
virtual bool | isProcessComplete (BackgroundProcessTicket ticket)
| Returns whether a previously queued process has completed or not.

## Static Public Member Functions

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

## Protected Types

typedef std::list< Request > | RequestQueue
typedef std::map< BackgroundProcessTicket, Request * > | RequestTicketMap
enum | RequestType { RT_INITIALISE_GROUP, RT_INITIALISE_ALL_GROUPS, RT_LOAD_GROUP, RT_LOAD_RESOURCE, RT_SHUTDOWN }
| Enumerates the type of requests. More...

## Protected Attributes

RequestQueue | mRequestQueue
| Queue of requests, used to store and order requests.
RequestTicketMap | mRequestTicketMap
| Request lookup by ticket.
unsigned long | mNextTicketID
| Next ticket ID.
void * | mThread
| Dummy.

## Static Protected Attributes

ResourceBackgroundQueue * | ms_Singleton

## Detailed Description

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

Remarks:
  If threading is enabled, Ogre will create a single background thread which can be used to load / unload resources in parallel. Only one resource will be processed at once in this background thread, but it will be in parallel with the main thread.

  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 wil 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. It is also possible to get immediate callbacks on completion, but these callbacks happen in the background loading thread (not your calling thread), so should only be used if you really understand multithreading.

Note:
  This class will only perform tasks in a background thread if OGRE_THREAD_SUPPORT is defined to be 1. Otherwise, all methods will call their exact equivalents in ResourceGroupManager synchronously.

Definition at line 90 of file OgreResourceBackgroundQueue.h.

## Member Typedef Documentation

typedef std::list<Request> Ogre::ResourceBackgroundQueue::RequestQueue `[protected]`

| Definition at line 115 of file OgreResourceBackgroundQueue.h.

typedef std::map<BackgroundProcessTicket, Request*> Ogre::ResourceBackgroundQueue::RequestTicketMap `[protected]`

| Definition at line 116 of file OgreResourceBackgroundQueue.h.

## Member Enumeration Documentation

enum Ogre::ResourceBackgroundQueue::RequestType `[protected]`

Enumerates the type of requests.

Enumeration values:

  RT_INITIALISE_GROUP |
  RT_INITIALISE_ALL_GROUPS |
  RT_LOAD_GROUP |
  RT_LOAD_RESOURCE |
  RT_SHUTDOWN |

Definition at line 94 of file OgreResourceBackgroundQueue.h.

## Constructor & Destructor Documentation

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

| Private mutex, not allowed to lock from outside.

virtual Ogre::ResourceBackgroundQueue::~ResourceBackgroundQueue | ( |  | ) | `[virtual]`

## Member Function Documentation

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.

Reimplemented from Ogre::Singleton< ResourceBackgroundQueue >.

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.

Reimplemented from Ogre::Singleton< ResourceBackgroundQueue >.

virtual void Ogre::ResourceBackgroundQueue::initialise | ( | void |  | ) | `[virtual]`

| Initialise the background queue system.

virtual BackgroundProcessTicket Ogre::ResourceBackgroundQueue::initialiseAllResourceGroups | ( | ResourceBackgroundQueueListener * | 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

virtual BackgroundProcessTicket Ogre::ResourceBackgroundQueue::initialiseResourceGroup | ( | const String & | name,
|  | ResourceBackgroundQueueListener * | 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

virtual bool Ogre::ResourceBackgroundQueue::isProcessComplete | ( | BackgroundProcessTicket | ticket | ) | `[virtual]`

Returns whether a previously queued process has completed or not.

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 onced complete so do not accumulate over time. This is why a non-existent ticket will return 'true'.

virtual BackgroundProcessTicket Ogre::ResourceBackgroundQueue::load | ( | const String & | resType,
|  | const String & | name,
|  | const String & | group,
|  | bool | isManual = false,
|  | ManualResourceLoader * | loader = 0,
|  | const NameValuePairList * | loadParams = 0,
|  | ResourceBackgroundQueueListener * | 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!

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

Loads a resource group 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

virtual void Ogre::ResourceBackgroundQueue::shutdown | ( | void |  | ) | `[virtual]`

| Shut down the background queue system.

## Member Data Documentation

unsigned long Ogre::ResourceBackgroundQueue::mNextTicketID `[protected]`

| Next ticket ID. Definition at line 125 of file OgreResourceBackgroundQueue.h.

RequestQueue Ogre::ResourceBackgroundQueue::mRequestQueue `[protected]`

| Queue of requests, used to store and order requests. Definition at line 119 of file OgreResourceBackgroundQueue.h.

RequestTicketMap Ogre::ResourceBackgroundQueue::mRequestTicketMap `[protected]`

| Request lookup by ticket. Definition at line 122 of file OgreResourceBackgroundQueue.h.

ResourceBackgroundQueue * Ogre::Singleton< ResourceBackgroundQueue >::ms_Singleton `[static, protected, inherited]`

| Definition at line 54 of file OgreSingleton.h.

void* Ogre::ResourceBackgroundQueue::mThread `[protected]`

| Dummy. Definition at line 138 of file OgreResourceBackgroundQueue.h.

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

- OgreResourceBackgroundQueue.h

Copyright © 2000-2005 by The OGRE Team
This work is licensed under a Creative Commons Attribution-ShareAlike 2.5 License.
Last modified Sun Feb 12 13:02:48 2006