LCOV - code coverage report
Current view: top level - OdbDesignLib/App - DesignCache.h (source / functions) Coverage Total Hit
Test: OdbDesign Test Coverage Lines: 91.5 % 106 97
Test Date: 2026-11-21 03:51:50 Functions: 100.0 % 12 12
Legend: Lines: hit not hit

            Line data    Source code
       1              : #pragma once
       2              : 
       3              : #include "../FileModel/Design/FileArchive.h"
       4              : #include "../ProductModel/Design.h"
       5              : #include "../odbdesign_export.h"
       6              : #include "StringVector.h"
       7              : #include <chrono>
       8              : #include <condition_variable>
       9              : #include <cstddef>
      10              : #include <cstdint>
      11              : #include <filesystem>
      12              : #include <functional>
      13              : #include <future>
      14              : #include <memory>
      15              : #include <mutex>
      16              : #include <shared_mutex>
      17              : #include <stdexcept>
      18              : #include <string>
      19              : #include <type_traits>
      20              : #include <unordered_map>
      21              : #include <unordered_set>
      22              : #include <vector>
      23              : 
      24              : 
      25              : namespace Odb::Lib::App
      26              : {
      27              :         class ODBDESIGN_EXPORT DesignCache
      28              :         {
      29              :         public:
      30              :                 // Lifecycle of a single design's load. Failed covers parse failure only
      31              :                 // (a corrupt/unparseable archive); a design that is simply not found is a
      32              :                 // miss, not a failure, and records no state entry (its name stays
      33              :                 // Unloaded) so the state map cannot grow without bound on untrusted
      34              :                 // names. Neither poisons the cache — the in-flight entry is erased so a
      35              :                 // later request starts a fresh load.
      36              :                 enum class LoadState
      37              :                 {
      38              :                         Unloaded,
      39              :                         Loading,
      40              :                         Loaded,
      41              :                         Failed
      42              :                 };
      43              : 
      44              :                 // Observer for load-state transitions. Invoked on the thread that performs the
      45              :                 // transition (loader or evictor) with no cache locks held; observers MUST be
      46              :                 // cheap and non-blocking.
      47              :                 using LoadEventCallback = std::function<void(const std::string& designName, LoadState from, LoadState to)>;
      48              : 
      49              :                 DesignCache(std::string directory);
      50              :                 ~DesignCache();
      51              : 
      52              :                 std::shared_ptr<ProductModel::Design> GetDesign(const std::string& designName);
      53              :                 std::shared_ptr<FileModel::Design::FileArchive> GetFileArchive(const std::string& designName);
      54              : 
      55              :                 // Injects an externally-built archive into the cache (POST /filemodels).
      56              :                 // injectedBytes: a byte estimate for the in-memory archive (e.g. the request
      57              :                 // body size) charged to the LRU budget when no on-disk file backs the name —
      58              :                 // without it a save=false injection is charged only DESIGN_BYTES_OVERHEAD.
      59              :                 void AddFileArchive(const std::string& designName, std::shared_ptr<FileModel::Design::FileArchive> fileArchive, bool save, std::uint64_t injectedBytes = 0);
      60              : 
      61              :                 // Drops a design's cached FileArchive, Design, and serialized response
      62              :                 // payloads (invalidation generation bump), and reverts its load state to
      63              :                 // Unloaded. Idempotent for names that are not cached. Used when the on-disk
      64              :                 // archive is replaced out from under a warm cache (upload overwrite) so the
      65              :                 // next load re-parses the new file instead of returning the stale object.
      66              :                 void InvalidateDesign(const std::string& designName);
      67              : 
      68              :                 bool SaveFileArchive(const std::string& designName);
      69              : 
      70              :                 std::vector<std::string> getLoadedDesignNames(const std::string& filter = "") const;
      71              :                 std::vector<std::string> getLoadedFileArchiveNames(const std::string& filter = "") const;
      72              :                 std::vector<std::string> getUnloadedDesignNames(const std::string& filter = "") const;
      73              : 
      74              :                 int loadAllFileArchives(bool stopOnError);
      75              :                 int loadAllDesigns(bool stopOnError);
      76              :                 int loadFileArchives(const Utils::StringVector& names);
      77              :                 int loadDesigns(const Utils::StringVector& names);
      78              : 
      79              :                 void setDirectory(const std::string& directory);
      80              :                 std::string getDirectory() const;
      81              : 
      82              :                 void Clear();
      83              : 
      84              :                 void ensureDirectoryExists() const;
      85              : 
      86              :                 // ---- load state machine + observers (consumed by M1.2 RequestLoadDesign, M3.2 events) ----
      87              : 
      88              :                 LoadState GetLoadState(const std::string& designName) const;
      89              : 
      90              :                 // Register a load-state observer. Observers are invoked synchronously on
      91              :                 // the thread performing the transition (loader or evictor) with no cache
      92              :                 // locks held; observers MUST be cheap and non-blocking.
      93              :                 //
      94              :                 // Re-entrancy contract: an observer MUST NOT request the design currently
      95              :                 // being loaded on its own thread (GetDesign / GetFileArchive / anything
      96              :                 // that reaches GetOrLoadSingleFlight for that name). The re-entrant call
      97              :                 // would join the loader's own pending in-flight future and deadlock; such
      98              :                 // re-entry is detected and rejected with std::runtime_error instead of
      99              :                 // waiting. Requesting other designs is safe.
     100              :                 void AddLoadObserver(LoadEventCallback callback);
     101              : 
     102              :                 // ---- background loads (consumed by M1.2 RequestLoadDesign + upload auto-warm) ----
     103              : 
     104              :                 // Kicks a background load of the named design and returns immediately:
     105              :                 // the parse runs on a detached thread through the same single-flight
     106              :                 // path as a synchronous GetDesign, so state/observer transitions,
     107              :                 // caching, and failure semantics (Failed is retryable) are identical.
     108              :                 // Returns true when a fresh background load was started; false when one
     109              :                 // is already pending or in flight for the name (the caller surfaces
     110              :                 // that as "already loading"). Throws only if the load thread itself
     111              :                 // could not be spawned; load failures are logged, never thrown here.
     112              :                 bool LoadDesignAsync(const std::string& designName);
     113              : 
     114              :                 // True when an archive file for the design name exists in the designs
     115              :                 // directory (first regular file whose stem matches), without
     116              :                 // triggering a load. Lets callers distinguish "no such archive"
     117              :                 // (NOT_FOUND) from a parse failure (Failed load state).
     118              :                 bool ContainsDesign(const std::string& designName) const;
     119              : 
     120              :                 // Byte budget for LRU eviction; 0 disables eviction.
     121              :                 void setCacheMaxBytes(std::uint64_t maxBytes);
     122              :                 std::uint64_t getCacheMaxBytes() const;
     123              : 
     124              :                 // Cap on concurrently parsing background loads; further loads queue on
     125              :                 // the semaphore inside their background thread (LoadDesignAsync itself
     126              :                 // never blocks). 0 = unbounded.
     127              :                 void setMaxBackgroundLoads(std::size_t maxLoads);
     128              :                 std::size_t getMaxBackgroundLoads() const;
     129              : 
     130              :                 // ---- serialized-response cache (M1.4) ----
     131              :                 //
     132              :                 // Per-design pre-serialized response payloads, counted against the SAME
     133              :                 // byte budget as the archive/Design entries (see LruEntry::serializedBytes).
     134              :                 // Population: a background pre-serialization is scheduled when a design
     135              :                 // load completes (synchronous and LoadDesignAsync/M1.2 background loads
     136              :                 // alike); the first GetDesign RPC that misses also serializes lazily, so
     137              :                 // behavior is correct even when the background pass lost a race or never
     138              :                 // ran. At most one serialization is counted per design per invalidation
     139              :                 // generation.
     140              :                 //
     141              :                 // Invalidation (drops the payload entries; next request re-populates):
     142              :                 // AddFileArchive (re-upload/POST /filemodels — also drops the cached
     143              :                 // Design, which was built from the old archive), LRU eviction, Clear().
     144              :                 // A commit racing any of these is discarded (generation + design-identity
     145              :                 // + epoch checks), so stale bytes can never be published.
     146              : 
     147              :                 // REST JSON payload variants exposed to the controllers:
     148              :                 // Design    -> ProductModel::Design::to_json()   (/designs/<name>)
     149              :                 // FileModel -> FileArchive::to_json()            (/filemodels/<name>)
     150              :                 // Note: the cached Design JSON is the un-clipped payload (the shared
     151              :                 // cached Design must keep its file model for the gRPC GetDesign path);
     152              :                 // the controller wiring decides how/whether to serve it for the default
     153              :                 // (file-model-clipped) route.
     154              :                 enum class JsonPayloadKind
     155              :                 {
     156              :                         Design,
     157              :                         FileModel
     158              :                 };
     159              : 
     160              :                 // Cached serialized ProductModel::Design bytes (the gRPC GetDesign
     161              :                 // response payload). True and filled when warm.
     162              :                 bool TryGetDesignBytes(const std::string& designName, std::string& outBytes) const;
     163              : 
     164              :                 // Cached REST JSON payload for the design. True and filled when warm.
     165              :                 bool TryGetJsonPayload(const std::string& designName, JsonPayloadKind kind, std::string& outJson) const;
     166              : 
     167              :                 // True when a full response payload set is cached for the design.
     168              :                 bool HasCachedResponse(const std::string& designName) const;
     169              : 
     170              :                 // Synchronous lazy population: builds and commits the response payloads
     171              :                 // for the currently cached design (no-op if the design is not cached or
     172              :                 // was already serialized for the current generation). Used by the gRPC
     173              :                 // GetDesign fast path's cold branch and by tests.
     174              :                 void SerializeResponsePayloads(const std::string& designName);
     175              : 
     176              :                 // Times a response payload set was built and committed (one per design
     177              :                 // per generation — warm GetDesign hits add nothing). Test seam for the
     178              :                 // "exactly one to_protobuf call" acceptance criterion.
     179              :                 std::uint64_t designSerializationCount() const;
     180              : 
     181              :                 // Current invalidation generation for the design's serialized response
     182              :                 // payloads (bumped by AddFileArchive / InvalidateDesign / eviction /
     183              :                 // payload invalidation). Consumers fold it into cache validators (ETags)
     184              :                 // so in-memory-only changes invalidate them.
     185              :                 std::uint64_t GetResponseGeneration(const std::string& designName) const;
     186              : 
     187              :                 // Total bytes currently charged to the LRU byte budget (archive/Design
     188              :                 // estimates + serialized response payloads). Test seam for budget
     189              :                 // accounting (e.g. eviction uncharges the full contribution).
     190              :                 std::uint64_t cachedBytes() const;
     191              : 
     192              :                 // Total bytes currently charged to serialized payloads (already included
     193              :                 // in the LRU byte budget). Drops to 0 on eviction/invalidation/Clear().
     194              :                 std::uint64_t cachedResponseBytes() const;
     195              : 
     196              :                 // ---- monolithic serve budget (M6) ----
     197              :                 //
     198              :                 // Designs whose estimated serialized wire size (ProductModel::Design::
     199              :                 // EstimateWireSizeBytes) exceeds this budget are (a) rejected by the
     200              :                 // monolithic gRPC GetDesign handler with RESOURCE_EXHAUSTED (the tree
     201              :                 // build + serialized copy is the 10 GiB-pod OOM) and (b) skipped by the
     202              :                 // background response pre-serialization (same tree build); they are
     203              :                 // served by the chunked GetDesignStream RPC instead. 0 disables the
     204              :                 // budget (pre-M6 behavior: every design serializes monolithically).
     205              :                 void setMonolithicWireBudget(std::uint64_t maxBytes);
     206              :                 std::uint64_t getMonolithicWireBudget() const;
     207              : 
     208              :         private:
     209              :                 std::string m_directory;
     210              : 
     211              :                 FileModel::Design::FileArchive::StringMap m_fileArchivesByName;
     212              :                 ProductModel::Design::StringMap m_designsByName;
     213              : 
     214              :                 // Protects m_fileArchivesByName, m_designsByName, and m_directory
     215              :                 // Use shared_lock for reads, unique_lock for writes
     216              :                 mutable std::shared_mutex m_cacheMutex;
     217              : 
     218              :                 // ---- single-flight load bookkeeping ----
     219              :                 //
     220              :                 // Lock order (never acquired in reverse; allowed nestings are
     221              :                 // m_lruMutex -> m_loadStateMutex inside eviction and
     222              :                 // m_lruMutex -> ResponseStore::m_mutex inside payload commit):
     223              :                 //   m_cacheMutex               -> (nothing)
     224              :                 //   m_lruMutex                 -> m_loadStateMutex, ResponseStore::m_mutex
     225              :                 //   ResponseStore::m_mutex     -> (nothing)
     226              :                 //   m_loadStateMutex           -> (nothing)
     227              :                 // All other critical sections take a single lock at a time.
     228              : 
     229              :                 using DesignFuture = std::shared_future<std::shared_ptr<ProductModel::Design>>;
     230              :                 using FileArchiveFuture = std::shared_future<std::shared_ptr<FileModel::Design::FileArchive>>;
     231              :                 using LoadStateMap = std::unordered_map<std::string, LoadState>;
     232              :                 using LoadObserverList = std::vector<LoadEventCallback>;
     233              : 
     234              :                 // Exactly one parse per design name: the thread that emplaces the entry runs
     235              :                 // the parse and fulfils the promise; concurrent callers block on the same
     236              :                 // shared_future. Erased on completion AND on failure (failed loads retry).
     237              :                 std::unordered_map<std::string, DesignFuture> m_designsInFlight;
     238              :                 std::unordered_map<std::string, FileArchiveFuture> m_fileArchivesInFlight;
     239              : 
     240              :                 LoadStateMap m_loadStatesByName;
     241              :                 LoadObserverList m_loadObservers;
     242              : 
     243              :                 // Cache generation, guarded by m_loadStateMutex: Clear() increments it. A
     244              :                 // load captures it at in-flight registration; a mismatch at completion
     245              :                 // means Clear() ran mid-parse and the load must abandon its bookkeeping
     246              :                 // (no cache insert, no LRU charge, no state transition) while still
     247              :                 // delivering the parsed value to its direct callers.
     248              :                 std::uint64_t m_epoch = 0;
     249              : 
     250              :                 // Protects the in-flight maps, m_loadStatesByName, m_loadObservers, and m_epoch
     251              :                 mutable std::mutex m_loadStateMutex;
     252              : 
     253              :                 // Names with a background load kicked but not yet finished (queued on the
     254              :                 // semaphore or parsing). Closing the between-kick-and-Loading window
     255              :                 // synchronously in LoadDesignAsync makes a second kick for the same name
     256              :                 // deterministically return false instead of racing the background
     257              :                 // thread's Loading announcement. Guarded by m_loadStateMutex.
     258              :                 std::unordered_set<std::string> m_pendingAsyncLoads;
     259              : 
     260              :                 // ---- background-load bookkeeping ----
     261              :                 //
     262              :                 // Counting semaphore for background parses (mutex + cv; C++17 target).
     263              :                 // m_outstandingBackgroundLoads counts spawned-but-unfinished background
     264              :                 // threads (queued or parsing); ~DesignCache drains it so detached loads
     265              :                 // never outlive the cache members they touch. Guarded by m_backgroundMutex.
     266              :                 mutable std::mutex m_backgroundMutex;
     267              :                 std::condition_variable m_backgroundSlotCv;
     268              :                 std::condition_variable m_backgroundDoneCv;
     269              :                 std::size_t m_maxBackgroundLoads = DEFAULT_MAX_BACKGROUND_LOADS;
     270              :                 std::size_t m_activeBackgroundLoads = 0;        // threads currently holding a parse slot
     271              :                 std::size_t m_outstandingBackgroundLoads = 0;   // spawned but unfinished threads
     272              : 
     273              :                 // Thread-local re-entry guard: name of the design whose load the current
     274              :                 // thread is running, set only while the Loading transition (and its
     275              :                 // synchronous observers) is in progress on the loader thread. The joiner
     276              :                 // path of GetOrLoadSingleFlight checks it and throws instead of joining
     277              :                 // the thread's own pending future. Held in a function-local thread_local
     278              :                 // because a static thread_local data member of an ODBDESIGN_EXPORT class
     279              :                 // would give the variable dll interface, which MSVC rejects (C2492).
     280          379 :                 static const std::string*& loadingDesignName()
     281              :                 {
     282              :                         thread_local const std::string* s_loadingDesignName = nullptr;
     283          379 :                         return s_loadingDesignName;
     284              :                 }
     285              : 
     286              :                 // ---- byte-budget LRU bookkeeping ----
     287              : 
     288              :                 struct LruEntry
     289              :                 {
     290              :                         std::uint64_t estimatedBytes = 0;
     291              :                         // Bytes charged for the design's cached serialized response payloads
     292              :                         // (included in estimatedBytes' contribution to m_cachedBytes). Kept
     293              :                         // separately so invalidation can uncharge without dropping the
     294              :                         // archive/Design cache entry.
     295              :                         std::uint64_t serializedBytes = 0;
     296              :                         std::chrono::steady_clock::time_point lastServed;
     297              :                 };
     298              : 
     299              :                 using LruEntryMap = std::unordered_map<std::string, LruEntry>;
     300              : 
     301              :                 // Keyed by design name: whether the archive, the Design, or both are cached,
     302              :                 // a name carries a single LRU entry. m_cachedBytes is the sum of estimatedBytes.
     303              :                 // Evicting a name removes its Design and FileArchive cache entries together;
     304              :                 // a Design still referenced by a live caller keeps its shared_ptr to its
     305              :                 // FileArchive, so in-use objects are never destroyed by eviction.
     306              :                 LruEntryMap m_lruEntries;
     307              :                 std::uint64_t m_cachedBytes = 0;
     308              :                 std::uint64_t m_maxBytes = DEFAULT_CACHE_MAX_BYTES;
     309              : 
     310              :                 // Protects m_lruEntries, m_cachedBytes, and m_maxBytes
     311              :                 mutable std::mutex m_lruMutex;
     312              : 
     313              :                 // Monolithic serve budget (M6); see setMonolithicWireBudget. Guarded by
     314              :                 // m_lruMutex (read on the serialization paths alongside the budget
     315              :                 // bookkeeping).
     316              :                 std::uint64_t m_monolithicWireBudget = DEFAULT_MONOLITHIC_WIRE_BUDGET;
     317              : 
     318              :                 // ---- serialized-response cache (M1.4) ----
     319              :                 //
     320              :                 // The pre-serialized response payloads for one design.
     321              :                 struct ResponsePayload
     322              :                 {
     323              :                         std::string designPbBytes;   // serialized ProductModel::Design (gRPC GetDesign response bytes)
     324              :                         std::string designJson;      // ProductModel::Design::to_json()  (/designs/<name>)
     325              :                         std::string fileModelJson;   // FileArchive::to_json()           (/filemodels/<name>)
     326              : 
     327          106 :                         std::uint64_t totalBytes() const
     328              :                         {
     329          106 :                                 return static_cast<std::uint64_t>(designPbBytes.size()) +
     330          106 :                                         static_cast<std::uint64_t>(designJson.size()) +
     331          106 :                                         static_cast<std::uint64_t>(fileModelJson.size());
     332              :                         }
     333              :                 };
     334              : 
     335              :                 // Payload store with per-design invalidation generations. A committer
     336              :                 // captures CurrentGeneration before serializing; TryStore succeeds only
     337              :                 // while the generation is unchanged, and stores at most once per
     338              :                 // (design, generation): a duplicate commit for an already-stored
     339              :                 // generation is a no-op success (this is what makes the design-
     340              :                 // serialization counter exact under racing background/lazy committers).
     341              :                 // Self-contained behind m_mutex; never calls back into DesignCache.
     342              :                 class ResponseStore
     343              :                 {
     344              :                 public:
     345              :                         struct StoreResult
     346              :                         {
     347              :                                 bool stored = false;            // payload is current for (name, generation)
     348              :                                 std::uint64_t storedBytes = 0;  // bytes now held for the name
     349              :                         };
     350              : 
     351              :                         bool TryGetDesignBytes(const std::string& designName, std::string& outBytes) const;
     352              :                         bool TryGetJsonPayload(const std::string& designName, JsonPayloadKind kind, std::string& outJson) const;
     353              :                         bool HasEntry(const std::string& designName) const;
     354              :                         std::uint64_t StoredBytes(const std::string& designName) const;
     355              :                         std::uint64_t TotalStoredBytes() const;
     356              :                         std::uint64_t CurrentGeneration(const std::string& designName) const;
     357              :                         StoreResult TryStore(const std::string& designName, std::uint64_t generation, ResponsePayload&& payload);
     358              :                         // Bumps the generation tombstone for each named design without
     359              :                         // touching entries (Clear() companion — see ResponseStore::Clear).
     360              :                         void BumpGenerations(const std::vector<std::string>& designNames);
     361              :                         // Drops the entry and bumps the generation; returns the dropped bytes.
     362              :                         std::uint64_t Invalidate(const std::string& designName);
     363              :                         void Clear();
     364              :                         std::uint64_t designSerializations() const;
     365              : 
     366              :                 private:
     367              :                         struct Entry
     368              :                         {
     369              :                                 ResponsePayload payload;
     370              :                         };
     371              : 
     372              :                         mutable std::mutex m_mutex;
     373              :                         std::unordered_map<std::string, Entry> m_entriesByName;
     374              :                         // Per-design invalidation generation (monotonically increasing
     375              :                         // tombstones; absent = 0). Single source of truth for TryStore
     376              :                         // validation — survives entry erasure so a commit that captured a
     377              :                         // pre-invalidation generation always loses.
     378              :                         std::unordered_map<std::string, std::uint64_t> m_generationsByName;
     379              :                         std::uint64_t m_designSerializations = 0;
     380              :                 };
     381              : 
     382              :                 ResponseStore m_responseStore;
     383              : 
     384              :                 // Builds the payload set from a loaded Design. The protobuf tree is
     385              :                 // built once: the serialized bytes and the Design JSON both come from
     386              :                 // the same message (no second ProductModel traversal). Non-static
     387              :                 // (M6): consults the monolithic serve budget to skip the tree build
     388              :                 // for over-budget designs.
     389              :                 ResponsePayload BuildResponsePayload(const ProductModel::Design& design);
     390              : 
     391              :                 // Validates (epoch, LRU presence, Design identity, generation) and
     392              :                 // commits a payload set, charging its bytes to the design's LRU entry
     393              :                 // and evicting over budget (never this design). Abort silently leaves
     394              :                 // the cache unchanged.
     395              :                 void CommitResponsePayloads(const std::string& designName,
     396              :                         std::uint64_t epochAtStart,
     397              :                         const std::shared_ptr<ProductModel::Design>& pDesign,
     398              :                         ResponsePayload&& payload,
     399              :                         std::uint64_t generation);
     400              : 
     401              :                 // Schedules a detached background thread that builds + commits the
     402              :                 // payloads for a design that just reached Loaded. Counted/drained via
     403              :                 // m_outstandingBackgroundLoads exactly like background loads.
     404              :                 void ScheduleResponsePreSerialization(const std::string& designName,
     405              :                         std::shared_ptr<ProductModel::Design> pDesign,
     406              :                         std::uint64_t epochAtStart);
     407              : 
     408              :                 // Body of the background pre-serialization thread. Never lets an
     409              :                 // exception escape.
     410              :                 void PreSerializeWorker(std::string designName,
     411              :                         std::shared_ptr<ProductModel::Design> pDesign,
     412              :                         std::uint64_t epochAtStart,
     413              :                         std::uint64_t generation);
     414              : 
     415              :                 // Drops the payload entry (generation bump) and uncharges its bytes
     416              :                 // from the design's LRU entry, when one exists.
     417              :                 void InvalidateResponsePayloads(const std::string& designName);
     418              : 
     419              :                 // Resyncs one LRU entry's serializedBytes with the store (charge delta).
     420              :                 // Requires m_lruMutex NOT held.
     421              :                 void AdjustLruSerializedBytes(const std::string& designName);
     422              : 
     423              :                 // Log helper for GetOrLoadSingleFlight's failure path: the template
     424              :                 // lives in this header, where the Logger macros are not included.
     425              :                 void LogFailedStateRecordError(const std::string& designName);
     426              : 
     427              :                 // Current cache generation snapshot (for lazy serialization commits).
     428              :                 std::uint64_t CurrentEpoch() const;
     429              : 
     430              :                 std::shared_ptr<ProductModel::Design> LoadDesign(const std::string& designName);
     431              :                 std::shared_ptr<FileModel::Design::FileArchive> LoadFileArchive(const std::string& designName);
     432              :                 std::shared_ptr<FileModel::Design::FileArchive> GetFileArchiveInternal(const std::string& designName, bool updateState);
     433              : 
     434              :                 // Shared archive-file-by-stem scan: path of the first regular file in the
     435              :                 // designs directory whose stem matches designName, or an empty path.
     436              :                 std::filesystem::path FindArchivePath(const std::string& designName) const;
     437              : 
     438              :                 // Body of a LoadDesignAsync background thread: queues on the semaphore,
     439              :                 // runs the single-flight load, logs the outcome, then releases its
     440              :                 // bookkeeping. Never lets an exception escape (thread functions must not).
     441              :                 void BackgroundLoad(const std::string& designName);
     442              :                 void AcquireBackgroundSlot();
     443              :                 void ReleaseBackgroundSlot();
     444              : 
     445              :                 // Core single-flight path behind GetDesign/GetFileArchive. Exactly one caller
     446              :                 // per design name runs loadFn; joiners wait on the same shared_future (a failed
     447              :                 // parse rethrows in each waiter). updateState=false for loads nested inside
     448              :                 // another load: LoadDesign pulling the archive must not flip the design's load
     449              :                 // state (Loading/Loaded) mid-load.
     450              :                 template <typename T, typename LoadFn, typename CacheMap, typename InFlightMap>
     451          246 :                 std::shared_ptr<T> GetOrLoadSingleFlight(
     452              :                         const std::string& designName,
     453              :                         CacheMap& cacheMap,
     454              :                         InFlightMap& inFlightMap,
     455              :                         LoadFn loadFn,
     456              :                         bool updateState)
     457              :                 {
     458              :                         // Fast path: shared (read) lock for cache hit
     459          246 :                         bool hit = false;
     460          246 :                         std::shared_ptr<T> pCached;
     461              :                         {
     462          246 :                                 std::shared_lock<std::shared_mutex> readLock(m_cacheMutex);
     463          246 :                                 auto findIt = cacheMap.find(designName);
     464          246 :                                 if (findIt != cacheMap.end())
     465              :                                 {
     466           48 :                                         pCached = findIt->second;
     467           48 :                                         hit = true;
     468              :                                 }
     469          246 :                         }
     470          246 :                         if (hit)
     471              :                         {
     472           48 :                                 TouchLru(designName);
     473           48 :                                 return pCached;
     474              :                         }
     475              : 
     476              :                         // Join an in-flight load, or become its only runner. The design's
     477              :                         // response-payload generation is captured BEFORE the registration
     478              :                         // lock (the store's mutex must never nest inside m_loadStateMutex —
     479              :                         // lock order above): AddFileArchive / InvalidateDesign / eviction
     480              :                         // bump it when they invalidate the design, so a load that raced one
     481              :                         // of those abandons its bookkeeping on completion instead of
     482              :                         // re-inserting contents built from the pre-replacement archive
     483              :                         // (see the abandon checkpoint below).
     484          198 :                         const auto generationAtStart = m_responseStore.CurrentGeneration(designName);
     485          198 :                         std::promise<std::shared_ptr<T>> promise;
     486          198 :                         std::shared_future<std::shared_ptr<T>> future = promise.get_future().share();
     487          198 :                         bool isLoader = false;
     488          198 :                         std::uint64_t epochAtStart = 0;
     489              :                         {
     490          198 :                                 std::lock_guard<std::mutex> lock(m_loadStateMutex);
     491          198 :                                 auto findIt = inFlightMap.find(designName);
     492          198 :                                 if (findIt != inFlightMap.end())
     493              :                                 {
     494           22 :                                         future = findIt->second;
     495              :                                 }
     496              :                                 else
     497              :                                 {
     498          176 :                                         inFlightMap.emplace(designName, future);
     499          176 :                                         isLoader = true;
     500              :                                         // Capture the cache generation at registration: a Clear() during
     501              :                                         // the parse bumps m_epoch and this load abandons its bookkeeping
     502              :                                         // on completion (see WasClearedSince below).
     503          176 :                                         epochAtStart = m_epoch;
     504              :                                 }
     505          198 :                         }
     506              : 
     507          198 :                         if (!isLoader)
     508              :                         {
     509              :                                 // Observer re-entry guard: if this thread is itself the loader of
     510              :                                 // this design (an observer invoked during the Loading transition),
     511              :                                 // waiting here would join our own pending future and deadlock.
     512              :                                 // Reject the re-entry instead of blocking forever.
     513           22 :                                 const std::string* pLoadingName = loadingDesignName();
     514           22 :                                 if (pLoadingName != nullptr && *pLoadingName == designName)
     515              :                                 {
     516            1 :                                         throw std::runtime_error(
     517              :                                                 "DesignCache observer re-entry: load observers must not call back into the DesignCache for the design being loaded");
     518              :                                 }
     519              : 
     520              :                                 // Another thread is parsing this design; wait on its result. A failed
     521              :                                 // parse rethrows here in the waiting thread.
     522           21 :                                 auto pValue = future.get();
     523           21 :                                 TouchLru(designName);
     524           21 :                                 return pValue;
     525           21 :                         }
     526              : 
     527              :                         // Loader-exit safety net: an exception escaping between in-flight
     528              :                         // registration and the explicit fulfilment sites below (realistically
     529              :                         // std::bad_alloc from the Loading state-map insert, which runs before
     530              :                         // the try/catch around loadFn) would leave the promise unsatisfied
     531              :                         // and the in-flight entry registered — every subsequent caller would
     532              :                         // join a dead future forever, with no recovery short of process
     533              :                         // restart (Clear() deliberately leaves in-flight entries to their
     534              :                         // owning threads). On any loader exit without an explicit fulfilment,
     535              :                         // fail the promise and drop the entry.
     536          176 :                         bool promiseSatisfied = false;
     537              :                         struct LoaderExitGuard
     538              :                         {
     539              :                                 DesignCache* m_pCache;
     540              :                                 InFlightMap& m_rInFlightMap;
     541              :                                 const std::string& m_rDesignName;
     542              :                                 std::promise<std::shared_ptr<T>>& m_rPromise;
     543              :                                 bool& m_rSatisfied;
     544              : 
     545          176 :                                 ~LoaderExitGuard()
     546              :                                 {
     547          176 :                                         if (m_rSatisfied)
     548              :                                         {
     549          176 :                                                 return;
     550              :                                         }
     551            0 :                                         m_rPromise.set_exception(std::current_exception()
     552            0 :                                                 ? std::current_exception()
     553            0 :                                                 : std::make_exception_ptr(std::runtime_error(
     554            0 :                                                         "DesignCache: loader exited without completing the load for \"" + m_rDesignName + "\"")));
     555            0 :                                         m_pCache->eraseInFlight(m_rInFlightMap, m_rDesignName);
     556            0 :                                 }
     557          176 :                         } loaderExitGuard{ this, inFlightMap, designName, promise, promiseSatisfied };
     558              : 
     559          176 :                         if (updateState)
     560              :                         {
     561              :                                 // Announce Loading with the re-entry marker set: observers run
     562              :                                 // synchronously on this (loader) thread, and one that re-enters the
     563              :                                 // cache for this design would otherwise join our own pending future
     564              :                                 // and deadlock (the marker makes such a call throw; see the joiner
     565              :                                 // path above).
     566              :                                 struct LoadingMarker
     567              :                                 {
     568          119 :                                         explicit LoadingMarker(const std::string& name) :
     569          119 :                                                 m_previous(loadingDesignName())
     570              :                                         {
     571          119 :                                                 loadingDesignName() = &name;
     572          119 :                                         }
     573          119 :                                         ~LoadingMarker()
     574              :                                         {
     575          119 :                                                 loadingDesignName() = m_previous;
     576          119 :                                         }
     577              :                                         const std::string* m_previous;
     578          119 :                                 } loadingMarker(designName);
     579              : 
     580          119 :                                 TransitionLoadState(designName, LoadState::Loading);
     581          119 :                         }
     582              : 
     583          176 :                         std::shared_ptr<T> pValue;
     584              :                         try
     585              :                         {
     586          176 :                                 pValue = loadFn();
     587              :                         }
     588           30 :                         catch (...)
     589              :                         {
     590              :                                 // Fulfil the shared future first so joiners observe the failure, then
     591              :                                 // record Failed, then drop the in-flight entry. The transition runs
     592              :                                 // while this thread still owns the in-flight entry: a caller arriving
     593              :                                 // mid-transition joins the already-failed future instead of
     594              :                                 // registering a fresh load whose Loading state our late Failed would
     595              :                                 // overwrite (state claiming Failed while a fresh load is in flight).
     596           15 :                                 promise.set_exception(std::current_exception());
     597           15 :                                 promiseSatisfied = true;
     598           15 :                                 if (updateState && !WasClearedSince(epochAtStart))
     599              :                                 {
     600              :                                         // The Failed transition itself can throw (bad_alloc from the
     601              :                                         // state-map insert or the observer-list copy). It must not
     602              :                                         // skip the erase below — that would strand an already-satisfied
     603              :                                         // in-flight entry and wedge the name for every later caller
     604              :                                         // (the promise is fulfilled, so joiners would see the stale
     605              :                                         // failure forever and a fresh load could never register). The
     606              :                                         // transition is best-effort bookkeeping; erase + rethrow are not.
     607              :                                         try
     608              :                                         {
     609           12 :                                                 TransitionLoadState(designName, LoadState::Failed);
     610              :                                         }
     611            0 :                                         catch (...)
     612              :                                         {
     613            0 :                                                 LogFailedStateRecordError(designName);
     614              :                                         }
     615              :                                 }
     616           15 :                                 eraseInFlight(inFlightMap, designName);
     617           15 :                                 throw;
     618              :                         }
     619              : 
     620          161 :                         if (pValue == nullptr)
     621              :                         {
     622              :                                 // Design not found: nothing to cache. A missing design is not a
     623              :                                 // parse failure — erase the state entry the Loading announcement
     624              :                                 // recorded (name reverts to the implicit Unloaded) so
     625              :                                 // m_loadStatesByName stays bounded by names that map to real
     626              :                                 // archives instead of growing on every untrusted route parameter
     627              :                                 // ever requested. Parse exceptions from corrupt archives still
     628              :                                 // record Failed, bounded by the real design count. The erase runs
     629              :                                 // before the in-flight entry is dropped, mirroring the failure
     630              :                                 // path: a caller arriving mid-cleanup joins our already-fulfilled
     631              :                                 // future instead of registering a fresh load whose Loading our
     632              :                                 // late erase would clobber.
     633           25 :                                 promise.set_value(nullptr);
     634           25 :                                 promiseSatisfied = true;
     635           25 :                                 if (updateState)
     636              :                                 {
     637           25 :                                         EraseLoadState(designName);
     638              :                                 }
     639           25 :                                 eraseInFlight(inFlightMap, designName);
     640           25 :                                 return nullptr;
     641              :                         }
     642              : 
     643          136 :                         const auto invalidatedSinceRegistration =
     644          136 :                                 m_responseStore.CurrentGeneration(designName) != generationAtStart;
     645          136 :                         if (WasClearedSince(epochAtStart) || invalidatedSinceRegistration)
     646              :                         {
     647              :                                 // Clear() ran while we parsed (epoch), or the design was
     648              :                                 // invalidated meanwhile (generation bump: AddFileArchive,
     649              :                                 // InvalidateDesign, or eviction) — this load's parse describes
     650              :                                 // pre-replacement contents, so abandon the bookkeeping: no
     651              :                                 // cache insert, no LRU charge, no state transition, no
     652              :                                 // pre-serialization. Inserting anyway would resurrect the
     653              :                                 // stale object under the fresh generation and serve payloads
     654              :                                 // describing the old archive indefinitely. Still deliver the
     655              :                                 // parsed value to our direct callers and drop the in-flight
     656              :                                 // entry.
     657              :                                 //
     658              :                                 // Accepted residual window (bounded, by design): an
     659              :                                 // invalidation/Clear() landing between this check and the
     660              :                                 // unlocked inserts below can re-populate the just-wiped cache
     661              :                                 // (phantom LRU entry / re-inserted object). Closing it fully
     662              :                                 // would require making the check atomic with the inserts —
     663              :                                 // i.e. re-ordering the lock hierarchy — for impact limited to
     664              :                                 // bookkeeping that the next invalidation heals; not worth the
     665              :                                 // churn (the epoch mechanism is best-effort for the same
     666              :                                 // reason).
     667            3 :                                 promise.set_value(pValue);
     668            3 :                                 promiseSatisfied = true;
     669            3 :                                 eraseInFlight(inFlightMap, designName);
     670            3 :                                 return pValue;
     671              :                         }
     672              : 
     673              :                         // Insert into cache under exclusive lock (double-check another thread
     674              :                         // or path — e.g. AddFileArchive — didn't insert while we parsed)
     675              :                         {
     676          133 :                                 std::unique_lock<std::shared_mutex> writeLock(m_cacheMutex);
     677          133 :                                 auto findIt = cacheMap.find(designName);
     678          133 :                                 if (findIt != cacheMap.end())
     679              :                                 {
     680            0 :                                         pValue = findIt->second;
     681              :                                 }
     682              :                                 else
     683              :                                 {
     684          133 :                                         cacheMap[designName] = pValue;
     685              :                                 }
     686          133 :                         }
     687              : 
     688              :                         // Charge the byte budget and evict if over; this design is never its own victim
     689          133 :                         InsertLruAndEvict(designName);
     690              : 
     691              :                         // M1.4: a design just became serveable — schedule background
     692              :                         // pre-serialization of its response payloads (gRPC GetDesign bytes
     693              :                         // + REST JSON variants). Only the design-level load hooks this (the
     694              :                         // archive sub-load runs with updateState=false). The commit is
     695              :                         // validated against epoch/eviction/invalidation, so races with
     696              :                         // Clear()/eviction/AddFileArchive discard the payloads.
     697              :                         if constexpr (std::is_same_v<T, ProductModel::Design>)
     698              :                         {
     699           53 :                                 if (updateState)
     700              :                                 {
     701           53 :                                         ScheduleResponsePreSerialization(designName, pValue, epochAtStart);
     702              :                                 }
     703              :                         }
     704              : 
     705              :                         // Record Loaded while the in-flight entry still exists: a caller
     706              :                         // arriving mid-transition joins our future instead of starting a fresh
     707              :                         // load whose Loading our Loaded would clobber, and joiners woken by
     708              :                         // set_value below then observe Loaded.
     709          133 :                         if (updateState)
     710              :                         {
     711           80 :                                 TransitionLoadState(designName, LoadState::Loaded);
     712              :                         }
     713              : 
     714              :                         // Publish to joiners only once the cache entry and state are visible
     715          133 :                         promise.set_value(pValue);
     716          133 :                         promiseSatisfied = true;
     717          133 :                         eraseInFlight(inFlightMap, designName);
     718          133 :                         return pValue;
     719          308 :                 }
     720              : 
     721              :                 template <typename T>
     722          176 :                 void eraseInFlight(std::unordered_map<std::string, std::shared_future<std::shared_ptr<T>>>& inFlightMap,
     723              :                         const std::string& designName)
     724              :                 {
     725              :                         // The loader thread is the only eraser; erase-by-key is a no-op if Clear()
     726              :                         // or a previous cycle removed the entry meanwhile.
     727          176 :                         std::lock_guard<std::mutex> lock(m_loadStateMutex);
     728          176 :                         inFlightMap.erase(designName);
     729          176 :                 }
     730              : 
     731              :                 void TouchLru(const std::string& designName);
     732              :                 void InsertLruAndEvict(const std::string& designName, std::uint64_t injectedBytes = 0);
     733              :                 std::vector<std::string> EvictOverBudgetLocked(const std::string& protectedName);
     734              :                 void EvictCacheEntries(const std::vector<std::string>& names);
     735              :                 std::uint64_t EstimateDesignBytes(const std::string& designName, std::uint64_t injectedBytes = 0) const;
     736              : 
     737              :                 // Re-estimates a design's LRU charge after its on-disk archive changed
     738              :                 // (e.g. AddFileArchive(save=true) just wrote the file) and adjusts
     739              :                 // m_cachedBytes by the delta. No-op when the name has no LRU entry.
     740              :                 void ResyncLruEstimate(const std::string& designName);
     741              : 
     742              :                 void TransitionLoadState(const std::string& designName, LoadState to);
     743              : 
     744              :                 // Removes a design's load-state entry entirely (its state becomes the
     745              :                 // implicit Unloaded) and notifies observers of the transition. Used when
     746              :                 // a load attempt ends without a result that should keep state (not-found):
     747              :                 // erasing — rather than overwriting with Unloaded — is what bounds
     748              :                 // m_loadStatesByName growth to names that map to real archives.
     749              :                 void EraseLoadState(const std::string& designName);
     750              : 
     751              :                 void NotifyLoadObservers(const std::string& designName, LoadState from, LoadState to, const LoadObserverList& observers);
     752              : 
     753              :                 // True once Clear() has run after the given epoch snapshot was taken
     754              :                 // (see m_epoch); a load in that situation abandons its bookkeeping.
     755              :                 bool WasClearedSince(std::uint64_t epoch) const;
     756              : 
     757              :                 constexpr inline static std::uint64_t DEFAULT_CACHE_MAX_BYTES = 4096ull * 1024ull * 1024ull;
     758              :                 constexpr inline static std::size_t DEFAULT_MAX_BACKGROUND_LOADS = 2;
     759              :                 // Default monolithic serve budget (M6): ~256 MiB of estimated serialized
     760              :                 // wire. Calibrated so every CI design (sample_design, designodb_rigidflex)
     761              :                 // stays monolithic while the two large designs (200-40628, 350-41017 —
     762              :                 // 1.0-1.34 GB serialized) are streaming-only with an order of magnitude
     763              :                 // of margin on both sides.
     764              :                 constexpr inline static std::uint64_t DEFAULT_MONOLITHIC_WIRE_BUDGET = 256ull * 1024ull * 1024ull;
     765              :                 // Rough per-design overhead added to the archive file size; serialized response
     766              :                 // sizes are added to this estimate in M1.4 (response cache).
     767              :                 constexpr inline static std::uint64_t DESIGN_BYTES_OVERHEAD = 4096;
     768              : 
     769              :                 constexpr inline static const char* DESIGN_EXTENSIONS[] = { "zip", "tgz", "tar.gz", "tar", "gzip" , "gz" };
     770              : 
     771              :         };
     772              : }
        

Generated by: LCOV version 2.0-1