HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
stageCache.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_USD_USD_STAGE_CACHE_H
25 #define PXR_USD_USD_STAGE_CACHE_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/usd/usd/api.h"
31 
32 #include <hboost/lexical_cast.hpp>
33 #include <hboost/operators.hpp>
34 
35 #include <string>
36 #include <memory>
37 #include <mutex>
38 #include <vector>
39 
41 
42 
45 
46 class ArResolverContext;
47 
49 
50 /// \class UsdStageCache
51 ///
52 /// A strongly concurrency safe collection of UsdStageRefPtr s, enabling
53 /// sharing across multiple clients and threads. See UsdStageCacheContext for
54 /// typical use cases finding UsdStage s in a cache and publishing UsdStage s to
55 /// a cache.
56 ///
57 /// UsdStageCache is strongly thread safe: all operations other than
58 /// construction and destruction may be performed concurrently.
59 ///
60 /// Clients typically populate and fetch UsdStage s in caches by binding a
61 /// UsdStageCacheContext object to a cache, then using the UsdStage::Open() API.
62 /// See UsdStageCacheContext for more details. Clients may also populate and
63 /// fetch directly via UsdStageCache::Insert(), UsdStageCache::Find(),
64 /// UsdStageCache::FindOneMatching(), and UsdStageCache::FindAllMatching()
65 /// API.
66 ///
67 /// Caches provide a mechanism that associates a lightweight key,
68 /// UsdStageCache::Id, with a cached stage. A UsdStageCache::Id can be
69 /// converted to and from long int and string. This can be useful for
70 /// communicating within a third party application that cannot transmit
71 /// arbitrary C++ objects. See UsdStageCache::GetId().
72 ///
73 /// Clients may iterate all cache elements using UsdStageCache::GetAllStages()
74 /// and remove elements with UsdStageCache::Erase(),
75 /// UsdStageCache::EraseAll(), and UsdStageCache::Clear().
76 ///
77 /// Note that this class is a regular type: it can be copied and assigned at
78 /// will. It is not a singleton. Also, since it holds a collection of
79 /// UsdStageRefPtr objects, copying it does not create new UsdStage instances,
80 /// it merely copies the RefPtrs.
81 ///
82 /// Enabling the USD_STAGE_CACHE TF_DEBUG code will issue debug output for
83 /// UsdStageCache Find/Insert/Erase/Clear operations. Also see
84 /// UsdStageCache::SetDebugName() and UsdStageCache::GetDebugName().
85 ///
87 {
88 public:
89  /// \class Id
90  ///
91  /// A lightweight identifier that may be used to identify a
92  /// particular cached stage within a UsdStageCache. An identifier may be
93  /// converted to and from long int and string, to facilitate use within
94  /// restricted contexts.
95  ///
96  /// Id objects are only valid with the stage from which they were obtained.
97  /// It never makes sense to use an Id with a stage other than the one it was
98  /// obtained from.
99  ///
100  struct Id : private hboost::totally_ordered<Id> {
101  /// Default construct an invalid id.
102  Id() : _value(-1) {}
103 
104  /// Create an Id from an integral value. The supplied \p val must have
105  /// been obtained by calling ToLongInt() previously.
106  static Id FromLongInt(long int val) { return Id(val); }
107 
108  /// Create an Id from a string value. The supplied \p val must have
109  /// been obtained by calling ToString() previously.
110  static Id FromString(const std::string &s) {
111  return FromLongInt(hboost::lexical_cast<long int>(s));
112  }
113 
114  /// Convert this Id to an integral representation.
115  long int ToLongInt() const { return _value; }
116 
117  /// Convert this Id to a string representation.
119  return hboost::lexical_cast<std::string>(ToLongInt());
120  }
121 
122  /// Return true if this Id is valid.
123  bool IsValid() const { return _value != -1; }
124 
125  /// Return true if this Id is valid.
126  explicit operator bool() const { return IsValid(); }
127 
128  private:
129  /// Equality comparison.
130  friend bool operator==(const Id &lhs, const Id &rhs) {
131  return lhs.ToLongInt() == rhs.ToLongInt();
132  }
133  /// Less-than comparison.
134  friend bool operator<(const Id &lhs, const Id &rhs) {
135  return lhs.ToLongInt() < rhs.ToLongInt();
136  }
137  /// Hash.
138  friend size_t hash_value(Id id) {
139  return ~size_t(id.ToLongInt());
140  }
141 
142  explicit Id(long int val) : _value(val) {}
143 
144  long int _value;
145  };
146 
147  /// Default construct an empty cache.
148  USD_API
149  UsdStageCache();
150 
151  /// Construct a new cache as a copy of \p other.
152  USD_API
153  UsdStageCache(const UsdStageCache &other);
154 
155  /// Destructor.
156  USD_API
157  ~UsdStageCache();
158 
159  /// Replace the contents of this cache with a copy of \p other.
160  USD_API
161  UsdStageCache &operator=(const UsdStageCache &other);
162 
163  /// Swap the contents of this cache with \p other.
164  USD_API
165  void swap(UsdStageCache &other);
166 
167  /// Return a vector containing the stages present in this cache.
168  USD_API
169  std::vector<UsdStageRefPtr> GetAllStages() const;
170 
171  /// Return the number of stages present in this cache.
172  USD_API
173  size_t Size() const;
174 
175  /// Return true if this cache holds no stages, false otherwise.
176  bool IsEmpty() const { return Size() == 0; }
177 
178  /// Find an existing stage in the cache that satisfies \p request, or invoke
179  /// request.Manufacture() to create one and insert it into the cache.
180  /// Return the resulting stage and a bool indicating whether or not this
181  /// call manufactured the stage.
182  ///
183  /// This avoids race conditions in concurrent code that can occur using the
184  /// other public methods. Consider this racy example:
185  ///
186  /// \code
187  /// if (!cache.FindOneMatching(rootLayer)) {
188  /// auto stage = UsdStage::Open(rootLayer);
189  /// cache.Insert(stage);
190  /// }
191  /// \endcode
192  ///
193  /// This will race with another thread doing the same thing, resulting in
194  /// two stages with the same root layer inserted in the cache. This is
195  /// potentially rather inefficient since stage creation can be expensive,
196  /// depending on how many objects and how many prims & layers the stage
197  /// contains. RequestStage() avoids this by ensuring that there is no race
198  /// and the stage is created only once.
199  ///
200  /// Note that request should not be retained and must not be reused.
201  USD_API
202  std::pair<UsdStageRefPtr, bool>
204 
205  /// Find the stage in this cache corresponding to \p id in this cache. If
206  /// \p id is not valid (see Id::IsValid()) or if this cache does not have a
207  /// stage corresponding to \p id, return null.
208  USD_API
209  UsdStageRefPtr Find(Id id) const;
210 
211  /// Find a stage in this cache with \p rootLayer. If there is no matching
212  /// stage in this cache, return null. If there is more than one matching
213  /// stage in this cache, return an arbitrary matching one. See also
214  /// FindAllMatching().
215  USD_API
216  UsdStageRefPtr FindOneMatching(const SdfLayerHandle &rootLayer) const;
217 
218  /// Find a stage in this cache with \p rootLayer and \p sessionLayer. If
219  /// there is no matching stage in this cache, return null. If there is more
220  /// than one matching stage in this cache, return an arbitrary matching one.
221  /// See also FindAllMatching().
222  USD_API
223  UsdStageRefPtr FindOneMatching(const SdfLayerHandle &rootLayer,
224  const SdfLayerHandle &sessionLayer) const;
225 
226  /// Find a stage in this cache with \p rootLayer and \p pathResolverContext.
227  /// If there is no matching stage in this cache, return null. If there is
228  /// more than one matching stage in this cache, return an arbitrary matching
229  /// one.
230  /// \sa FindAllMatching()
231  USD_API
232  UsdStageRefPtr FindOneMatching(
233  const SdfLayerHandle &rootLayer,
234  const ArResolverContext &pathResolverContext) const;
235 
236  /// Find a stage in this cache with \p rootLayer, \p sessionLayer, and
237  /// \p pathResolverContext. If there is no matching stage in this cache,
238  /// return null. If there is more than one matching stage in this cache,
239  /// return an arbitrary matching one.
240  /// \sa FindAllMatching()
241  USD_API
242  UsdStageRefPtr FindOneMatching(
243  const SdfLayerHandle &rootLayer,
244  const SdfLayerHandle &sessionLayer,
245  const ArResolverContext &pathResolverContext) const;
246 
247  /// Find all stages in this cache with \p rootLayer. If there is no
248  /// matching stage in this cache, return an empty vector.
249  USD_API
250  std::vector<UsdStageRefPtr>
251  FindAllMatching(const SdfLayerHandle &rootLayer) const;
252 
253  /// Find all stages in this cache with \p rootLayer and \p sessionLayer.
254  /// If there is no matching stage in this cache, return an empty vector.
255  USD_API
256  std::vector<UsdStageRefPtr>
257  FindAllMatching(const SdfLayerHandle &rootLayer,
258  const SdfLayerHandle &sessionLayer) const;
259 
260  /// Find all stages in this cache with \p rootLayer and
261  /// \p pathResolverContext. If there is no matching stage in this cache,
262  /// return an empty vector.
263  USD_API
264  std::vector<UsdStageRefPtr>
265  FindAllMatching(const SdfLayerHandle &rootLayer,
266  const ArResolverContext &pathResolverContext) const;
267 
268  /// Find all stages in this cache with \p rootLayer, \p sessionLayer, and
269  /// \p pathResolverContext. If there is no matching stage in this cache,
270  /// return an empty vector. If there is more than one matching stage in
271  /// this cache, return an arbitrary matching one.
272  USD_API
273  std::vector<UsdStageRefPtr>
274  FindAllMatching(const SdfLayerHandle &rootLayer,
275  const SdfLayerHandle &sessionLayer,
276  const ArResolverContext &pathResolverContext) const;
277 
278  /// Return the Id associated with \p stage in this cache. If \p stage is
279  /// not present in this cache, return an invalid Id.
280  USD_API
281  Id GetId(const UsdStageRefPtr &stage) const;
282 
283  /// Return true if \p stage is present in this cache, false otherwise.
284  bool Contains(const UsdStageRefPtr &stage) const {
285  return static_cast<bool>(GetId(stage));
286  }
287 
288  /// Return true if \p id is present in this cache, false otherwise.
289  bool Contains(Id id) const { return Find(id); }
290 
291  /// Insert \p stage into this cache and return its associated Id. If the
292  /// given \p stage is already present in this cache, simply return its
293  /// associated Id.
294  USD_API
295  Id Insert(const UsdStageRefPtr &stage);
296 
297  /// Erase the stage identified by \p id from this cache and return true. If
298  /// \p id is invalid or there is no associated stage in this cache, do
299  /// nothing and return false. Since the cache contains UsdStageRefPtr,
300  /// erasing a stage from the cache will only destroy the stage if no other
301  /// UsdStageRefPtrs exist referring to it.
302  USD_API
303  bool Erase(Id id);
304 
305  /// Erase \p stage from this cache and return true. If \p stage is not
306  /// present in this cache, do nothing and return false. Since the cache
307  /// contains UsdStageRefPtr, erasing a stage from the cache will only
308  /// destroy the stage if no other UsdStageRefPtrs exist referring to it.
309  USD_API
310  bool Erase(const UsdStageRefPtr &stage);
311 
312  /// Erase all stages present in the cache with \p rootLayer and return the
313  /// number erased. Since the cache contains UsdStageRefPtr, erasing a stage
314  /// from the cache will only destroy the stage if no other UsdStageRefPtrs
315  /// exist referring to it.
316  USD_API
317  size_t EraseAll(const SdfLayerHandle &rootLayer);
318 
319  /// Erase all stages present in the cache with \p rootLayer and
320  /// \p sessionLayer and return the number erased. Since the cache contains
321  /// UsdStageRefPtr, erasing a stage from the cache will only destroy the
322  /// stage if no other UsdStageRefPtrs exist referring to it.
323  USD_API
324  size_t EraseAll(const SdfLayerHandle &rootLayer,
325  const SdfLayerHandle &sessionLayer);
326 
327  /// Erase all stages present in the cache with \p rootLayer,
328  /// \p sessionLayer, and \p pathResolverContext and return the number
329  /// erased. Since the cache contains UsdStageRefPtr, erasing a stage from
330  /// the cache will only destroy the stage if no other UsdStageRefPtrs
331  /// exist referring to it.
332  USD_API
333  size_t EraseAll(const SdfLayerHandle &rootLayer,
334  const SdfLayerHandle &sessionLayer,
335  const ArResolverContext &pathResolverContext);
336 
337  /// Remove all entries from this cache, leaving it empty and equivalent to a
338  /// default-constructed cache. Since the cache contains UsdStageRefPtr,
339  /// erasing a stage from the cache will only destroy the stage if no other
340  /// UsdStageRefPtrs exist referring to it.
341  USD_API
342  void Clear();
343 
344  /// Assign a debug name to this cache. This will be emitted in debug output
345  /// messages when the USD_STAGE_CACHES debug flag is enabled. If set to the
346  /// empty string, the cache's address will be used instead.
347  USD_API
348  void SetDebugName(const std::string &debugName);
349 
350  /// Retrieve this cache's debug name, set with SetDebugName(). If no debug
351  /// name has been assigned, return the empty string.
352  USD_API
353  std::string GetDebugName() const;
354 
355 private:
356  friend void swap(UsdStageCache &lhs, UsdStageCache &rhs) {
357  lhs.swap(rhs);
358  }
359 
360  typedef struct Usd_StageCacheImpl _Impl;
361  std::unique_ptr<_Impl> _impl;
362  mutable std::mutex _mutex;
363 };
364 
366 {
367 public:
368  USD_API
369  virtual ~UsdStageCacheRequest();
370 
371  // Return true if the stage satisfies this request.
372  virtual bool IsSatisfiedBy(UsdStageRefPtr const &stage) const = 0;
373 
374  // Return true if the pending request will satisfy this request, once
375  // complete.
376  virtual bool IsSatisfiedBy(UsdStageCacheRequest const &pending) const = 0;
377 
378  // Invoked to manufacture a stage to insert in the cache. Postcondition:
379  // IsSatisfiedBy() must return true for the resulting stage.
380  virtual UsdStageRefPtr Manufacture() = 0;
381 
382 private:
383  friend class UsdStageCache;
384 
385  struct _Mailbox;
386  void _Subscribe(_Mailbox *);
387 
388  struct _Data;
389  struct _DataDeleter { void operator()(_Data *); };
390  std::unique_ptr<_Data, _DataDeleter> _data;
391 };
392 
393 
395 
396 #endif // PXR_USD_USD_STAGE_CACHE_H
USD_API UsdStageCache()
Default construct an empty cache.
Definition: layer.h:96
virtual USD_API ~UsdStageCacheRequest()
#define USD_API
Definition: api.h:40
friend size_t hash_value(Id id)
Hash.
Definition: stageCache.h:138
USD_API std::vector< UsdStageRefPtr > GetAllStages() const
Return a vector containing the stages present in this cache.
USD_API std::pair< UsdStageRefPtr, bool > RequestStage(UsdStageCacheRequest &&request)
static Id FromString(const std::string &s)
Definition: stageCache.h:110
USD_API UsdStageRefPtr Find(Id id) const
USD_API UsdStageRefPtr FindOneMatching(const SdfLayerHandle &rootLayer) const
PXR_NAMESPACE_OPEN_SCOPE SDF_DECLARE_HANDLES(SdfLayer)
USD_API void Clear()
bool Contains(Id id) const
Return true if id is present in this cache, false otherwise.
Definition: stageCache.h:289
USD_API void SetDebugName(const std::string &debugName)
USD_API bool Erase(Id id)
virtual bool IsSatisfiedBy(UsdStageRefPtr const &stage) const =0
friend void swap(UsdStageCache &lhs, UsdStageCache &rhs)
Definition: stageCache.h:356
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.
Definition: stageCache.h:176
friend bool operator==(const Id &lhs, const Id &rhs)
Equality comparison.
Definition: stageCache.h:130
GLsizei const GLchar *const * string
Definition: glcorearb.h:813
std::string ToString() const
Convert this Id to a string representation.
Definition: stageCache.h:118
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.
Definition: stageCache.h:284
Id()
Default construct an invalid id.
Definition: stageCache.h:102
USD_API UsdStageCache & operator=(const UsdStageCache &other)
Replace the contents of this cache with a copy of other.
USD_API Id Insert(const UsdStageRefPtr &stage)
USD_API ~UsdStageCache()
Destructor.
static Id FromLongInt(long int val)
Definition: stageCache.h:106
GLuint GLfloat * val
Definition: glcorearb.h:1607
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1375
friend bool operator<(const Id &lhs, const Id &rhs)
Less-than comparison.
Definition: stageCache.h:134
USD_API std::vector< UsdStageRefPtr > FindAllMatching(const SdfLayerHandle &rootLayer) const
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
USD_API void swap(UsdStageCache &other)
Swap the contents of this cache with other.
bool IsValid() const
Return true if this Id is valid.
Definition: stageCache.h:123
virtual UsdStageRefPtr Manufacture()=0
long int ToLongInt() const
Convert this Id to an integral representation.
Definition: stageCache.h:115
TF_DECLARE_REF_PTRS(UsdStage)
GLdouble s
Definition: glew.h:1395
USD_API size_t EraseAll(const SdfLayerHandle &rootLayer)
USD_API std::string GetDebugName() const