HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
stageCacheContext.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_CONTEXT_H
25 #define PXR_USD_USD_STAGE_CACHE_CONTEXT_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/usd/usd/api.h"
29 #include "pxr/base/tf/stacked.h"
30 
31 #include <vector>
32 
34 
35 
36 class UsdStageCache;
37 
38 // Private helper wrapper class, holds a const reference to a stage cache.
41  : cache(cache) {}
43 };
44 
45 // Using a template arg for 'cache' in UsdUseButDoNotPopulateCache enforces
46 // lvalue requirement: rvalues will not bind to function template non-const
47 // reference parameters.
48 
49 /// Indicate that a UsdStageCacheContext should be bound in a read-only fashion.
50 /// Calls to UsdStage::Open() will attempt to find stages in \p cache when a
51 /// UsdStageCacheContext is present on the stack. See UsdStageCacheContext for
52 /// more details and example use.
53 template <class StageCache>
55 UsdUseButDoNotPopulateCache(StageCache &cache) {
57 }
58 
60 {
61  /// Indicate that a UsdStageCacheContext should ignore all currently bound
62  /// UsdStageCacheContexts, preventing reading from or writing to their
63  /// UsdStageCaches. See UsdStageCache for more details and example use.
65  /// Indicate that a UsdStageCacheContext should ignore all currently bound
66  /// writable UsdStageCacheContexts, writing to their UsdStageCaches. See
67  /// UsdStageCache for more details and example use.
69 
71 };
72 
73 /// \class UsdStageCacheContext
74 ///
75 /// A context object that lets the UsdStage::Open() API read from or read
76 /// from and write to a UsdStageCache instance during a scope of execution.
77 ///
78 /// Code examples illustrate typical use:
79 /// \code
80 /// {
81 /// // A stage cache to work with.
82 /// UsdStageCache stageCache;
83 ///
84 /// // Bind this cache. UsdStage::Open() will attempt to find a matching
85 /// // stage in the cache. If none is found, it will open a new stage and
86 /// // insert it into the cache.
87 /// UsdStageCacheContext context(stageCache);
88 ///
89 /// // Since the cache is currently empty, this Open call will not find an
90 /// // existing stage in the cache, but will insert the newly opened stage
91 /// // in it.
92 /// auto stage = UsdStage::Open(<args>);
93 ///
94 /// assert(stageCache.Contains(stage));
95 ///
96 /// // A subsequent Open() call with the same arguments will retrieve the
97 /// // stage from cache.
98 /// auto stage2 = UsdStage::Open(<args>);
99 /// assert(stage2 == stage);
100 /// }
101 /// \endcode
102 ///
103 /// The UsdStage::Open() API examines caches in UsdStageCacheContexts that exist
104 /// on the stack in the current thread in order starting with the most recently
105 /// created (deepest in the stack) to the least recently created.
106 ///
107 /// The UsdUseButDoNotPopulateCache() function makes a cache available for
108 /// UsdStage::Open() to find stages in, but newly opened stages will not be
109 /// published to it. This can be useful if you want to make use of a cache but
110 /// cannot or do not wish to mutate that cache.
111 ///
112 /// Passing UsdBlockStageCaches disables cache use entirely (as if no
113 /// UsdStageCacheContexts exist on the stack), while
114 /// UsdBlockStageCachePopulation disables writing to all bound caches (as if
115 /// they were all established with UsdUseButDoNotPopulateCache()).
116 ///
117 /// Threading note: Different threads have different call stacks, so
118 /// UsdStageCacheContext objects that exist in one thread's stack do not
119 /// influence calls to UsdStage::Open() from a different thread.
120 ///
122 {
123 public:
124  /// Bind a cache for calls to UsdStage::Open() to read from and write to.
125  explicit UsdStageCacheContext(UsdStageCache &cache)
126  : _rwCache(&cache)
127  , _isReadOnlyCache(false)
128  , _blockType(Usd_NoBlock) {}
129 
130  /// Bind a cache for calls to UsdStage::Open() to read from.
131  /// \see UsdUseButDoNotPopulateCache()
133  : _roCache(&holder.cache)
134  , _isReadOnlyCache(true)
135  , _blockType(Usd_NoBlock) {}
136 
137  /// Disable cache use completely (with UsdBlockStageCaches) or only
138  /// for writing (with UsdBlockStageCacheWrites).
140  : _blockType(blockType) {}
141 
142 private:
143  friend class UsdStage;
144 
145  static std::vector<const UsdStageCache *> _GetReadOnlyCaches();
146  static std::vector<const UsdStageCache *> _GetReadableCaches();
147  static std::vector<UsdStageCache *> _GetWritableCaches();
148 
149  // A blocking context is encoded with both members variables null.
150  union {
151  UsdStageCache *_rwCache;
152  const UsdStageCache *_roCache;
153  };
154  bool _isReadOnlyCache;
156 };
157 
158 
160 
161 #endif // PXR_USD_USD_STAGE_CACHE_CONTEXT_H
#define USD_API
Definition: api.h:40
TF_DEFINE_STACKED(UsdStageCacheContext, true, USD_API)
Usd_NonPopulatingStageCacheWrapper UsdUseButDoNotPopulateCache(StageCache &cache)
Usd_NonPopulatingStageCacheWrapper(const UsdStageCache &cache)
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1394
UsdStageCacheContextBlockType
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91