GCC Code Coverage Report

Directory: src/
File: src/core/types.h
Date: 2026-09-30 11:11:31
Exec Total Coverage
Lines: 6 8 75.0%
Functions: 2 3 66.7%
Branches: 1 2 50.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 * vs_types.h - Core type definitions for pg_vectorsearch
6 */
7
8 #ifndef VS_TYPES_H
9 #define VS_TYPES_H
10
11 #include <stdbool.h>
12 #include <stddef.h>
13 #include <stdint.h>
14
15 /*
16 * Flexible array member marker. PostgreSQL's c.h defines this; for
17 * standalone builds we provide an empty fallback so shared headers
18 * can use the same syntax in both contexts.
19 */
20 #ifndef FLEXIBLE_ARRAY_MEMBER
21 #define FLEXIBLE_ARRAY_MEMBER /* empty, C99+ */
22 #endif
23
24 /*
25 * VS_VTABLE_INLINE — hint for vtable functions.
26 *
27 * Clang inlines always_inline functions through static-const vtable
28 * pointers even across target_clones boundaries. GCC errors on
29 * target mismatch, so we omit the attribute there.
30 */
31 #ifdef __clang__
32 #define VS_VTABLE_INLINE __attribute__((always_inline)) static inline
33 #else
34 #define VS_VTABLE_INLINE static inline
35 #endif
36
37 /* Quantized representations */
38 typedef uint8_t ScalarQ8; /* 8-bit scalar quantized */
39 typedef uint8_t BinaryQ; /* Binary quantized byte (packed bits) */
40
41 /* Dimension type (max 65535 dimensions) */
42 typedef uint16_t Dimension;
43
44 /* Cluster/centroid identifier */
45 typedef uint32_t ClusterId;
46
47 /* Distance type (always float for intermediate computations) */
48 typedef float Distance;
49
50 /*
51 * Vec32Ref: Non-owning reference to vector data.
52 *
53 * Used for passing vectors to functions without copying.
54 * The caller is responsible for ensuring the data remains valid.
55 */
56 typedef struct
57 {
58 const float *data;
59 Dimension dim;
60 } Vec32Ref;
61
62 /*
63 * VectorMut: Mutable vector reference.
64 *
65 * Used when the function needs to modify the vector data.
66 */
67 typedef struct
68 {
69 float *data;
70 Dimension dim;
71 } VectorMut;
72
73 /* Distance metric enum */
74 typedef enum
75 {
76 DISTANCE_L2, /* Euclidean (L2 squared) */
77 DISTANCE_INNER_PRODUCT, /* Negative inner product (for max similarity) */
78 DISTANCE_COSINE /* 1 - cosine similarity */
79 } DistanceMetric;
80
81 /*
82 * VsDistanceMode - RaBitQ distance computation mode
83 *
84 * Controls whether search uses asymmetric (full-precision query × 1-bit data)
85 * or symmetric (1-bit query × 1-bit data) distance. Symmetric is ~4x faster
86 * but has higher estimation error.
87 */
88 typedef enum
89 {
90 VS_DISTANCE_MODE_DEFAULT = -1, /* GUC sentinel: use index relopt */
91 VS_DISTANCE_MODE_ASYMMETRIC = 0,
92 VS_DISTANCE_MODE_SYMMETRIC = 1,
93 } VsDistanceMode;
94
95 static inline const char *
96 35 vs_distance_mode_name(VsDistanceMode mode)
97 {
98 31 static const char *names[] = {
99 [VS_DISTANCE_MODE_ASYMMETRIC] = "asymmetric",
100 [VS_DISTANCE_MODE_SYMMETRIC] = "symmetric",
101 };
102 35 return names[mode];
103 }
104
105 /*
106 * VecType - Vector element type for dispatch
107 *
108 * Used by k-means and quantization to select the correct compile-time
109 * specialization. F16C is the hand-written AVX2+FMA+F16C path; F16
110 * relies on compiler auto-vectorization via TARGET_CLONES.
111 */
112 typedef enum
113 {
114 VS_VEC_F32 = 0, /* float32 */
115 VS_VEC_F16 = 1, /* float16 (scalar / auto-vectorized) */
116 VS_VEC_F16C = 2, /* float16 (hand-written F16C SIMD) */
117 } VecType;
118
119 static inline size_t
120 2662 vs_vec_element_size(VecType type)
121 {
122 1512 static const size_t sizes[] =
123 {[VS_VEC_F32] = 4, [VS_VEC_F16] = 2, [VS_VEC_F16C] = 2};
124
1/2
✓ Branch 0 taken 1512 times.
✗ Branch 1 not taken.
 2662 return sizes[type];
125 }
126
127 static inline const char *
128 ✗ vs_vec_type_name(VecType type)
129 {
130 static const char *names[] = {
131 [VS_VEC_F32] = "float32",
132 [VS_VEC_F16] = "float16",
133 [VS_VEC_F16C] = "float16-f16c",
134 };
135 ✗ return names[type];
136 }
137
138 /*
139 * Vec32TypeOps - Inline vtable for compile-time specialization
140 *
141 * Contains function pointers for mixed-type distance computation
142 * (vec_type × float32 centroid). Used internally by k-means and
143 * quantization impl functions where always_inline enables the
144 * compiler to inline through the function pointers.
145 */
146 typedef struct Vec32TypeOps
147 {
148 const char *name; /* "float32" or "float16" */
149 size_t element_size; /* 4 or 2 */
150
151 float (*dot_product)(
152 const void *vec, const float *centroid, Dimension dim);
153 float (*l2_squared)(const void *vec, const float *centroid, Dimension dim);
154 float (*norm_sq)(const void *vec, Dimension dim);
155
156 void (*sum_to_float)(const void *vec, float *accum, Dimension dim);
157 void (*to_float_one)(const void *src, float *dst, Dimension dim);
158
159 /* Returns pointer to float32 data (zero-copy for f32, converts for f16) */
160 const float *(*to_float_block)(
161 const void *src, float *dst, uint32_t count, Dimension dim);
162 } Vec32TypeOps;
163
164 #endif /* VS_TYPES_H */
165