|
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 UsdStageCache & | operator= (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) |
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.
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 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.
|
inline |
Return true if stage
is present in this cache, false otherwise.
Definition at line 289 of file stageCache.h.
|
inline |
Return true if id
is present in this cache, false otherwise.
Definition at line 294 of file stageCache.h.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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().
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.
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().
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.
USD_API std::vector< UsdStageRefPtr > GetAllStages | ( | ) | const |
Return a vector containing the stages present in this cache.
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.
USD_API Id GetId | ( | const UsdStageRefPtr & | stage | ) | const |
USD_API Id Insert | ( | const UsdStageRefPtr & | stage | ) |
|
inline |
Return true if this cache holds no stages, false otherwise.
Definition at line 181 of file stageCache.h.
USD_API UsdStageCache & operator= | ( | const UsdStageCache & | other | ) |
Replace the contents of this cache with a copy of other
.
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:
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 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 Size | ( | ) | const |
Return the number of stages present in this cache.
USD_API void swap | ( | UsdStageCache & | other | ) |
Swap the contents of this cache with other
.
|
friend |
Definition at line 361 of file stageCache.h.