#include <stageCache.h>

Classes
class	Id

Public Member Functions
USD_API	UsdStageCache ()
	Default construct an empty cache. More...

USD_API	UsdStageCache (const UsdStageCache &other)
	Construct a new cache as a copy of `other`. More...

USD_API	~UsdStageCache ()
	Destructor. More...

USD_API UsdStageCache &	operator= (const UsdStageCache &other)
	Replace the contents of this cache with a copy of `other`. More...

USD_API void	swap (UsdStageCache &other)
	Swap the contents of this cache with `other`. More...

USD_API std::vector < UsdStageRefPtr >	GetAllStages () const
	Return a vector containing the stages present in this cache. More...

USD_API size_t	Size () const
	Return the number of stages present in this cache. More...

bool	IsEmpty () const
	Return true if this cache holds no stages, false otherwise. More...

USD_API std::pair < UsdStageRefPtr, bool >	RequestStage (UsdStageCacheRequest &&request)

USD_API UsdStageRefPtr	Find (Id id) const

USD_API UsdStageRefPtr	FindOneMatching (const SdfLayerHandle &rootLayer) const

USD_API UsdStageRefPtr	FindOneMatching (const SdfLayerHandle &rootLayer, const SdfLayerHandle &sessionLayer) const

USD_API UsdStageRefPtr	FindOneMatching (const SdfLayerHandle &rootLayer, const ArResolverContext &pathResolverContext) const

USD_API UsdStageRefPtr	FindOneMatching (const SdfLayerHandle &rootLayer, const SdfLayerHandle &sessionLayer, const ArResolverContext &pathResolverContext) const

USD_API std::vector < UsdStageRefPtr >	FindAllMatching (const SdfLayerHandle &rootLayer) const

USD_API std::vector < UsdStageRefPtr >	FindAllMatching (const SdfLayerHandle &rootLayer, const SdfLayerHandle &sessionLayer) const

USD_API std::vector < UsdStageRefPtr >	FindAllMatching (const SdfLayerHandle &rootLayer, const ArResolverContext &pathResolverContext) const

USD_API std::vector < UsdStageRefPtr >	FindAllMatching (const SdfLayerHandle &rootLayer, const SdfLayerHandle &sessionLayer, const ArResolverContext &pathResolverContext) const

USD_API Id	GetId (const UsdStageRefPtr &stage) const

bool	Contains (const UsdStageRefPtr &stage) const
	Return true if `stage` is present in this cache, false otherwise. More...

bool	Contains (Id id) const
	Return true if `id` is present in this cache, false otherwise. More...

USD_API Id	Insert (const UsdStageRefPtr &stage)

USD_API bool	Erase (Id id)

USD_API bool	Erase (const UsdStageRefPtr &stage)

USD_API size_t	EraseAll (const SdfLayerHandle &rootLayer)

USD_API size_t	EraseAll (const SdfLayerHandle &rootLayer, const SdfLayerHandle &sessionLayer)

USD_API size_t	EraseAll (const SdfLayerHandle &rootLayer, const SdfLayerHandle &sessionLayer, const ArResolverContext &pathResolverContext)

USD_API void	Clear ()

USD_API void	SetDebugName (const std::string &debugName)

USD_API std::string	GetDebugName () const

Friends
void	swap (UsdStageCache &lhs, UsdStageCache &rhs)

Detailed Description

A strongly concurrency safe collection of UsdStageRefPtr s, enabling sharing across multiple clients and threads. See UsdStageCacheContext for typical use cases finding UsdStage s in a cache and publishing UsdStage s to a cache.

UsdStageCache is strongly thread safe: all operations other than construction and destruction may be performed concurrently.

Clients typically populate and fetch UsdStage s in caches by binding a UsdStageCacheContext object to a cache, then using the UsdStage::Open() API. See UsdStageCacheContext for more details. Clients may also populate and fetch directly via UsdStageCache::Insert(), UsdStageCache::Find(), UsdStageCache::FindOneMatching(), and UsdStageCache::FindAllMatching() API.

Caches provide a mechanism that associates a lightweight key, UsdStageCache::Id, with a cached stage. A UsdStageCache::Id can be converted to and from long int and string. This can be useful for communicating within a third party application that cannot transmit arbitrary C++ objects. See UsdStageCache::GetId().

Clients may iterate all cache elements using UsdStageCache::GetAllStages() and remove elements with UsdStageCache::Erase(), UsdStageCache::EraseAll(), and UsdStageCache::Clear().

