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

#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 UsdStageCacheoperator= (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 85 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 299 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 304 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 191 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 371 of file stageCache.h.


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