GCC Code Coverage Report

Directory: src/
File: src/index/storage.h
Date: 2026-09-30 11:11:31
Exec Total Coverage
Lines: 21 22 95.5%
Functions: 8 8 100.0%
Branches: 5 8 62.5%
Line Branch Exec Source
1 /*
2 * Copyright (c) 2026 Tiger Data, Inc.
3 * Licensed under the PostgreSQL License. See LICENSE for details.
4 *
5 * storage.h - Unified I/O abstraction for index page access
6 *
7 * VsStorageOps is a vtable for page and vector I/O. VsStorage is a
8 * base struct containing an ops pointer that implementations embed as
9 * their first member, adding implementation-specific context fields.
10 *
11 * WAL logging and durability are internal to each implementation —
12 * callers just see read/release/write/commit.
13 *
14 * Standalone: embed in a struct with an array of malloc'd 8KB buffers
15 * PG mode: embed in VsPgStorage with Relation + buffer cache
16 * Cloud: embed with remote block store handle (future)
17 *
18 * Caller pattern:
19 *
20 * // Search (read-only hot path)
21 * Page page = vs_storage_read_page(s, blkno);
22 * // ... scan page entries ...
23 * vs_storage_release_page(s, blkno);
24 *
25 * // Build (write path)
26 * Page page = vs_storage_new_page(s, &blkno);
27 * prism_centroid_page_init(page, level);
28 * prism_centroid_page_add(page, dim, ...);
29 * vs_storage_commit_page(s, blkno);
30 */
31
32 #ifndef VS_STORAGE_H
33 #define VS_STORAGE_H
34
35 #include "algo/topk.h"
36 #include "core/types.h"
37
38 #ifdef VS_STANDALONE
39 #include "standalone/pg_compat.h"
40 #else
41 #include <postgres.h>
42
43 #pragma GCC diagnostic push
44 #pragma GCC diagnostic ignored "-Wunused-parameter"
45 #include <storage/bufpage.h>
46 #pragma GCC diagnostic pop
47 #include <storage/itemptr.h>
48 #endif
49
50 typedef struct VsStorage VsStorage;
51
52 typedef struct VsStorageOps
53 {
54 /* Read path */
55 Page (*read_page)(VsStorage *self, BlockNumber blkno);
56 void (*release_page)(VsStorage *self, BlockNumber blkno);
57
58 /*
59 * Advisory async prefetch: hint that blkno will be read soon so the
60 * implementation can start the I/O (e.g. posix_fadvise via
61 * PrefetchBuffer). Best-effort -- a later read_page still performs the
62 * actual read. NULL = unsupported; callers reach it through
63 * vs_storage_prefetch(), which tolerates a NULL op and an invalid block.
64 */
65 void (*prefetch)(VsStorage *self, BlockNumber blkno);
66
67 /* Write path (durability/WAL is internal to implementation) */
68 Page (*write_page)(VsStorage *self, BlockNumber blkno);
69 Page (*new_page)(VsStorage *self, BlockNumber *blkno_out);
70 void (*commit_page)(VsStorage *self, BlockNumber blkno);
71
72 /*
73 * Bulk extend: pre-allocate npages contiguous pages.
74 * Returns the first block number. NULL = not supported.
75 */
76 BlockNumber (*extend)(VsStorage *self, uint32_t npages);
77
78 /*
79 * Rerank candidates with exact distances.
80 *
81 * Fetches full-precision vectors and computes exact L2 for
82 * candidates that can't be pruned by error bounds. The
83 * implementation owns I/O strategy, vector extraction,
84 * and distance computation.
85 *
86 * query and stored vectors are opaque Datums — the storage
87 * knows the vector type and handles extraction + dispatch.
88 *
89 * Input:
90 * query — query vector (float array)
91 * dim — vector dimension
92 * candidates[count] — approximate results (id encodes TID)
93 *
94 * Output:
95 * out_indices[keep] — indices into candidates
96 * out_distances[keep] — exact distances
97 *
98 * Returns: result count (<= keep), sorted by distance asc.
99 * NULL pointer means reranking is not supported.
100 */
101 uint32_t (*rerank)(
102 VsStorage *self,
103 const float *query,
104 Dimension dim,
105 const VsTopKEntry *candidates,
106 uint32_t count,
107 uint32_t keep,
108 uint32_t *out_indices,
109 Distance *out_distances);
110 } VsStorageOps;
111
112 struct VsStorage
113 {
114 const VsStorageOps *ops;
115 };
116
117 /* ----------------------------------------------------------------
118 * Inline wrappers — hide s->ops->fn(s, ...) behind clean calls
119 * ---------------------------------------------------------------- */
120
121 static inline Page
122 19397951 vs_storage_read_page(VsStorage *s, BlockNumber blkno)
123 {
124 /* Every caller
125 * holds an initialized storage; the analyzer cannot see that across
126 * the ops table. */
127 /* NOLINTNEXTLINE(clang-analyzer-core.NullDereference) */
128 19397951 return s->ops->read_page(s, blkno);
129 }
130
131 static inline void
132 19397951 vs_storage_release_page(VsStorage *s, BlockNumber blkno)
133 {
134 19397951 s->ops->release_page(s, blkno);
135 3792919 }
136
137 static inline void
138 40152 vs_storage_prefetch(VsStorage *s, BlockNumber blkno)
139 {
140
4/6
✓ Branch 0 taken 40152 times.
✗ Branch 1 not taken.
✓ Branch 2 taken 10134 times.
✓ Branch 3 taken 30018 times.
✓ Branch 4 taken 10134 times.
✗ Branch 5 not taken.
 40152 if (s != NULL && s->ops->prefetch != NULL && blkno != InvalidBlockNumber)
141 10134 s->ops->prefetch(s, blkno);
142 40152 }
143
144 static inline Page
145 76529 vs_storage_write_page(VsStorage *s, BlockNumber blkno)
146 {
147 76529 return s->ops->write_page(s, blkno);
148 }
149
150 static inline Page
151 1965 vs_storage_new_page(VsStorage *s, BlockNumber *blkno_out)
152 {
153 1965 return s->ops->new_page(s, blkno_out);
154 }
155
156 static inline void
157 78494 vs_storage_commit_page(VsStorage *s, BlockNumber blkno)
158 {
159 78705 s->ops->commit_page(s, blkno);
160 59729 }
161
162 static inline BlockNumber
163 276 vs_storage_extend(VsStorage *s, uint32_t npages)
164 {
165
1/2
✓ Branch 0 taken 276 times.
✗ Branch 1 not taken.
 276 if (s->ops->extend != NULL)
166 276 return s->ops->extend(s, npages);
167 ✗ return InvalidBlockNumber;
168 }
169
170 static inline uint32_t
171 3982 vs_storage_rerank(
172 VsStorage *s,
173 const float *query,
174 Dimension dim,
175 const VsTopKEntry *candidates,
176 uint32_t count,
177 uint32_t keep,
178 uint32_t *out_indices,
179 Distance *out_distances)
180 {
181 3982 return s->ops->rerank(
182 s,
183 query,
184 dim,
185 candidates,
186 count,
187 keep,
188 out_indices,
189 out_distances);
190 }
191
192 #endif /* VS_STORAGE_H */
193