Note that this class is a regular type: it can be copied and assigned at will. It is not a singleton. Also, since it holds a collection of UsdStageRefPtr objects, copying it does not create new UsdStage instances, it merely copies the RefPtrs.

Enabling the USD_STAGE_CACHE TF_DEBUG code will issue debug output for UsdStageCache Find/Insert/Erase/Clear operations. Also see UsdStageCache::SetDebugName() and UsdStageCache::GetDebugName().

Definition at line 84 of file stageCache.h.

Constructor & Destructor Documentation

USD_API UsdStageCache::UsdStageCache ( )

Default construct an empty cache.

USD_API UsdStageCache::UsdStageCache ( const UsdStageCache & other )

Construct a new cache as a copy of other.

USD_API UsdStageCache::~UsdStageCache ( )

Destructor.

Member Function Documentation

USD_API void UsdStageCache::Clear ( )

Remove all entries from this cache, leaving it empty and equivalent to a default-constructed cache. Since the cache contains UsdStageRefPtr, erasing a stage from the cache will only destroy the stage if no other UsdStageRefPtrs exist referring to it.

bool UsdStageCache::Contains ( const UsdStageRefPtr & stage ) const

inline

Return true if stage is present in this cache, false otherwise.

Definition at line 306 of file stageCache.h.

bool UsdStageCache::Contains ( Id id ) const

inline

Return true if id is present in this cache, false otherwise.

Definition at line 311 of file stageCache.h.

USD_API bool UsdStageCache::Erase ( Id id )

Erase the stage identified by id from this cache and return true. If id is invalid or there is no associated stage in this cache, do nothing and return false. Since the cache contains UsdStageRefPtr, erasing a stage from the cache will only destroy the stage if no other UsdStageRefPtrs exist referring to it.

USD_API bool UsdStageCache::Erase ( const UsdStageRefPtr & stage )

Erase stage from this cache and return true. If stage is not present in this cache, do nothing and return false. Since the cache contains UsdStageRefPtr, erasing a stage from the cache will only destroy the stage if no other UsdStageRefPtrs exist referring to it.

USD_API size_t UsdStageCache::EraseAll ( const SdfLayerHandle & rootLayer )

Erase all stages present in the cache with rootLayer and return the number erased. Since the cache contains UsdStageRefPtr, erasing a stage from the cache will only destroy the stage if no other UsdStageRefPtrs exist referring to it.

USD_API size_t UsdStageCache::EraseAll	(	const SdfLayerHandle &	rootLayer,
		const SdfLayerHandle &	sessionLayer
	)

Erase all stages present in the cache with rootLayer and sessionLayer and return the number erased. Since the cache contains UsdStageRefPtr, erasing a stage from the cache will only destroy the stage if no other UsdStageRefPtrs exist referring to it.

USD_API size_t UsdStageCache::EraseAll	(	const SdfLayerHandle &	rootLayer,
		const SdfLayerHandle &	sessionLayer,
		const ArResolverContext &	pathResolverContext
	)

Erase all stages present in the cache with rootLayer, sessionLayer, and pathResolverContext and return the number erased. Since the cache contains UsdStageRefPtr, erasing a stage from the cache will only destroy the stage if no other UsdStageRefPtrs exist referring to it.

USD_API UsdStageRefPtr UsdStageCache::Find ( Id id ) const

Find the stage in this cache corresponding to id in this cache. If id is not valid (see Id::IsValid()) or if this cache does not have a stage corresponding to id, return null.

USD_API std::vector<UsdStageRefPtr> UsdStageCache::FindAllMatching ( const SdfLayerHandle & rootLayer ) const

Find all stages in this cache with rootLayer. If there is no matching stage in this cache, return an empty vector.

USD_API std::vector<UsdStageRefPtr> UsdStageCache::FindAllMatching	(	const SdfLayerHandle &	rootLayer,
		const SdfLayerHandle &	sessionLayer
	)		const

Find all stages in this cache with rootLayer and sessionLayer. If there is no matching stage in this cache, return an empty vector.

USD_API std::vector<UsdStageRefPtr> UsdStageCache::FindAllMatching	(	const SdfLayerHandle &	rootLayer,
		const ArResolverContext &	pathResolverContext
	)		const

Find all stages in this cache with rootLayer and pathResolverContext. If there is no matching stage in this cache, return an empty vector.

