OCCT

// Copyright (c) 2026 OPEN CASCADE SAS
//
// This file is part of Open CASCADE Technology software library.
//
// This library is free software; you can redistribute it and/or modify it under
// the terms of the GNU Lesser General Public License version 2.1 as published
// by the Free Software Foundation, with special exception defined in the file
// OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
// distribution for complete text of the license and disclaimer of any warranty.
//
// Alternatively, this file may be used under the terms of Open CASCADE
// commercial license or contractual agreement.

#ifndef _BRepGraph_CacheRegistry_HeaderFile
#define _BRepGraph_CacheRegistry_HeaderFile

#include <BRepGraph_Cache.hxx>
#include <BRepGraph_CopyRemap.hxx>
#include <NCollection_FlatDataMap.hxx>
#include <NCollection_LinearVector.hxx>
#include <Standard_DefineAlloc.hxx>
#include <Standard_GUID.hxx>

#include <atomic>
#include <functional>
#include <limits>
#include <mutex>
#include <shared_mutex>

class BRepGraph;
struct BRepGraph_Data;
class BRepGraph_CacheIterator;

//! @brief GUID-keyed runtime registry of graph cache services.
//!
//! Stores registered cache services in a stable slot array for O(1) slot access
//! and a GUID-to-slot map for lookup by stable public identity. Cache services
//! own their typed transient data; this registry only manages identity and
//! owner binding.
class BRepGraph_CacheRegistry
{
public:
  DEFINE_STANDARD_ALLOC

  Standard_EXPORT BRepGraph_CacheRegistry();
  Standard_EXPORT explicit BRepGraph_CacheRegistry(BRepGraph& theGraph);
  Standard_EXPORT ~BRepGraph_CacheRegistry();

  BRepGraph_CacheRegistry(const BRepGraph_CacheRegistry&)            = delete;
  BRepGraph_CacheRegistry& operator=(const BRepGraph_CacheRegistry&) = delete;

  Standard_EXPORT BRepGraph_CacheRegistry(BRepGraph_CacheRegistry&& theOther) noexcept;
  Standard_EXPORT BRepGraph_CacheRegistry& operator=(BRepGraph_CacheRegistry&& theOther) noexcept;

  //! Attach an external registry to a graph.
  Standard_EXPORT void Attach(BRepGraph& theGraph);

  //! Detach this registry and all registered caches from its graph.
  Standard_EXPORT void Detach() noexcept;

  //! Return true when this registry is attached to a graph.
  [[nodiscard]] Standard_EXPORT bool IsAttached() const noexcept;

  //! Return true when this registry is attached to the supplied graph.
  [[nodiscard]] Standard_EXPORT bool IsFor(const BRepGraph& theGraph) const noexcept;

  //! Return the attached graph, or null for a detached registry.
  [[nodiscard]] Standard_EXPORT BRepGraph* AttachedGraph() const noexcept;

  //! Register a cache service. Replaces an existing cache with the same GUID.
  //! @param[in] theCache cache service
  //! @return graph-local slot index
  Standard_EXPORT uint32_t RegisterCache(const occ::handle<BRepGraph_Cache>& theCache);

  //! Register a cache service. Short form used by graph-local cache operations.
  //! @param[in] theCache cache service
  //! @return graph-local slot index
  Standard_EXPORT uint32_t Register(const occ::handle<BRepGraph_Cache>& theCache);

  //! Remove a cache service by GUID.
  //! @param[in] theGUID cache identity
  Standard_EXPORT void UnregisterCache(const Standard_GUID& theGUID);

  //! Find a cache service by GUID.
  //! @param[in] theGUID cache identity
  //! @return cache service, or null handle if not found
  [[nodiscard]] Standard_EXPORT occ::handle<BRepGraph_Cache> FindCache(
    const Standard_GUID& theGUID) const;

  //! Typed convenience lookup by cache GUID.
  template <typename T>
  [[nodiscard]] occ::handle<T> FindCache() const
  {
    return Find<T>();
  }

  //! Typed lookup by cache GUID.
  template <typename T>
  [[nodiscard]] occ::handle<T> Find() const
  {
    return occ::down_cast<T>(findCache(T::GetID()));
  }

  //! Return an existing cache service or create and register a default one.
  //! Template convenience wrapper: extracts GUID and calls ensureCache.
  template <typename T>
  [[nodiscard]] occ::handle<T> Ensure()
  {
    return occ::down_cast<T>(
      ensureCache(T::GetID(), []() -> occ::handle<BRepGraph_Cache> { return new T(); }));
  }

  //! Return current graph-local slot for a GUID.
  //! @param[in] theGUID cache type identity
  //! @param[out] theSlot graph-local slot index
  //! @return true if the cache service is registered
  [[nodiscard]] Standard_EXPORT bool FindSlot(const Standard_GUID& theGUID,
                                              uint32_t&            theSlot) const;

