# Ogre::ResourceBackgroundQueue Class Reference
[Resources]

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

`#include <OgreResourceBackgroundQueue.h>`

Inheritance diagram for Ogre::ResourceBackgroundQueue:
[legend]

List of all members.

## 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 ()
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, Listener *listener=0)
| Initialise a resource group in the background.
virtual BackgroundProcessTicket | initialiseAllResourceGroups (Listener *listener=0)
| Initialise all resource groups which are yet to be initialised in the background.
virtual BackgroundProcessTicket | prepareResourceGroup (const String &name, Listener *listener=0)
| Prepares a resource group in the background.
virtual BackgroundProcessTicket | loadResourceGroup (const String &name, Listener *listener=0)
| Loads a resource group in the background.
virtual BackgroundProcessTicket | unload (const String &resType, const String &name, Listener *listener=0)
| Unload a single resource in the background.
virtual BackgroundProcessTicket | unload (const String &resType, ResourceHandle handle, Listener *listener=0)
| Unload a single resource in the background.
virtual BackgroundProcessTicket | unloadResourceGroup (const String &name, Listener *listener=0)
| Unloads a resource group in the background.
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.
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.
virtual bool | isProcessComplete (BackgroundProcessTicket ticket)
| Returns whether a previously queued process has completed or not.
void | abortRequest (BackgroundProcessTicket ticket)
| Aborts background process.
bool | canHandleRequest (const WorkQueue::Request *req, const WorkQueue *srcQ)
| Implementation for WorkQueue::RequestHandler.
WorkQueue::Response * | handleRequest (const WorkQueue::Request *req, const WorkQueue *srcQ)
| Implementation for WorkQueue::RequestHandler.
bool | canHandleResponse (const WorkQueue::Response *res, const WorkQueue *srcQ)
| Implementation for WorkQueue::ResponseHandler.
void | handleResponse (const WorkQueue::Response *res, const WorkQueue *srcQ)
| Implementation for WorkQueue::ResponseHandler.
void * | operator new (size_t sz, const char *file, int line, const char *func)
| operator new, with debug line info
void * | operator new (size_t sz)
void * | operator new (size_t sz, void *ptr)
| placement operator new
void * | operator new[] (size_t sz, const char *file, int line, const char *func)
| array operator new, with debug line info
void * | operator new[] (size_t sz)
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 *)
virtual bool | canHandleRequest (const Request *req, const WorkQueue *srcQ)
| Return whether this handler can process a given request.
virtual Response * | handleRequest (const Request *req, const WorkQueue *srcQ)=0
| The handler method every subclass must implement.

## Static Public Member Functions

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

## Protected Types

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...
typedef set < BackgroundProcessTicket > ::type | OutstandingRequestSet

## Protected Member Functions

BackgroundProcessTicket | addRequest (ResourceRequest &req)

## Protected Attributes

uint16 | mWorkQueueChannel
OutstandingRequestSet | mOutstandingRequestSet

## Static Protected Attributes

static ResourceBackgroundQueue * | ms_Singleton

## 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 80 of file OgreResourceBackgroundQueue.h.

## Member Typedef Documentation

typedef set<BackgroundProcessTicket>::type Ogre::ResourceBackgroundQueue::OutstandingRequestSet `[protected]`

Definition at line 140 of file OgreResourceBackgroundQueue.h.

## Member Enumeration Documentation

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 111 of file OgreResourceBackgroundQueue.h.

## Constructor & Destructor Documentation

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

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

## Member Function Documentation

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

Aborts background process.

BackgroundProcessTicket Ogre::ResourceBackgroundQueue::addRequest | ( | ResourceRequest & | req | ) | `[protected]`

virtual bool Ogre::WorkQueue::RequestHandler::canHandleRequest | ( | const Request * | req,
|  | const WorkQueue * | srcQ |
| ) |  |  | `[virtual, inherited]`

Return whether this handler can process a given request.

Remarks:
  Defaults to true, but if you wish to add several handlers each of which deal with different types of request, you can override this method.

Definition at line 172 of file OgreWorkQueue.h.

References Ogre::WorkQueue::Request::getAborted().

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

Implementation for WorkQueue::RequestHandler.

bool Ogre::ResourceBackgroundQueue::canHandleResponse | ( | const WorkQueue::Response * | res,
|  | const WorkQueue * | srcQ |
| ) |  |  | `[virtual]`

Implementation for WorkQueue::ResponseHandler.

Reimplemented from Ogre::WorkQueue::ResponseHandler.

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.

static ResourceBackgroundQueue & Ogre::Singleton< ResourceBackgroundQueue >::getSingleton | ( | void |  | ) | `[static, inherited]`

Definition at line 90 of file OgreSingleton.h.

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.

static ResourceBackgroundQueue * Ogre::Singleton< ResourceBackgroundQueue >::getSingletonPtr | ( | void |  | ) | `[static, inherited]`

Definition at line 92 of file OgreSingleton.h.

virtual Response* Ogre::WorkQueue::RequestHandler::handleRequest | ( | const Request * | req,
|  | const WorkQueue * | srcQ |
| ) |  |  | `[pure virtual, inherited]`

The handler method every subclass must implement.

If a failure is encountered, return a Response with a failure result rather than raise an exception.

Parameters:

  | req | The Request structure, which is effectively owned by the handler during this call. It must be attached to the returned Response regardless of success or failure.
  | srcQ | The work queue that this request originated from

Returns:
  Pointer to a Response object - the caller is responsible for deleting the object.

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

Implementation for WorkQueue::RequestHandler.

void Ogre::ResourceBackgroundQueue::handleResponse | ( | const WorkQueue::Response * | res,
|  | const WorkQueue * | srcQ |
| ) |  |  | `[virtual]`

Implementation for WorkQueue::ResponseHandler.

Implements Ogre::WorkQueue::ResponseHandler.

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

Initialise the background queue system.

Note:
  Called automatically by Root::initialise.

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

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

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

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!

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

template<class Alloc >

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

Definition at line 101 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

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

Definition at line 95 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

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

Definition at line 107 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

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

Definition at line 112 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

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

Definition at line 118 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

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

placement operator new

Definition at line 78 of file OgreMemoryAllocatedObject.h.

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 67 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

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

Definition at line 72 of file OgreMemoryAllocatedObject.h.

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 85 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

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

Definition at line 90 of file OgreMemoryAllocatedObject.h.

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!

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

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

Shut down the background queue system.

Note:
  Called automatically by Root::shutdown.

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

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

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

OutstandingRequestSet Ogre::ResourceBackgroundQueue::mOutstandingRequestSet `[protected]`

Definition at line 141 of file OgreResourceBackgroundQueue.h.

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

Definition at line 75 of file OgreSingleton.h.

uint16 Ogre::ResourceBackgroundQueue::mWorkQueueChannel `[protected]`

Definition at line 109 of file OgreResourceBackgroundQueue.h.

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

- OgreResourceBackgroundQueue.h

Copyright © 2008 Torus Knot Software Ltd
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.
Last modified Wed Nov 3 2010 19:24:59