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"
32 
33 #include <string>
34 #include <memory>
35 #include <mutex>
36 #include <vector>
37 
39 
40 
43 
44 class ArResolverContext;
45 
47 
48 /// \class UsdStageCache
49 ///
50 /// A strongly concurrency safe collection of UsdStageRefPtr s, enabling
51 /// sharing across multiple clients and threads. See UsdStageCacheContext for
52 /// typical use cases finding UsdStage s in a cache and publishing UsdStage s to
53 /// a cache.
54 ///
55 /// UsdStageCache is strongly thread safe: all operations other than
56 /// construction and destruction may be performed concurrently.
57 ///
58 /// Clients typically populate and fetch UsdStage s in caches by binding a
59 /// UsdStageCacheContext object to a cache, then using the UsdStage::Open() API.
60 /// See UsdStageCacheContext for more details. Clients may also populate and
61 /// fetch directly via UsdStageCache::Insert(), UsdStageCache::Find(),
62 /// UsdStageCache::FindOneMatching(), and UsdStageCache::FindAllMatching()
63 /// API.
64 ///
65 /// Caches provide a mechanism that associates a lightweight key,
66 /// UsdStageCache::Id, with a cached stage. A UsdStageCache::Id can be
67 /// converted to and from long int and string. This can be useful for
68 /// communicating within a third party application that cannot transmit
69 /// arbitrary C++ objects. See UsdStageCache::GetId().
70 ///
71 /// Clients may iterate all cache elements using UsdStageCache::GetAllStages()
72 /// and remove elements with UsdStageCache::Erase(),
73 /// UsdStageCache::EraseAll(), and UsdStageCache::Clear().
74 ///
75 /// Note that this class is a regular type: it can be copied and assigned at
76 /// will. It is not a singleton. Also, since it holds a collection of
77 /// UsdStageRefPtr objects, copying it does not create new UsdStage instances,
78 /// it merely copies the RefPtrs.
79 ///
80 /// Enabling the USD_STAGE_CACHE TF_DEBUG code will issue debug output for
81 /// UsdStageCache Find/Insert/Erase/Clear operations. Also see
82 /// UsdStageCache::SetDebugName() and UsdStageCache::GetDebugName().
83 ///
85 {
86 public:
87  /// \class Id
88  ///
89  /// A lightweight identifier that may be used to identify a
90  /// particular cached stage within a UsdStageCache. An identifier may be
91  /// converted to and from long int and string, to facilitate use within
92  /// restricted contexts.
93  ///
94  /// Id objects are only valid with the stage from which they were obtained.
95  /// It never makes sense to use an Id with a stage other than the one it was
96  /// obtained from.
97  ///
98  struct Id {
99  /// Default construct an invalid id.
100  Id() : _value(-1) {}
101 
102  /// Create an Id from an integral value. The supplied \p val must have
103  /// been obtained by calling ToLongInt() previously.
104  static Id FromLongInt(long int val) { return Id(val); }
105 
106  /// Create an Id from a string value. The supplied \p val must have
107  /// been obtained by calling ToString() previously.
108  static Id FromString(const std::string &s) {
109  bool overflow = false;
110  const long int result = TfStringToLong(s, &overflow);
111  if (overflow) {
113  "'%s' overflowed during conversion to int64_t.",
114  s.c_str()
115  );
116  }
117  return FromLongInt(result);
118  }
119 
120  /// Convert this Id to an integral representation.
121  long int ToLongInt() const { return _value; }
122 
123  /// Convert this Id to a string representation.
125  return TfStringify(ToLongInt());
126  }
127 
128  /// Return true if this Id is valid.
129  bool IsValid() const { return _value != -1; }
130 
131  /// Return true if this Id is valid.
132  explicit operator bool() const { return IsValid(); }
133 
134  private:
135  /// Equality comparison.
136  friend bool operator==(const Id &lhs, const Id &rhs) {
137  return lhs.ToLongInt() == rhs.ToLongInt();
138  }
139  /// Inequality comparison.
140  friend bool operator!=(const Id &lhs, const Id &rhs) {
141  return !(lhs == rhs);
142  }
143  /// Less-than comparison.
144  friend bool operator<(const Id &lhs, const Id &rhs) {
145  return lhs.ToLongInt() < rhs.ToLongInt();
146  }
147  /// Less-than or equal comparison.
148  friend bool operator<=(const Id &lhs, const Id &rhs) {
149  return !(rhs < lhs);
150  }
151  /// Greater-than comparison.
152  friend bool operator>(const Id &lhs, const Id &rhs) {
153  return rhs < lhs;
154  }
155  /// Greater-than or equal comparison.
156  friend bool operator>=(const Id &lhs, const Id &rhs) {
157  return !(lhs < rhs);
158  }
159  /// Hash.
160  friend size_t hash_value(Id id) {
161  return ~size_t(id.ToLongInt());
162  }
163 
164  explicit Id(long int val) : _value(val) {}
165 
166  long int _value;
167  };
168 
169  /// Default construct an empty cache.
170  USD_API
171  UsdStageCache();
172 
173  /// Construct a new cache as a copy of \p other.
174  USD_API
175  UsdStageCache(const UsdStageCache &other);
176 
177  /// Destructor.
178  USD_API
179  ~UsdStageCache();
180 
181  /// Replace the contents of this cache with a copy of \p other.
182  USD_API
183  UsdStageCache &operator=(const UsdStageCache &other);
184 
185  /// Swap the contents of this cache with \p other.
186  USD_API
187  void swap(UsdStageCache &other);
188 
189  /// Return a vector containing the stages present in this cache.
190  USD_API
191  std::vector<UsdStageRefPtr> GetAllStages() const;
192 
193  /// Return the number of stages present in this cache.
194  USD_API
195  size_t Size() const;
196 
197  /// Return true if this cache holds no stages, false otherwise.
198  bool IsEmpty() const { return Size() == 0; }
199 
200  /// Find an existing stage in the cache that satisfies \p request, or invoke
201  /// request.Manufacture() to create one and insert it into the cache.
202  /// Return the resulting stage and a bool indicating whether or not this
203  /// call manufactured the stage.
204  ///
205  /// This avoids race conditions in concurrent code that can occur using the
206  /// other public methods. Consider this racy example:
207  ///
208  /// \code
209  /// if (!cache.FindOneMatching(rootLayer)) {
210  /// auto stage = UsdStage::Open(rootLayer);
211  /// cache.Insert(stage);
212  /// }
213  /// \endcode
214  ///
215  /// This will race with another thread doing the same thing, resulting in
216  /// two stages with the same root layer inserted in the cache. This is
217  /// potentially rather inefficient since stage creation can be expensive,
218  /// depending on how many objects and how many prims & layers the stage
219  /// contains. RequestStage() avoids this by ensuring that there is no race
220  /// and the stage is created only once.
221  ///
222  /// Note that request should not be retained and must not be reused.
223  USD_API
224  std::pair<UsdStageRefPtr, bool>
226 
227  /// Find the stage in this cache corresponding to \p id in this cache. If
228  /// \p id is not valid (see Id::IsValid()) or if this cache does not have a
229  /// stage corresponding to \p id, return null.
230  USD_API
231  UsdStageRefPtr Find(Id id) const;
232 
233  /// Find a stage in this cache with \p rootLayer. If there is no matching
234  /// stage in this cache, return null. If there is more than one matching
235  /// stage in this cache, return an arbitrary matching one. See also
236  /// FindAllMatching().
237  USD_API
238  UsdStageRefPtr FindOneMatching(const SdfLayerHandle &rootLayer) const;
239 
240  /// Find a stage in this cache with \p rootLayer and \p sessionLayer. If
241  /// there is no matching stage in this cache, return null. If there is more
242  /// than one matching stage in this cache, return an arbitrary matching one.
243  /// See also FindAllMatching().
244  USD_API
245  UsdStageRefPtr FindOneMatching(const SdfLayerHandle &rootLayer,
246  const SdfLayerHandle &sessionLayer) const;
247 
248  /// Find a stage in this cache with \p rootLayer and \p pathResolverContext.
249  /// If there is no matching stage in this cache, return null. If there is
250  /// more than one matching stage in this cache, return an arbitrary matching
251  /// one.
252  /// \sa FindAllMatching()
253  USD_API
254  UsdStageRefPtr FindOneMatching(
255  const SdfLayerHandle &rootLayer,
256  const ArResolverContext &pathResolverContext) const;
257 
258  /// Find a stage in this cache with \p rootLayer, \p sessionLayer, and
259  /// \p pathResolverContext. If there is no matching stage in this cache,
260  /// return null. If there is more than one matching stage in this cache,
261  /// return an arbitrary matching one.
262  /// \sa FindAllMatching()
263  USD_API
264  UsdStageRefPtr FindOneMatching(
265  const SdfLayerHandle &rootLayer,
266  const SdfLayerHandle &sessionLayer,
267  const ArResolverContext &pathResolverContext) const;
268 
269  /// Find all stages in this cache with \p rootLayer. If there is no
270  /// matching stage in this cache, return an empty vector.
271  USD_API
272  std::vector<UsdStageRefPtr>
273  FindAllMatching(const SdfLayerHandle &rootLayer) const;
274 
275  /// Find all stages in this cache with \p rootLayer and \p sessionLayer.
276  /// If there is no matching stage in this cache, return an empty vector.
277  USD_API
278  std::vector<UsdStageRefPtr>
279  FindAllMatching(const SdfLayerHandle &rootLayer,
280  const SdfLayerHandle &sessionLayer) const;
281 
282  /// Find all stages in this cache with \p rootLayer and
283  /// \p pathResolverContext. If there is no matching stage in this cache,
284  /// return an empty vector.
285  USD_API
286  std::vector<UsdStageRefPtr>
287  FindAllMatching(const SdfLayerHandle &rootLayer,
288  const ArResolverContext &pathResolverContext) const;
289 
290  /// Find all stages in this cache with \p rootLayer, \p sessionLayer, and
291  /// \p pathResolverContext. If there is no matching stage in this cache,
292  /// return an empty vector. If there is more than one matching stage in
293  /// this cache, return an arbitrary matching one.
294  USD_API
295  std::vector<UsdStageRefPtr>
296  FindAllMatching(const SdfLayerHandle &rootLayer,
297  const SdfLayerHandle &sessionLayer,
298  const ArResolverContext &pathResolverContext) const;
299 
300  /// Return the Id associated with \p stage in this cache. If \p stage is
301  /// not present in this cache, return an invalid Id.
302  USD_API
303  Id GetId(const UsdStageRefPtr &stage) const;
304 
305  /// Return true if \p stage is present in this cache, false otherwise.
306  bool Contains(const UsdStageRefPtr &stage) const {
307  return static_cast<bool>(GetId(stage));
308  }
309 
310  /// Return true if \p id is present in this cache, false otherwise.
311  bool Contains(Id id) const { return Find(id); }
312 
313  /// Insert \p stage into this cache and return its associated Id. If the
314  /// given \p stage is already present in this cache, simply return its
315  /// associated Id.
316  USD_API
317  Id Insert(const UsdStageRefPtr &stage);
318 
319  /// Erase the stage identified by \p id from this cache and return true. If
320  /// \p id is invalid or there is no associated stage in this cache, do
321  /// nothing and return false. Since the cache contains UsdStageRefPtr,
322  /// erasing a stage from the cache will only destroy the stage if no other
323  /// UsdStageRefPtrs exist referring to it.
324  USD_API
325  bool Erase(Id id);
326 
327  /// Erase \p stage from this cache and return true. If \p stage is not
328  /// present in this cache, do nothing and return false. Since the cache
329  /// contains UsdStageRefPtr, erasing a stage from the cache will only
330  /// destroy the stage if no other UsdStageRefPtrs exist referring to it.
331  USD_API
332  bool Erase(const UsdStageRefPtr &stage);
333 
334  /// Erase all stages present in the cache with \p rootLayer and return the
335  /// number erased. Since the cache contains UsdStageRefPtr, erasing a stage
336  /// from the cache will only destroy the stage if no other UsdStageRefPtrs
337  /// exist referring to it.
338  USD_API
339  size_t EraseAll(const SdfLayerHandle &rootLayer);
340 
341  /// Erase all stages present in the cache with \p rootLayer and
342  /// \p sessionLayer and return the number erased. Since the cache contains
343  /// UsdStageRefPtr, erasing a stage from the cache will only destroy the
344  /// stage if no other UsdStageRefPtrs exist referring to it.
345  USD_API
346  size_t EraseAll(const SdfLayerHandle &rootLayer,
347  const SdfLayerHandle &sessionLayer);
348 
349  /// Erase all stages present in the cache with \p rootLayer,
350  /// \p sessionLayer, and \p pathResolverContext and return the number
351  /// erased. Since the cache contains UsdStageRefPtr, erasing a stage from
352  /// the cache will only destroy the stage if no other UsdStageRefPtrs
353  /// exist referring to it.
354  USD_API
355  size_t EraseAll(const SdfLayerHandle &rootLayer,
356  const SdfLayerHandle &sessionLayer,
357  const ArResolverContext &pathResolverContext);
358 
359  /// Remove all entries from this cache, leaving it empty and equivalent to a
360  /// default-constructed cache. Since the cache contains UsdStageRefPtr,
361  /// erasing a stage from the cache will only destroy the stage if no other
362  /// UsdStageRefPtrs exist referring to it.
363  USD_API
364  void Clear();
365 
366  /// Assign a debug name to this cache. This will be emitted in debug output
367  /// messages when the USD_STAGE_CACHES debug flag is enabled. If set to the
368  /// empty string, the cache's address will be used instead.
369  USD_API
370  void SetDebugName(const std::string &debugName);
371 
372  /// Retrieve this cache's debug name, set with SetDebugName(). If no debug
373  /// name has been assigned, return the empty string.
374  USD_API
375  std::string GetDebugName() const;
376 
377 private:
378  friend void swap(UsdStageCache &lhs, UsdStageCache &rhs) {
379  lhs.swap(rhs);
380  }
381 
382  typedef struct Usd_StageCacheImpl _Impl;
383  std::unique_ptr<_Impl> _impl;
384  mutable std::mutex _mutex;
385 };
386 
388 {
389 public:
390  USD_API
391  virtual ~UsdStageCacheRequest();
392 
393  // Return true if the stage satisfies this request.
394  virtual bool IsSatisfiedBy(UsdStageRefPtr const &stage) const = 0;
395 
396  // Return true if the pending request will satisfy this request, once
397  // complete.
398  virtual bool IsSatisfiedBy(UsdStageCacheRequest const &pending) const = 0;
399 
400  // Invoked to manufacture a stage to insert in the cache. Postcondition:
401  // IsSatisfiedBy() must return true for the resulting stage.
402  virtual UsdStageRefPtr Manufacture() = 0;
403 
404 private:
405  friend class UsdStageCache;
406 
407  struct _Mailbox;
408  void _Subscribe(_Mailbox *);
409 
410  struct _Data;
411  struct _DataDeleter { void operator()(_Data *); };
412  std::unique_ptr<_Data, _DataDeleter> _data;
413 };
414 
415 
417 
418 #endif // PXR_USD_USD_STAGE_CACHE_H
USD_API UsdStageCache()
Default construct an empty cache.
Definition: layer.h:97
virtual USD_API ~UsdStageCacheRequest()
#define USD_API
Definition: api.h:40
TF_API long TfStringToLong(const std::string &txt, bool *outOfRange=NULL)
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
#define TF_CODING_ERROR
GLdouble s
Definition: glad.h:3009
friend size_t hash_value(Id id)
Hash.
Definition: stageCache.h:160
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)
**But if you need a result
Definition: thread.h:613
static Id FromString(const std::string &s)
Definition: stageCache.h:108
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:311
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:378
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:198
friend bool operator==(const Id &lhs, const Id &rhs)
Equality comparison.
Definition: stageCache.h:136
std::string ToString() const
Convert this Id to a string representation.
Definition: stageCache.h:124
USD_API Id GetId(const UsdStageRefPtr &stage) const
std::string TfStringify(const T &v)
Definition: stringUtils.h:572
bool Contains(const UsdStageRefPtr &stage) const
Return true if stage is present in this cache, false otherwise.
Definition: stageCache.h:306
Id()
Default construct an invalid id.
Definition: stageCache.h:100
USD_API UsdStageCache & operator=(const UsdStageCache &other)
Replace the contents of this cache with a copy of other.
friend bool operator>(const Id &lhs, const Id &rhs)
Greater-than comparison.
Definition: stageCache.h:152
USD_API Id Insert(const UsdStageRefPtr &stage)
USD_API ~UsdStageCache()
Destructor.
static Id FromLongInt(long int val)
Definition: stageCache.h:104
friend bool operator>=(const Id &lhs, const Id &rhs)
Greater-than or equal comparison.
Definition: stageCache.h:156
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
friend bool operator<(const Id &lhs, const Id &rhs)
Less-than comparison.
Definition: stageCache.h:144
USD_API std::vector< UsdStageRefPtr > FindAllMatching(const SdfLayerHandle &rootLayer) const
GLuint GLfloat * val
Definition: glcorearb.h:1608
#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:129
friend bool operator!=(const Id &lhs, const Id &rhs)
Inequality comparison.
Definition: stageCache.h:140
virtual UsdStageRefPtr Manufacture()=0
long int ToLongInt() const
Convert this Id to an integral representation.
Definition: stageCache.h:121
TF_DECLARE_REF_PTRS(UsdStage)
friend bool operator<=(const Id &lhs, const Id &rhs)
Less-than or equal comparison.
Definition: stageCache.h:148
USD_API size_t EraseAll(const SdfLayerHandle &rootLayer)
USD_API std::string GetDebugName() const