  //! Return current graph-local slot for a cache service.
  //! @param[in] theCache cache service
  //! @param[out] theSlot graph-local slot index
  //! @return true if the cache service is registered
  [[nodiscard]] Standard_EXPORT bool FindSlot(const occ::handle<BRepGraph_Cache>& theCache,
                                              uint32_t&                           theSlot) const;

  //! Return cache service by graph-local slot, or null handle if the slot is out of range.
  //! @param[in] theSlot graph-local cache slot
  [[nodiscard]] Standard_EXPORT occ::handle<BRepGraph_Cache> Cache(const uint32_t theSlot) const;

  //! Number of registered cache services.
  [[nodiscard]] uint32_t NbCaches() const
  {
    std::shared_lock<std::shared_mutex> aLock(myMutex);
    return static_cast<uint32_t>(myCaches.Size());
  }

  //! Iterate registered cache services.
  [[nodiscard]] Standard_EXPORT BRepGraph_CacheIterator CacheIter() const;

  //! Clear data in all registered cache services.
  Standard_EXPORT void ClearAll() noexcept;

  //! Ask registered cache services to copy fresh, remappable data into the target graph.
  Standard_EXPORT void CopyFreshCachesTo(
    BRepGraph&                                                         theTargetGraph,
    const NCollection_FlatDataMap<BRepGraph_ItemId, BRepGraph_ItemId>& theItemRemap,
    const BRepGraph_CopyRemap::Mode                                    theMode,
    const BRepGraph_CopyRemap::FreshnessPolicy                         theFreshnessPolicy =
      BRepGraph_CopyRemap::FreshnessPolicy::SourceOnly) const;

  //! Ask registered cache services to copy fresh data using identity mapping.
  Standard_EXPORT void CopyFreshCachesTo(
    BRepGraph&                                 theTargetGraph,
    const BRepGraph_CopyRemap::MappingKind     theMappingKind,
    const BRepGraph_CopyRemap::Mode            theMode,
    const BRepGraph_CopyRemap::FreshnessPolicy theFreshnessPolicy =
      BRepGraph_CopyRemap::FreshnessPolicy::SourceOnly) const;

  //! Unregister all cache services.
  Standard_EXPORT void Clear() noexcept;

private:
  friend class ::BRepGraph;
  friend struct ::BRepGraph_Data;

  static constexpr uint32_t THE_INVALID_SLOT = std::numeric_limits<uint32_t>::max();

  //! Attach this registry to graph owner. Propagates context to registered caches.
  Standard_EXPORT void attachGraph(BRepGraph* theGraph) noexcept;

  //! Rebind an external registry after its graph owner has moved.
  Standard_EXPORT void rebindGraph(BRepGraph* theGraph) noexcept;

  //! Detach an external registry from a graph that is being destroyed.
  Standard_EXPORT void detachGraphFromOwner(BRepGraph* theGraph) noexcept;

  [[nodiscard]] Standard_EXPORT occ::handle<BRepGraph_Cache> findCacheLocked(
    const Standard_GUID& theGUID) const;

  [[nodiscard]] Standard_EXPORT occ::handle<BRepGraph_Cache> findCache(
    const Standard_GUID& theGUID) const;

  //! Return an existing cache service or create and register a default one.
  //! Uses double-checked locking: shared lock for fast path (cache exists),
  //! exclusive lock only for creation (rare, first-call only).
  [[nodiscard]] Standard_EXPORT occ::handle<BRepGraph_Cache> ensureCache(
    const Standard_GUID&                                 theGUID,
    const std::function<occ::handle<BRepGraph_Cache>()>& theFactory);

  [[nodiscard]] Standard_EXPORT occ::handle<BRepGraph_Cache> cacheAt(const uint32_t theSlot) const;

  Standard_EXPORT uint32_t registerCacheLocked(const occ::handle<BRepGraph_Cache>& theCache,
                                               occ::handle<BRepGraph_Cache>&       theRemoved,
                                               bool&                               theToAttach);

  Standard_EXPORT void releaseCaches(const bool theToClearDetached) noexcept;

  Standard_EXPORT void releaseIfUnregistered(const occ::handle<BRepGraph_Cache>& theCache) noexcept;

  NCollection_LinearVector<occ::handle<BRepGraph_Cache>> myCaches;
  NCollection_FlatDataMap<Standard_GUID, uint32_t>       myGuidToSlot;
  std::atomic<BRepGraph*>                                myGraph{nullptr};
  bool                                                   myIsExternal  = false;
  bool                                                   myIsDetaching = false;
  mutable std::shared_mutex                              myMutex;
};

#include <BRepGraph_CacheIterator.hxx>

#endif // _BRepGraph_CacheRegistry_HeaderFile