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

#include <OgreResourceBackgroundQueue.h>

Inheritance diagram for Ogre::ResourceBackgroundQueue:

Classes
class	Listener
	This abstract listener interface lets you get notifications of completed background processes instead of having to poll ticket statuses. More...

Public Member Functions
	ResourceBackgroundQueue ()

	~ResourceBackgroundQueue () override

void	abortRequest (BackgroundProcessTicket ticket)
	Aborts background process. More...

bool	canHandleRequest (const WorkQueue::Request req, const WorkQueue srcQ) override
	Implementation for WorkQueue::RequestHandler. More...

bool	canHandleResponse (const WorkQueue::Response res, const WorkQueue srcQ) override
	Implementation for WorkQueue::ResponseHandler. More...

WorkQueue::Response *	handleRequest (const WorkQueue::Request req, const WorkQueue srcQ) override
	Implementation for WorkQueue::RequestHandler. More...

void	handleResponse (const WorkQueue::Response res, const WorkQueue srcQ) override
	Implementation for WorkQueue::ResponseHandler. More...

virtual void	initialise ()
	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...

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

Public Member Functions inherited from Ogre::Singleton< ResourceBackgroundQueue >
	Singleton ()

	~Singleton ()

Public Member Functions inherited from Ogre::WorkQueue::RequestHandler
	RequestHandler ()

virtual	~RequestHandler ()

Public Member Functions inherited from Ogre::WorkQueue::ResponseHandler
	ResponseHandler ()

virtual	~ResponseHandler ()

Static Public Member Functions
static ResourceBackgroundQueue &	getSingleton ()
	Override standard Singleton retrieval. More...

static ResourceBackgroundQueue *	getSingletonPtr ()
	Override standard Singleton retrieval. More...

Static Public Member Functions inherited from Ogre::Singleton< ResourceBackgroundQueue >
static ResourceBackgroundQueue &	getSingleton ()

static ResourceBackgroundQueue *	getSingletonPtr ()

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.

Constructor & Destructor Documentation

◆ ResourceBackgroundQueue()

Ogre::ResourceBackgroundQueue::ResourceBackgroundQueue ( )

◆ ~ResourceBackgroundQueue()

Ogre::ResourceBackgroundQueue::~ResourceBackgroundQueue ( )

override

Member Function Documentation

◆ abortRequest()

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

Aborts background process.

◆ canHandleRequest()

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

overridevirtual

Implementation for WorkQueue::RequestHandler.

Reimplemented from Ogre::WorkQueue::RequestHandler.

◆ canHandleResponse()

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

overridevirtual

Implementation for WorkQueue::ResponseHandler.

Reimplemented from Ogre::WorkQueue::ResponseHandler.

◆ getSingleton()

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

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

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
	)

overridevirtual

Implementation for WorkQueue::RequestHandler.

Implements Ogre::WorkQueue::RequestHandler.

◆ handleResponse()

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

overridevirtual

Implementation for WorkQueue::ResponseHandler.

Implements Ogre::WorkQueue::ResponseHandler.

◆ initialise()

virtual void Ogre::ResourceBackgroundQueue::initialise ( )

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

◆ 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 ( )

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

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

OgreResourceBackgroundQueue.h

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ResourceBackgroundQueue()

◆ ~ResourceBackgroundQueue()

Member Function Documentation

◆ abortRequest()

◆ canHandleRequest()

◆ canHandleResponse()

◆ getSingleton()

◆ getSingletonPtr()

◆ handleRequest()

◆ handleResponse()

◆ initialise()

◆ initialiseAllResourceGroups()

◆ initialiseResourceGroup()

◆ isProcessComplete()

◆ load()

◆ loadResourceGroup()

◆ prepare()

◆ prepareResourceGroup()

◆ shutdown()

◆ unload() [1/2]

◆ unload() [2/2]

◆ unloadResourceGroup()