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 385 : static const std::string*& loadingDesignName()
281 : {
282 : thread_local const std::string* s_loadingDesignName = nullptr;
283 385 : 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 103 : std::uint64_t totalBytes() const
328 : {
329 103 : return static_cast<std::uint64_t>(designPbBytes.size()) +
330 103 : static_cast<std::uint64_t>(designJson.size()) +
331 103 : 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 45 : pCached = findIt->second;
467 45 : hit = true;
468 : }
469 246 : }
470 246 : if (hit)
471 : {
472 45 : TouchLru(designName);
473 45 : 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 201 : const auto generationAtStart = m_responseStore.CurrentGeneration(designName);
485 201 : std::promise<std::shared_ptr<T>> promise;
486 201 : std::shared_future<std::shared_ptr<T>> future = promise.get_future().share();
487 201 : bool isLoader = false;
488 201 : std::uint64_t epochAtStart = 0;
489 : {
490 201 : std::lock_guard<std::mutex> lock(m_loadStateMutex);
491 201 : auto findIt = inFlightMap.find(designName);
492 201 : if (findIt != inFlightMap.end())
493 : {
494 22 : future = findIt->second;
495 : }
496 : else
497 : {
498 179 : inFlightMap.emplace(designName, future);
499 179 : 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 179 : epochAtStart = m_epoch;
504 : }
505 201 : }
506 :
507 201 : 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 179 : 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 179 : ~LoaderExitGuard()
546 : {
547 179 : if (m_rSatisfied)
548 : {
549 179 : 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 179 : } loaderExitGuard{ this, inFlightMap, designName, promise, promiseSatisfied };
558 :
559 179 : 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 121 : explicit LoadingMarker(const std::string& name) :
569 121 : m_previous(loadingDesignName())
570 : {
571 121 : loadingDesignName() = &name;
572 121 : }
573 121 : ~LoadingMarker()
574 : {
575 121 : loadingDesignName() = m_previous;
576 121 : }
577 : const std::string* m_previous;
578 121 : } loadingMarker(designName);
579 :
580 121 : TransitionLoadState(designName, LoadState::Loading);
581 121 : }
582 :
583 179 : std::shared_ptr<T> pValue;
584 : try
585 : {
586 179 : 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 164 : 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 139 : const auto invalidatedSinceRegistration =
644 139 : m_responseStore.CurrentGeneration(designName) != generationAtStart;
645 139 : 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 5 : promise.set_value(pValue);
668 5 : promiseSatisfied = true;
669 5 : eraseInFlight(inFlightMap, designName);
670 5 : 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 134 : std::unique_lock<std::shared_mutex> writeLock(m_cacheMutex);
677 134 : auto findIt = cacheMap.find(designName);
678 134 : if (findIt != cacheMap.end())
679 : {
680 0 : pValue = findIt->second;
681 : }
682 : else
683 : {
684 134 : cacheMap[designName] = pValue;
685 : }
686 134 : }
687 :
688 : // Charge the byte budget and evict if over; this design is never its own victim
689 134 : 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 134 : if (updateState)
710 : {
711 81 : TransitionLoadState(designName, LoadState::Loaded);
712 : }
713 :
714 : // Publish to joiners only once the cache entry and state are visible
715 134 : promise.set_value(pValue);
716 134 : promiseSatisfied = true;
717 134 : eraseInFlight(inFlightMap, designName);
718 134 : return pValue;
719 308 : }
720 :
721 : template <typename T>
722 179 : 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 179 : std::lock_guard<std::mutex> lock(m_loadStateMutex);
728 179 : inFlightMap.erase(designName);
729 179 : }
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 : }
|