GCC Code Coverage Report


Directory: src/
File: src/pg/meta.h
Date: 2026-11-18 16:12:57
Exec Total Coverage
Lines: 6 6 100.0%
Functions: 0 0 -%
Branches: 4 4 100.0%

Line Branch Exec Source
1 /*
2 * Copyright (c) 2026 Tiger Data, Inc.
3 * Licensed under the PostgreSQL License. See LICENSE for details.
4 *
5 * meta.h - Metadata page layout for prism index
6 *
7 * Block 0 of every prism index stores a PrismMetaPage in the
8 * page special area. It records index parameters (dimension, tree
9 * depth, centroid format, distance metric, RaBitQ seed) and the
10 * global mean vector used for RaBitQ query preparation.
11 */
12
13 #ifndef PRISM_META_H
14 #define PRISM_META_H
15
16 #include <postgres.h>
17
18 #pragma GCC diagnostic push
19 #pragma GCC diagnostic ignored "-Wunused-parameter"
20 #include <storage/bufpage.h>
21 #pragma GCC diagnostic pop
22
23 #include "core/types.h"
24 #include "index/index_base.h"
25
26 /*
27 * "PRI" + a format-version byte. Bump the low byte on any incompatible
28 * metapage/layout change so an index built by an older format is rejected at
29 * open rather than silently misread. It is the only version gate the index
30 * has, so it also covers changes outside the metapage. 06 is the initial
31 * format. 07 keeps references too wide for a page on reference pages, and
32 * lets fastscan groups continue across posting pages.
33 */
34 #define PRISM_META_MAGIC ((uint32_t)0x50524907) /* "PRI\x07" */
35
36 /* Metadata flags */
37 #define PRISM_META_FLAG_FASTSCAN 0x01
38
39 typedef struct PrismMetaPage
40 {
41 uint32_t magic; /* PRISM_META_MAGIC */
42 Dimension dim; /* vector dimension */
43 uint8_t nlevels; /* centroid tree depth */
44 uint8_t centroid_format; /* PrismCentroidFormat */
45 BlockNumber first_centroid; /* root centroid page */
46 BlockNumber first_posting; /* first posting page (one past the last
47 * centroid page); lets VACUUM skip the whole
48 * centroid region without scanning it */
49 uint32_t nlist; /* number of leaf centroids */
50 /*
51 * Centroid pages reachable from first_centroid. Maintained rather than
52 * derived: the region a build reserves is [prism_first_centroid_blkno,
53 * first_posting), but a split with no room on a level-0 page extends the
54 * relation and chains the new page past the posting region, so a block
55 * range stops measuring it. prism_rebalance folds each split's additions
56 * back in here.
57 */
58 uint32_t ncentroid_pages;
59 uint8_t metric; /* DistanceMetric */
60 uint8_t fan_out; /* children per tree node */
61 uint8_t flags; /* PRISM_META_FLAG_* */
62 uint8_t reserved;
63 uint64_t rabitq_seed; /* seed for RaBitQ params */
64 /* Global mean vector stored inline after struct, up
65 * to PRISM_GLOBAL_MEAN_MAX_INLINE_DIM; past it the
66 * mean lives in the reference pages at
67 * PRISM_GLOBAL_MEAN_BLKNO (see index_base.h). */
68 } PrismMetaPage;
69
70 #define PRISM_META_FIXED_SIZE \
71 (offsetof(PrismMetaPage, rabitq_seed) + sizeof(uint64_t))
72
73 static inline bool
74 1154 prism_meta_mean_inline(Dimension dim)
75 {
76
4/4
✓ Branch 0 taken 494 times.
✓ Branch 1 taken 83 times.
✓ Branch 3 taken 272 times.
✓ Branch 4 taken 305 times.
879 return prism_global_mean_pages(dim) == 0;
77 }
78
79 /* Special-area size: the struct plus the inline global mean where it fits */
80 #define PRISM_META_SIZE(dim) \
81 (MAXALIGN( \
82 PRISM_META_FIXED_SIZE + (prism_meta_mean_inline(dim) \
83 ? (size_t)(dim) * sizeof(float) \
84 : 0)))
85
86 /*
87 * The shared inline threshold is tight at 8-byte alignment. A smaller
88 * alignment can leave slack in the metapage.
89 */
90 StaticAssertDecl(
91 PRISM_CEILING_ALIGN(PRISM_META_FIXED_SIZE) +
92 (size_t)PRISM_GLOBAL_MEAN_MAX_INLINE_DIM *
93 sizeof(float) <=
94 BLCKSZ - PRISM_CEILING_ALIGN(SizeOfPageHeaderData),
95 "the inline mean must fit the metapage at the threshold");
96 StaticAssertDecl(
97 PRISM_CEILING_ALIGN(PRISM_META_FIXED_SIZE) +
98 (size_t)(PRISM_GLOBAL_MEAN_MAX_INLINE_DIM + 1) *
99 sizeof(float) >
100 BLCKSZ - PRISM_CEILING_ALIGN(SizeOfPageHeaderData),
101 "the inline-mean threshold is tight");
102
103 /* Access the inline global mean vector after the struct (inline layout) */
104 static inline float *
105 219 prism_meta_global_mean(PrismMetaPage *meta)
106 {
107 219 return (float *)((char *)meta + PRISM_META_FIXED_SIZE);
108 }
109
110 static inline const float *
111 275 prism_meta_global_mean_const(const PrismMetaPage *meta)
112 {
113 275 return (const float *)((const char *)meta + PRISM_META_FIXED_SIZE);
114 }
115
116 #endif /* PRISM_META_H */
117