OdbDesign
OdbDesign ODB++ Parser - C++ library, gRPC/REST server, CLI, tests
 
Loading...
Searching...
No Matches
StreamSpoolCache.h
Go to the documentation of this file.
1#pragma once
2
3// StreamSpoolCache — disk-backed spool of a design's GetDesignStream chunk
4// sequence (M6.3, getdesign-streaming-oom-plan.md).
5//
6// The monolithic in-RAM response cache (DesignCache M1.4) is unusable for
7// over-budget designs: its payload IS the multi-GB serialized Design. For
8// those designs the first GetDesignStream fill tees every chunk to a spool
9// file while writing it to the wire; subsequent (warm) requests re-emit the
10// chunks by reading the file record-by-record — never materializing more
11// than one chunk of heap. The RAM cost of a warm hit is page cache, which
12// the kernel reclaims under pressure, instead of anonymous heap.
13//
14// Spool file format: length-delimited protobuf records — each record is the
15// standard varint-encoded byte length of the serialized Odb::Grpc::DesignChunk
16// followed by those bytes, in chunk emission order, so a spool replays the
17// exact chunk sequence (and therefore the exact monolithic Design bytes after
18// reassembly).
19//
20// Identity/invalidation: an entry is valid for (design name, response-cache
21// generation). DesignCache bumps the generation on AddFileArchive (re-upload),
22// InvalidateDesign, and LRU eviction, so a stale spool is detected on the next
23// open and the next fill re-spools the fresh contents. The cache owns a
24// private spool directory (per service instance, under the system temp dir by
25// default, removed in the destructor) so parallel server/test instances never
26// touch each other's files; a total-bytes cap LRU-evicts spool files beyond it.
27
28#include <cstdint>
29#include <filesystem>
30#include <fstream>
31#include <map>
32#include <mutex>
33#include <string>
34
35#include <google/protobuf/message.h>
36
37namespace OdbDesignServer
38{
39 namespace Services
40 {
42 {
43 public:
44 // Default total-bytes cap for the private-directory constructor.
45 static constexpr std::uint64_t kDefaultMaxTotalBytes = 4ull * 1024ull * 1024ull * 1024ull;
46
47 // Creates a cache with a private spool directory under the system
48 // temp directory (keeps parallel instances isolated; the directory
49 // is removed in the destructor). maxTotalBytes defaults to
50 // kDefaultMaxTotalBytes.
51 explicit StreamSpoolCache(std::uint64_t maxTotalBytes = kDefaultMaxTotalBytes);
52
53 // Creates a cache rooted at an explicit directory. The directory is
54 // created if missing; its spool files are NOT removed wholesale by
55 // the destructor (only files this cache itself published).
56 StreamSpoolCache(const std::filesystem::path& directory, std::uint64_t maxTotalBytes);
58
61
62 // Sequential record reader over an open spool file. Never holds
63 // more than one record's bytes in heap.
64 class Reader
65 {
66 public:
67 // Reads the next length-delimited record into `record`.
68 // Returns false at end-of-spool or on a read/parse failure;
69 // Failed() distinguishes the two. A failure poisons the reader.
70 bool Next(google::protobuf::Message& record);
71 bool Failed() const { return m_failed; }
72 // True when the reader reached a clean EOF SHORT of the record
73 // count the entry was committed with — the file was truncated
74 // at a record boundary (or emptied), which framing alone
75 // cannot distinguish from a legitimate end-of-spool.
76 bool Truncated() const { return !m_failed && m_recordsRead < m_expectedRecords; }
77 std::uint64_t RecordsRead() const { return m_recordsRead; }
78 std::uint64_t ExpectedRecords() const { return m_expectedRecords; }
79
80 private:
81 friend class StreamSpoolCache;
82 std::ifstream m_stream;
83 std::uint64_t m_recordsRead = 0;
84 std::uint64_t m_expectedRecords = 0;
85 bool m_failed = false;
86 };
87
88 // Append-only record writer over a spool file. Commit() publishes
89 // the file for warm serving; Abort() deletes it. An uncommitted
90 // writer aborts in its destructor.
91 class Writer
92 {
93 public:
94 Writer() = default;
95 ~Writer();
96 Writer(Writer&& other) noexcept;
97 Writer& operator=(Writer&& other) noexcept;
98
99 // Appends one length-delimited record. Returns false on I/O or
100 // serialization failure (the writer is poisoned afterwards).
101 bool Append(const google::protobuf::Message& record);
102
103 // Flushes, closes, and publishes the spool entry. Returns
104 // false when the flush/close failed (e.g. ENOSPC surfaced only
105 // at flush time) — the incomplete file is deleted instead of
106 // published; the already-delivered cold response stands.
107 bool Commit();
108 // Closes and deletes the spool file without publishing.
109 void Abort();
110
111 std::uint64_t BytesWritten() const { return m_bytesWritten; }
112 std::uint64_t RecordsWritten() const { return m_recordsWritten; }
113 bool OpenForWrite() const { return m_openForWrite; }
114
115 private:
116 friend class StreamSpoolCache;
117 void Close(bool commit);
118
119 std::ofstream m_stream;
120 std::filesystem::path m_path;
121 StreamSpoolCache* m_pCache = nullptr;
122 std::string m_designName;
123 std::uint64_t m_generation = 0;
124 std::uint64_t m_bytesWritten = 0;
125 std::uint64_t m_recordsWritten = 0;
126 bool m_openForWrite = false;
127 bool m_committed = false;
128 bool m_publishSucceeded = false;
129 };
130
131 // True (and fills `readerOut`) when a spool valid for (name,
132 // generation) exists and opens. A stale entry is dropped (its file
133 // deleted). False when no valid spool exists: cold fill required.
134 bool TryOpenReader(const std::string& designName, std::uint64_t generation, Reader& readerOut);
135
136 // Opens a fresh spool file for (name, generation). Returns false
137 // when the spool directory is unusable (caller serves the stream
138 // without spooling).
139 bool BeginWrite(const std::string& designName, std::uint64_t generation, Writer& writerOut);
140
141 // Drops the design's spool entry (and file), if any.
142 void Drop(const std::string& designName);
143
144 // Path-guarded Drop for call sites that observed an entry outside
145 // m_mutex (e.g. after a lock-free is_regular_file probe on a
146 // captured path): removes the entry only if it still refers to the
147 // observed spool file. Paths are unique per fill (generation + pid
148 // + fillId), so neither a different-generation re-publish nor a
149 // same-generation last-committer-wins fill is ever dropped instead
150 // of the stale entry.
151 void DropStaleEntry(const std::string& designName, const std::filesystem::path& expectedPath);
152
153 // Counters (observability/tests).
154 std::uint64_t WarmOpens() const;
155 std::uint64_t TotalSpoolBytes() const;
156 std::size_t EntryCount() const;
157
158 private:
159 struct Entry
160 {
161 std::filesystem::path path;
162 std::uint64_t generation = 0;
163 std::uint64_t bytes = 0;
164 std::uint64_t records = 0;
165 std::uint64_t lastUsed = 0;
166 };
167
168 void InitializeDirectory(const std::filesystem::path& directory, bool ownsDirectory, std::uint64_t maxTotalBytes);
169 std::filesystem::path MakeSpoolPath(const std::string& designName, std::uint64_t generation, std::uint64_t fillId) const;
170 // Returns false when the entry was refused (individually over
171 // spool_max_bytes — file deleted, nothing published).
172 bool PublishEntry(const std::string& designName, const Entry& entry);
173 void EvictOverBudgetLocked(const std::string& protectedName);
174
175 mutable std::mutex m_mutex;
176 std::filesystem::path m_directory;
177 bool m_ownsDirectory = false;
178 std::uint64_t m_maxTotalBytes = 0;
179 std::uint64_t m_totalBytes = 0;
180 std::uint64_t m_warmOpens = 0;
181 std::uint64_t m_useCounter = 0;
182 std::map<std::string, Entry> m_entriesByName;
183 bool m_usable = false;
184 };
185 }
186}
bool Next(google::protobuf::Message &record)
bool Append(const google::protobuf::Message &record)
bool BeginWrite(const std::string &designName, std::uint64_t generation, Writer &writerOut)
void DropStaleEntry(const std::string &designName, const std::filesystem::path &expectedPath)
static constexpr std::uint64_t kDefaultMaxTotalBytes
bool TryOpenReader(const std::string &designName, std::uint64_t generation, Reader &readerOut)
StreamSpoolCache & operator=(const StreamSpoolCache &)=delete
void Drop(const std::string &designName)
StreamSpoolCache(const StreamSpoolCache &)=delete