USD_API std::vector<UsdStageRefPtr> UsdStageCache::FindAllMatching	(	const SdfLayerHandle &	rootLayer,
		const SdfLayerHandle &	sessionLayer,
		const ArResolverContext &	pathResolverContext
	)		const

Find all stages in this cache with rootLayer, sessionLayer, and pathResolverContext. If there is no matching stage in this cache, return an empty vector. If there is more than one matching stage in this cache, return an arbitrary matching one.

USD_API UsdStageRefPtr UsdStageCache::FindOneMatching ( const SdfLayerHandle & rootLayer ) const

Find a stage in this cache with rootLayer. If there is no matching stage in this cache, return null. If there is more than one matching stage in this cache, return an arbitrary matching one. See also FindAllMatching().

USD_API UsdStageRefPtr UsdStageCache::FindOneMatching	(	const SdfLayerHandle &	rootLayer,
		const SdfLayerHandle &	sessionLayer
	)		const

Find a stage in this cache with rootLayer and sessionLayer. If there is no matching stage in this cache, return null. If there is more than one matching stage in this cache, return an arbitrary matching one. See also FindAllMatching().

USD_API UsdStageRefPtr UsdStageCache::FindOneMatching	(	const SdfLayerHandle &	rootLayer,
		const ArResolverContext &	pathResolverContext
	)		const

Find a stage in this cache with rootLayer and pathResolverContext. If there is no matching stage in this cache, return null. If there is more than one matching stage in this cache, return an arbitrary matching one.

See Also: FindAllMatching()

USD_API UsdStageRefPtr UsdStageCache::FindOneMatching	(	const SdfLayerHandle &	rootLayer,
		const SdfLayerHandle &	sessionLayer,
		const ArResolverContext &	pathResolverContext
	)		const

Find a stage in this cache with rootLayer, sessionLayer, and pathResolverContext. If there is no matching stage in this cache, return null. If there is more than one matching stage in this cache, return an arbitrary matching one.

See Also: FindAllMatching()

USD_API std::vector<UsdStageRefPtr> UsdStageCache::GetAllStages ( ) const

Return a vector containing the stages present in this cache.

USD_API std::string UsdStageCache::GetDebugName ( ) const

Retrieve this cache's debug name, set with SetDebugName(). If no debug name has been assigned, return the empty string.

USD_API Id UsdStageCache::GetId ( const UsdStageRefPtr & stage ) const

Return the Id associated with stage in this cache. If stage is not present in this cache, return an invalid Id.

USD_API Id UsdStageCache::Insert ( const UsdStageRefPtr & stage )

Insert stage into this cache and return its associated Id. If the given stage is already present in this cache, simply return its associated Id.

bool UsdStageCache::IsEmpty ( ) const

inline

Return true if this cache holds no stages, false otherwise.

Definition at line 198 of file stageCache.h.

USD_API UsdStageCache& UsdStageCache::operator= ( const UsdStageCache & other )

Replace the contents of this cache with a copy of other.

USD_API std::pair<UsdStageRefPtr, bool> UsdStageCache::RequestStage ( UsdStageCacheRequest && request )

Find an existing stage in the cache that satisfies request, or invoke request.Manufacture() to create one and insert it into the cache. Return the resulting stage and a bool indicating whether or not this call manufactured the stage.

This avoids race conditions in concurrent code that can occur using the other public methods. Consider this racy example:

if (!cache.FindOneMatching(rootLayer)) {
    auto stage = UsdStage::Open(rootLayer);
    cache.Insert(stage);
}

This will race with another thread doing the same thing, resulting in two stages with the same root layer inserted in the cache. This is potentially rather inefficient since stage creation can be expensive, depending on how many objects and how many prims & layers the stage contains. RequestStage() avoids this by ensuring that there is no race and the stage is created only once.

Note that request should not be retained and must not be reused.

USD_API void UsdStageCache::SetDebugName ( const std::string & debugName )

Assign a debug name to this cache. This will be emitted in debug output messages when the USD_STAGE_CACHES debug flag is enabled. If set to the empty string, the cache's address will be used instead.

USD_API size_t UsdStageCache::Size ( ) const

Return the number of stages present in this cache.

USD_API void UsdStageCache::swap ( UsdStageCache & other )

Swap the contents of this cache with other.

Friends And Related Function Documentation

void swap	(	UsdStageCache &	lhs,
		UsdStageCache &	rhs
	)

friend

Definition at line 378 of file stageCache.h.

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

pxr/usd/usd/stageCache.h

Classes

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation