include/opencascade/BRepGraph_CacheRegistry.hxx

0001 // Copyright (c) 2026 OPEN CASCADE SAS
0002 //
0003 // This file is part of Open CASCADE Technology software library.
0004 //
0005 // This library is free software; you can redistribute it and/or modify it under
0006 // the terms of the GNU Lesser General Public License version 2.1 as published
0007 // by the Free Software Foundation, with special exception defined in the file
0008 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
0009 // distribution for complete text of the license and disclaimer of any warranty.
0010 //
0011 // Alternatively, this file may be used under the terms of Open CASCADE
0012 // commercial license or contractual agreement.
0013
0014 #ifndef _BRepGraph_CacheRegistry_HeaderFile
0015 #define _BRepGraph_CacheRegistry_HeaderFile
0016
0017 #include <BRepGraph_Cache.hxx>
0018 #include <BRepGraph_CopyRemap.hxx>
0019 #include <NCollection_DataMap.hxx>
0020 #include <NCollection_FlatDataMap.hxx>
0021 #include <NCollection_LinearVector.hxx>
0022 #include <Standard_DefineAlloc.hxx>
0023 #include <Standard_GUID.hxx>
0024
0025 #include <functional>
0026 #include <mutex>
0027 #include <shared_mutex>
0028
0029 class BRepGraph;
0030 struct BRepGraph_Data;
0031 class BRepGraph_CacheIterator;
0032
0033 //! @brief GUID-keyed runtime registry of graph cache services.
0034 //!
0035 //! Stores registered cache services in a stable slot array for O(1) slot access
0036 //! and a GUID-to-slot map for lookup by stable public identity. Cache services
0037 //! own their typed transient data; this registry only manages identity and
0038 //! owner binding.
0039 class BRepGraph_CacheRegistry
0040 {
0041 public:
0042   DEFINE_STANDARD_ALLOC
0043
0044   Standard_EXPORT BRepGraph_CacheRegistry();
0045
0046   BRepGraph_CacheRegistry(const BRepGraph_CacheRegistry&)            = delete;
0047   BRepGraph_CacheRegistry& operator=(const BRepGraph_CacheRegistry&) = delete;
0048
0049   Standard_EXPORT BRepGraph_CacheRegistry(BRepGraph_CacheRegistry&& theOther) noexcept;
0050   Standard_EXPORT BRepGraph_CacheRegistry& operator=(BRepGraph_CacheRegistry&& theOther) noexcept;
0051
0052   //! Register a cache service. Replaces an existing cache with the same GUID.
0053   //! @param[in] theCache cache service
0054   //! @return graph-local slot index
0055   Standard_EXPORT uint32_t RegisterCache(const occ::handle<BRepGraph_Cache>& theCache);
0056
0057   //! Register a cache service. Short form used by graph-local cache operations.
0058   //! @param[in] theCache cache service
0059   //! @return graph-local slot index
0060   Standard_EXPORT uint32_t Register(const occ::handle<BRepGraph_Cache>& theCache);
0061
0062   //! Remove a cache service by GUID.
0063   //! @param[in] theGUID cache identity
0064   Standard_EXPORT void UnregisterCache(const Standard_GUID& theGUID);
0065
0066   //! Find a cache service by GUID.
0067   //! @param[in] theGUID cache identity
0068   //! @return cache service, or null handle if not found
0069   [[nodiscard]] Standard_EXPORT occ::handle<BRepGraph_Cache> FindCache(
0070     const Standard_GUID& theGUID) const;
0071
0072   //! Typed convenience lookup by cache GUID.
0073   template <typename T>
0074   [[nodiscard]] occ::handle<T> FindCache() const
0075   {
0076     return Find<T>();
0077   }
0078
0079   //! Typed lookup by cache GUID.
0080   template <typename T>
0081   [[nodiscard]] occ::handle<T> Find() const
0082   {
0083     return occ::down_cast<T>(FindCache(T::GetID()));
0084   }
0085
0086   //! Return an existing cache service or create and register a default one.
0087   //! Template convenience wrapper: extracts GUID and calls ensureCache.
0088   template <typename T>
0089   [[nodiscard]] occ::handle<T> Ensure()
0090   {
0091     return occ::down_cast<T>(
0092       ensureCache(T::GetID(), []() -> occ::handle<BRepGraph_Cache> { return new T(); }));
0093   }
0094
0095   //! Return current graph-local slot for a GUID.
0096   //! @param[in] theGUID cache family identity
0097   //! @param[out] theSlot graph-local slot index
0098   //! @return true if the cache service is registered
0099   [[nodiscard]] Standard_EXPORT bool FindSlot(const Standard_GUID& theGUID,
0100                                               uint32_t&            theSlot) const;
0101
0102   //! Return current graph-local slot for a cache service.
0103   //! @param[in] theCache cache service
0104   //! @param[out] theSlot graph-local slot index
0105   //! @return true if the cache service is registered
0106   [[nodiscard]] Standard_EXPORT bool FindSlot(const occ::handle<BRepGraph_Cache>& theCache,
0107                                               uint32_t&                           theSlot) const;
0108
0109   //! Return cache service by graph-local slot, or null handle if the slot is out of range.
0110   //! @param[in] theSlot graph-local cache slot
0111   [[nodiscard]] Standard_EXPORT occ::handle<BRepGraph_Cache> Cache(uint32_t theSlot) const;
0112
0113   //! Number of registered cache services.
0114   [[nodiscard]] uint32_t NbCaches() const
0115   {
0116     std::shared_lock<std::shared_mutex> aLock(myMutex);
0117     return static_cast<uint32_t>(myCaches.Size());
0118   }
0119
0120   //! Iterate registered cache services.
0121   [[nodiscard]] Standard_EXPORT BRepGraph_CacheIterator CacheIter() const;
0122
0123   //! Clear data in all registered cache services.
0124   Standard_EXPORT void ClearAll() noexcept;
0125
0126   //! Ask registered cache services to copy fresh, remappable data into the target graph.
0127   Standard_EXPORT void CopyFreshCachesTo(
0128     BRepGraph&                                                         theTargetGraph,
0129     const NCollection_FlatDataMap<BRepGraph_ItemId, BRepGraph_ItemId>& theItemRemap,
0130     const BRepGraph_CopyRemap::Mode                                    theMode) const;
0131
0132   //! Ask registered cache services to copy fresh data using identity mapping.
0133   Standard_EXPORT void CopyFreshCachesTo(BRepGraph&                       theTargetGraph,
0134                                          BRepGraph_CopyRemap::MappingKind theMappingKind,
0135                                          BRepGraph_CopyRemap::Mode        theMode) const;
0136
0137   //! Unregister all cache services.
0138   Standard_EXPORT void Clear() noexcept;
0139
0140 private:
0141   friend class ::BRepGraph;
0142   friend struct ::BRepGraph_Data;
0143
0144   //! Attach this registry to graph owner. Propagates context to registered caches.
0145   Standard_EXPORT void Attach(BRepGraph* theGraph) noexcept;
0146
0147   //! Clear the graph data binding.
0148   Standard_EXPORT void Detach() noexcept;
0149
0150   [[nodiscard]] Standard_EXPORT occ::handle<BRepGraph_Cache> findCacheLocked(
0151     const Standard_GUID& theGUID) const;
0152
0153   //! Return an existing cache service or create and register a default one.
0154   //! Uses double-checked locking: shared lock for fast path (cache exists),
0155   //! exclusive lock only for creation (rare, first-call only).
0156   [[nodiscard]] Standard_EXPORT occ::handle<BRepGraph_Cache> ensureCache(
0157     const Standard_GUID&                                 theGUID,
0158     const std::function<occ::handle<BRepGraph_Cache>()>& theFactory);
0159
0160   [[nodiscard]] Standard_EXPORT occ::handle<BRepGraph_Cache> cacheAt(uint32_t theSlot) const;
0161
0162   Standard_EXPORT uint32_t registerCacheLocked(const occ::handle<BRepGraph_Cache>& theCache);
0163
0164   Standard_EXPORT void detachAllLocked() noexcept;
0165
0166   NCollection_LinearVector<occ::handle<BRepGraph_Cache>> myCaches;
0167   NCollection_DataMap<Standard_GUID, uint32_t>           myGuidToSlot;
0168   BRepGraph*                                             myGraph = nullptr;
0169   mutable std::shared_mutex                              myMutex;
0170 };
0171
0172 #include <BRepGraph_CacheIterator.hxx>
0173
0174 #endif // _BRepGraph_CacheRegistry_HeaderFile