OdbDesign
OdbDesign ODB++ Parser - C++ library, gRPC/REST server, CLI, tests
 
Loading...
Searching...
No Matches
DesignCache.h
Go to the documentation of this file.
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
25namespace Odb::Lib::App
26{
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);
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.
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
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 static const std::string*& loadingDesignName()
281 {
282 thread_local const std::string* s_loadingDesignName = nullptr;
283 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 std::uint64_t totalBytes() const
328 {
329 return static_cast<std::uint64_t>(designPbBytes.size()) +
330 static_cast<std::uint64_t>(designJson.size()) +
331 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:
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 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 bool hit = false;
460 std::shared_ptr<T> pCached;
461 {
462 std::shared_lock<std::shared_mutex> readLock(m_cacheMutex);
463 auto findIt = cacheMap.find(designName);
464 if (findIt != cacheMap.end())
465 {
466 pCached = findIt->second;
467 hit = true;
468 }
469 }
470 if (hit)
471 {
472 TouchLru(designName);
473 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 const auto generationAtStart = m_responseStore.CurrentGeneration(designName);
485 std::promise<std::shared_ptr<T>> promise;
486 std::shared_future<std::shared_ptr<T>> future = promise.get_future().share();
487 bool isLoader = false;
488 std::uint64_t epochAtStart = 0;
489 {
490 std::lock_guard<std::mutex> lock(m_loadStateMutex);
491 auto findIt = inFlightMap.find(designName);
492 if (findIt != inFlightMap.end())
493 {
494 future = findIt->second;
495 }
496 else
497 {
498 inFlightMap.emplace(designName, future);
499 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 epochAtStart = m_epoch;
504 }
505 }
506
507 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 const std::string* pLoadingName = loadingDesignName();
514 if (pLoadingName != nullptr && *pLoadingName == designName)
515 {
516 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 auto pValue = future.get();
523 TouchLru(designName);
524 return pValue;
525 }
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 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 ~LoaderExitGuard()
546 {
547 if (m_rSatisfied)
548 {
549 return;
550 }
551 m_rPromise.set_exception(std::current_exception()
552 ? std::current_exception()
553 : std::make_exception_ptr(std::runtime_error(
554 "DesignCache: loader exited without completing the load for \"" + m_rDesignName + "\"")));
555 m_pCache->eraseInFlight(m_rInFlightMap, m_rDesignName);
556 }
557 } loaderExitGuard{ this, inFlightMap, designName, promise, promiseSatisfied };
558
559 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 explicit LoadingMarker(const std::string& name) :
569 m_previous(loadingDesignName())
570 {
571 loadingDesignName() = &name;
572 }
573 ~LoadingMarker()
574 {
575 loadingDesignName() = m_previous;
576 }
577 const std::string* m_previous;
578 } loadingMarker(designName);
579
580 TransitionLoadState(designName, LoadState::Loading);
581 }
582
583 std::shared_ptr<T> pValue;
584 try
585 {
586 pValue = loadFn();
587 }
588 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 promise.set_exception(std::current_exception());
597 promiseSatisfied = true;
598 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 TransitionLoadState(designName, LoadState::Failed);
610 }
611 catch (...)
612 {
613 LogFailedStateRecordError(designName);
614 }
615 }
616 eraseInFlight(inFlightMap, designName);
617 throw;
618 }
619
620 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 promise.set_value(nullptr);
634 promiseSatisfied = true;
635 if (updateState)
636 {
637 EraseLoadState(designName);
638 }
639 eraseInFlight(inFlightMap, designName);
640 return nullptr;
641 }
642
643 const auto invalidatedSinceRegistration =
644 m_responseStore.CurrentGeneration(designName) != generationAtStart;
645 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 promise.set_value(pValue);
668 promiseSatisfied = true;
669 eraseInFlight(inFlightMap, designName);
670 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 std::unique_lock<std::shared_mutex> writeLock(m_cacheMutex);
677 auto findIt = cacheMap.find(designName);
678 if (findIt != cacheMap.end())
679 {
680 pValue = findIt->second;
681 }
682 else
683 {
684 cacheMap[designName] = pValue;
685 }
686 }
687
688 // Charge the byte budget and evict if over; this design is never its own victim
689 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 if (updateState)
700 {
701 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 if (updateState)
710 {
711 TransitionLoadState(designName, LoadState::Loaded);
712 }
713
714 // Publish to joiners only once the cache entry and state are visible
715 promise.set_value(pValue);
716 promiseSatisfied = true;
717 eraseInFlight(inFlightMap, designName);
718 return pValue;
719 }
720
721 template <typename T>
722 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 std::lock_guard<std::mutex> lock(m_loadStateMutex);
728 inFlightMap.erase(designName);
729 }
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}
std::function< void(const std::string &designName, LoadState from, LoadState to)> LoadEventCallback
Definition DesignCache.h:47
std::map< std::string, std::shared_ptr< FileArchive > > StringMap
Definition FileArchive.h:62
std::map< std::string, std::shared_ptr< Design > > StringMap
Definition Design.h:127
std::vector< std::string > StringVector
Definition StringVector.h:8
#define ODBDESIGN_EXPORT