Provide an InsertStage method on the stage cache object to allow the

explicit insertion of stages into the cache. This could be used for
stages loaded from files on disk, but is primarily intended for adding
in-memory stages to the cache.

third_party/houdini/lib/gusd/stageCache.cpp

@@ -411,6 +411,11 @@ class GusdStageCache::_Impl
     void            FindStages(const UT_StringSet& paths,
                                UT_Set<UsdStageRefPtr>& stages) const;
 
+    void	    InsertStage(UsdStageRefPtr &stage,
+                                const UT_StringRef& path,
+                                const GusdStageOpts& opts,
+                                const GusdStageEditPtr& edit);
+
     /// Load a range of [start,end) prims from the cache. The range corresponds
     /// to a *subset* of the prims in \p primPaths.
     /// The \p rangeFn functor must implement `operator()(exint)` which, given
@@ -1324,6 +1329,23 @@ GusdStageCache::_Impl::FindStages(const UT_StringSet& paths,
 }
 
 
+void
+GusdStageCache::_Impl::InsertStage(UsdStageRefPtr &stage,
+                                   const UT_StringRef& path,
+                                   const GusdStageOpts& opts,
+                                   const GusdStageEditPtr& edit)
+{
+    TF_DEBUG(GUSD_STAGECACHE).Msg(
+        "[GusdStageCache::InsertStage] Inserting stage @%s@\n",
+        path.c_str());
+
+    _StageMap::accessor a;
+    if(stage && _stageMap.insert(a, _StageKey(path, opts, edit))) {
+        a->second = stage;
+    }
+}
+
+
 UsdStageRefPtr
 GusdStageCache::_MaskedStageCache::FindStage(const SdfPath& primPath)
 {
@@ -1743,6 +1765,15 @@ GusdStageCacheWriter::FindStages(const UT_StringSet& paths,
 }
 
 
+void
+GusdStageCacheWriter::InsertStage(UsdStageRefPtr &stage,
+                                  const UT_StringRef& path,
+                                  const GusdStageOpts& opts,
+                                  const GusdStageEditPtr& edit)
+{
+    _cache._impl->InsertStage(stage, path, opts, edit);
+}
+
 void
 GusdStageCacheWriter::ReloadStages(const UT_StringSet& paths)
 {

third_party/houdini/lib/gusd/stageCache.h

@@ -297,6 +297,16 @@ class GUSD_API GusdStageCacheWriter : public GusdStageCacheReader
     void    FindStages(const UT_StringSet& paths,
                        UT_Set<UsdStageRefPtr>& stages);
 
+    /// Insert a stage into our cache. The lifetime of this stage is not
+    /// fully controlled by this cache. The cache is just a holder for the
+    /// stage for as long as the gusd library is allowed access to it (until
+    /// it is destroyed by the external owner, which must then call Clear
+    /// with the same path.
+    void    InsertStage(UsdStageRefPtr &stage,
+                        const UT_StringRef& path,
+                        const GusdStageOpts& opts,
+                        const GusdStageEditPtr& edit);
+
     /// \section GusdStageCacheWriter_ReloadAndClear Reloading And Clearing
     ///
     /// During active sessions, the contents of a cache may be refreshed