All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
UsdStageCache Class Reference

A strongly concurrency safe collection of UsdStageRefPtr s, enabling sharing across multiple clients and threads. More...

#include <stageCache.h>

Classes

class  Id
 A lightweight identifier that may be used to identify a particular cached stage within a UsdStageCache. More...
 

Public Member Functions

USD_API UsdStageCache ()
 Default construct an empty cache.
 
USD_API UsdStageCache (const UsdStageCache &other)
 Construct a new cache as a copy of other.
 
USD_API ~UsdStageCache ()
 Destructor.
 
USD_API UsdStageCacheoperator= (const UsdStageCache &other)
 Replace the contents of this cache with a copy of other.
 
USD_API void swap (UsdStageCache &other)
 Swap the contents of this cache with other.
 
USD_API std::vector< UsdStageRefPtr > GetAllStages () const
 Return a vector containing the stages present in this cache.
 
USD_API size_t Size () const
 Return the number of stages present in this cache.
 
bool IsEmpty () const
 Return true if this cache holds no stages, false otherwise.
 
USD_API std::pair< UsdStageRefPtr, bool > 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.
 
USD_API UsdStageRefPtr Find (Id id) const
 Find the stage in this cache corresponding to id in this cache.
 
USD_API UsdStageRefPtr FindOneMatching (const SdfLayerHandle &rootLayer) const
 Find a stage in this cache with rootLayer.
 
USD_API UsdStageRefPtr FindOneMatching (const SdfLayerHandle &rootLayer, const SdfLayerHandle &sessionLayer) const
 Find a stage in this cache with rootLayer and sessionLayer.
 
USD_API UsdStageRefPtr FindOneMatching (const SdfLayerHandle &rootLayer, const ArResolverContext &pathResolverContext) const
 Find a stage in this cache with rootLayer and pathResolverContext.
 
USD_API UsdStageRefPtr FindOneMatching (const SdfLayerHandle &rootLayer, const SdfLayerHandle &sessionLayer, const ArResolverContext &pathResolverContext) const
 Find a stage in this cache with rootLayer, sessionLayer, and pathResolverContext.
 
USD_API std::vector< UsdStageRefPtr > FindAllMatching (const SdfLayerHandle &rootLayer) const
 Find all stages in this cache with rootLayer.
 
USD_API std::vector< UsdStageRefPtr > FindAllMatching (const SdfLayerHandle &rootLayer, const SdfLayerHandle &sessionLayer) const
 Find all stages in this cache with rootLayer and sessionLayer.
 
USD_API std::vector< UsdStageRefPtr > FindAllMatching (const SdfLayerHandle &rootLayer, const ArResolverContext &pathResolverContext) const
 Find all stages in this cache with rootLayer and pathResolverContext.
 
USD_API std::vector< UsdStageRefPtr > FindAllMatching (const SdfLayerHandle &rootLayer, const SdfLayerHandle &sessionLayer, const ArResolverContext &pathResolverContext) const
 Find all stages in this cache with rootLayer, sessionLayer, and pathResolverContext.
 
USD_API Id GetId (const UsdStageRefPtr &stage) const
 Return the Id associated with stage in this cache.
 
bool Contains (const UsdStageRefPtr &stage) const
 Return true if stage is present in this cache, false otherwise.
 
bool Contains (Id id) const
 Return true if id is present in this cache, false otherwise.
 
USD_API Id Insert (const UsdStageRefPtr &stage)
 Insert stage into this cache and return its associated Id.
 
USD_API bool Erase (Id id)
 Erase the stage identified by id from this cache and return true.
 
USD_API bool Erase (const UsdStageRefPtr &stage)
 Erase stage from this cache and return true.
 
USD_API size_t EraseAll (const SdfLayerHandle &rootLayer)
 Erase all stages present in the cache with rootLayer and return the number erased.
 
USD_API size_t EraseAll (const SdfLayerHandle &rootLayer, const SdfLayerHandle &sessionLayer)
 Erase all stages present in the cache with rootLayer and sessionLayer and return the number erased.
 
USD_API size_t 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.
 
USD_API void Clear ()
 Remove all entries from this cache, leaving it empty and equivalent to a default-constructed cache.
 
USD_API void SetDebugName (const std::string &debugName)
 Assign a debug name to this cache.
 
USD_API std::string GetDebugName () const
 Retrieve this cache's debug name, set with SetDebugName().
 

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

Constructor & Destructor Documentation

◆ UsdStageCache() [1/2]

USD_API UsdStageCache ( )

Default construct an empty cache.

◆ UsdStageCache() [2/2]

USD_API UsdStageCache ( const UsdStageCache other)

Construct a new cache as a copy of other.

◆ ~UsdStageCache()

USD_API ~UsdStageCache ( )

Destructor.

Member Function Documentation

◆ Clear()

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

◆ Contains() [1/2]

bool Contains ( const UsdStageRefPtr &  stage) const
inline

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

Definition at line 289 of file stageCache.h.

◆ Contains() [2/2]

bool Contains ( Id  id) const
inline

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

Definition at line 294 of file stageCache.h.

◆ Erase() [1/2]

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

◆ Erase() [2/2]

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

◆ EraseAll() [1/3]

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

◆ EraseAll() [2/3]

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

◆ EraseAll() [3/3]

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

◆ Find()

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

◆ FindAllMatching() [1/4]

USD_API std::vector< UsdStageRefPtr > 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.

◆ FindAllMatching() [2/4]

USD_API std::vector< UsdStageRefPtr > 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.

◆ FindAllMatching() [3/4]

USD_API std::vector< UsdStageRefPtr > 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.

◆ FindAllMatching() [4/4]

USD_API std::vector< UsdStageRefPtr > 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.

◆ FindOneMatching() [1/4]

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

◆ FindOneMatching() [2/4]

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

◆ FindOneMatching() [3/4]

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

◆ FindOneMatching() [4/4]

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

◆ GetAllStages()

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

Return a vector containing the stages present in this cache.

◆ GetDebugName()

USD_API std::string GetDebugName ( ) const

Retrieve this cache's debug name, set with SetDebugName().

If no debug name has been assigned, return the empty string.

◆ GetId()

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

◆ Insert()

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

◆ IsEmpty()

bool IsEmpty ( ) const
inline

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

Definition at line 181 of file stageCache.h.

◆ operator=()

USD_API UsdStageCache & operator= ( const UsdStageCache other)

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

◆ RequestStage()

USD_API std::pair< UsdStageRefPtr, bool > 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);
}
static USD_API UsdStageRefPtr Open(const std::string &filePath, InitialLoadSet load=LoadAll)
Attempt to find a matching existing stage in a cache if UsdStageCacheContext objects exist on the sta...

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.

◆ SetDebugName()

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

◆ Size()

USD_API size_t Size ( ) const

Return the number of stages present in this cache.

◆ swap()

USD_API void swap ( UsdStageCache other)

Swap the contents of this cache with other.

Friends And Related Function Documentation

◆ swap

void swap ( UsdStageCache lhs,
UsdStageCache rhs 
)
friend

Definition at line 361 of file stageCache.h.


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