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:

[legend]List of all members.


Public Member Functions
	ResourceBackgroundQueue ()
virtual	~ResourceBackgroundQueue ()
void	setStartBackgroundThread (bool startThread)
	Sets whether or not a thread should be created and started to handle the background loading, or whether a user thread will call the appropriate hooks.
bool	getStartBackgroundThread (void)
	Gets whether or not a thread should be created and started to handle the background loading, or whether a user thread will call the appropriate hooks.
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.
bool	_doNextQueuedBackgroundProcess ()
	Process a single queued background operation.
void	_initThread ()
	Initialise processing for a background thread.
virtual void	_queueFireBackgroundPreparingComplete (Resource *res)
	Queue the firing of the 'background preparing complete' event to a Resource::Listener event.
virtual void	_queueFireBackgroundLoadingComplete (Resource *res)
	Queue the firing of the 'background loading complete' event to a Resource::Listener event.
virtual void	_fireOnFrameCallbacks (void)
	Fires all the queued events for background loaded resources.
	Singleton (void)
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 *)
Static Public Member Functions
static ResourceBackgroundQueue &	getSingleton (void)
	Override standard Singleton retrieval.
static ResourceBackgroundQueue *	getSingletonPtr (void)
	Override standard Singleton retrieval.
Protected Types
typedef std::list< Request >	RequestQueue
typedef std::map< BackgroundProcessTicket, Request * >	RequestTicketMap
typedef std::list< QueuedNotification >	NotificationQueue
enum	RequestType { 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, RT_SHUTDOWN }
	Enumerates the type of requests. More...
Protected Member Functions
virtual OGRE_AUTO_MUTEX void	queueFireBackgroundOperationComplete (Request *req)
	Queue the firing of the 'background loading complete' event to a Resource::Listener event.
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.
NotificationQueue	mNotificationQueue
	Queued notifications of background loading being finished.
bool	mStartThread
	Whether this class should start it's own thread or not.
void *	mThread
	Dummy.
Static Protected Attributes
static ResourceBackgroundQueue *	ms_Singleton
Classes
class	Listener
	This abstract listener interface lets you get notifications of completed background processes instead of having to poll ticket statuses. More...
struct	QueuedNotification
	Struct that holds details of queued notifications. More...
struct	Request
	Encapsulates a queued request for the background queue. More...

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

: By default, when threading is enabled this class will start its own separate thread to perform the actual loading. However, if you would prefer to use your own existing thread to perform the background load, then be sure to call setStartBackgroundThread(false) before initialise() is called by Root::initialise. Your own thread should call _initThread immediately on startup, before any resources are loaded at all, and _doNextQueuedBackgroundProcess to process background requests.

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

Member Typedef Documentation

typedef std::list<QueuedNotification> Ogre::ResourceBackgroundQueue::NotificationQueue [protected]

Definition at line 185 of file OgreResourceBackgroundQueue.h.

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

Definition at line 156 of file OgreResourceBackgroundQueue.h.

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

Definition at line 157 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_PREPARE_GROUP

RT_PREPARE_RESOURCE

RT_LOAD_GROUP

RT_LOAD_RESOURCE

RT_UNLOAD_GROUP

RT_UNLOAD_RESOURCE

RT_SHUTDOWN

Definition at line 129 of file OgreResourceBackgroundQueue.h.

Constructor & Destructor Documentation

Ogre::ResourceBackgroundQueue::ResourceBackgroundQueue ( )

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

Member Function Documentation

bool Ogre::ResourceBackgroundQueue::_doNextQueuedBackgroundProcess ( )

Process a single queued background operation.

Remarks:
If you are using your own thread to perform background loading, calling this method from that thread triggers the processing of a single background loading request from the queue. This method will not return until the request has been fully processed. It also returns whether it did in fact process anything - if it returned false, there was nothing more in the queue.

Note:
Do not call this method unless you are using your own thread to perform the background loading and called setStartBackgroundThread(false). You must only have one background loading thread.

Returns:
true if a request was processed, false if the queue was empty.

virtual void Ogre::ResourceBackgroundQueue::_fireOnFrameCallbacks ( void ) [virtual]

Fires all the queued events for background loaded resources.

Remarks:
You should call this from the thread that runs the main frame loop to avoid having to make the receivers of this event thread-safe. If you use Ogre's built in frame loop you don't need to call this yourself.

void Ogre::ResourceBackgroundQueue::_initThread ( )

Initialise processing for a background thread.

Remarks:
You must call this method if you use your own thread rather than letting this class create its own. Moreover, you must call it after initialise() and after you've started your own thread, but before any resources have been loaded. There are some per-thread tasks which have to be performed on some rendering APIs and it's important that they are done before rendering resources are created.

You must call this method in your own background thread, not the main thread. It's important to block the main thread whilst this initialisation is happening, use an OGRE_THREAD_WAIT on the public initSync token after locking the initMutex.

virtual void Ogre::ResourceBackgroundQueue::_queueFireBackgroundLoadingComplete ( Resource * res ) [virtual]

Queue the firing of the 'background loading complete' event to a Resource::Listener event.

Remarks:
The purpose of this is to allow the background loading thread to call this method to queue the notification to listeners waiting on the background loading of a resource. Rather than allow the resource background loading thread to directly call these listeners, which would require all the listeners to be thread-safe, this method implements a thread-safe queue which can be processed in the main frame loop thread each frame to clear the events in a simpler manner.

Parameters:

res The resource listened on

virtual void Ogre::ResourceBackgroundQueue::_queueFireBackgroundPreparingComplete ( Resource * res ) [virtual]

Queue the firing of the 'background preparing complete' event to a Resource::Listener event.

Remarks:
The purpose of this is to allow the background thread to call this method to queue the notification to listeners waiting on the background preparing of a resource. Rather than allow the resource background thread to directly call these listeners, which would require all the listeners to be thread-safe, this method implements a thread-safe queue which can be processed in the main frame loop thread each frame to clear the events in a simpler manner.

Parameters:

res The resource listened on

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.

Reimplemented from Ogre::Singleton< ResourceBackgroundQueue >.

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.

Reimplemented from Ogre::Singleton< ResourceBackgroundQueue >.

bool Ogre::ResourceBackgroundQueue::getStartBackgroundThread ( void )

Gets whether or not a thread should be created and started to handle the background loading, or whether a user thread will call the appropriate hooks.

Definition at line 255 of file OgreResourceBackgroundQueue.h.

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,

const char * ,

int ,

const char *

) [inherited]

Definition at line 101 of file OgreMemoryAllocatedObject.h.

template<class Alloc>

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

void *

) [inherited]

Definition at line 95 of file OgreMemoryAllocatedObject.h.

template<class Alloc>

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

Definition at line 89 of file OgreMemoryAllocatedObject.h.

template<class Alloc>

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

const char * ,

int ,

const char *

) [inherited]

Definition at line 112 of file OgreMemoryAllocatedObject.h.

template<class Alloc>

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

Definition at line 106 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 73 of file OgreMemoryAllocatedObject.h.

template<class Alloc>

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

Definition at line 67 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 62 of file OgreMemoryAllocatedObject.h.

template<class Alloc>

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

Definition at line 84 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 79 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 OGRE_AUTO_MUTEX void Ogre::ResourceBackgroundQueue::queueFireBackgroundOperationComplete ( Request * req ) [protected, virtual]

Queue the firing of the 'background loading complete' event to a Resource::Listener event.

Remarks:
The purpose of this is to allow the background loading thread to call this method to queue the notification to listeners waiting on the background loading of a resource. Rather than allow the resource background loading thread to directly call these listeners, which would require all the listeners to be thread-safe, this method implements a thread-safe queue which can be processed in the main frame loop thread each frame to clear the events in a simpler manner.

Parameters:

listener The listener to be notified

ticket The ticket for the operation that has completed

void Ogre::ResourceBackgroundQueue::setStartBackgroundThread ( bool startThread )

Sets whether or not a thread should be created and started to handle the background loading, or whether a user thread will call the appropriate hooks.

Remarks:
By default, a new thread will be started to handle the background load requests. However, the application may well have some threads of its own which is wishes to use to perform the background loading as well as other tasks (for example on most platforms there will be a fixed number of hardware threads which the application will wish to work within). Use this method to turn off the creation of a separate thread if you wish, and call the _doNextQueuedBackgroundProcess method from your own thread to process background requests.

Note:
You must call this method prior to initialisation. Initialisation of this class is automatically done when Root::initialise is called.

Definition at line 249 of file OgreResourceBackgroundQueue.h.

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

Shut down the background queue system.

Note:
Called automatically by Root::shutdown.

Ogre::Singleton< ResourceBackgroundQueue >::Singleton ( void ) [inherited]

Definition at line 64 of file OgreSingleton.h.

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

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

Next ticket ID.

Definition at line 166 of file OgreResourceBackgroundQueue.h.

NotificationQueue Ogre::ResourceBackgroundQueue::mNotificationQueue [protected]

Queued notifications of background loading being finished.

Definition at line 187 of file OgreResourceBackgroundQueue.h.

RequestQueue Ogre::ResourceBackgroundQueue::mRequestQueue [protected]

Queue of requests, used to store and order requests.

Definition at line 160 of file OgreResourceBackgroundQueue.h.

RequestTicketMap Ogre::ResourceBackgroundQueue::mRequestTicketMap [protected]

Request lookup by ticket.

Definition at line 163 of file OgreResourceBackgroundQueue.h.

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

Definition at line 61 of file OgreSingleton.h.

bool Ogre::ResourceBackgroundQueue::mStartThread [protected]

Whether this class should start it's own thread or not.

Definition at line 192 of file OgreResourceBackgroundQueue.h.

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

Dummy.

Definition at line 207 of file OgreResourceBackgroundQueue.h.

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

OgreResourceBackgroundQueue.h

Ogre::ResourceBackgroundQueue Class Reference

Public Member Functions

Static Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Static Protected Attributes

Classes