GCC Code Coverage Report


Directory: src/
File: src/pg/maintenance.c
Date: 2026-11-18 16:12:57
Exec Total Coverage
Lines: 349 365 95.6%
Functions: 30 30 100.0%
Branches: 125 170 73.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 * maintenance.c - mutating index maintenance functions
6 *
7 * SQL-callable operations that modify prism index pages, and therefore
8 * WAL-log them. Kept separate from the strictly read-only inspection
9 * functions in inspect.c so the write/WAL paths are grouped where they
10 * get the scrutiny persistent mutations need.
11 *
12 * Operations:
13 * prism_convert_posting_to_fastscan(regclass, int4) -- convert one cluster's
14 * posting chain from AoS to fastscan format (procedure)
15 * prism_split_posting_list(regclass, bigint) -- split one list by head block
16 * (procedure)
17 * prism_rebalance(regclass, int4) -- split every list over a given size
18 * (procedure)
19 *
20 * All three are procedures, not functions: they are DDL-like mutating
21 * maintenance and take no return value (reporting via NOTICE). Only
22 * split_posting_list and rebalance additionally require their own
23 * transaction (require_own_transaction): they manage a maintenance pass
24 * across possibly many lists, and letting them run inside a caller's
25 * transaction would offer a rollback that does not roll back the pages
26 * they have already written. convert_posting_to_fastscan performs one
27 * atomic write with no such internal boundary, so it carries no such
28 * restriction -- it is meant to be called in a loop from a DO block or
29 * function, e.g. to convert every cluster a query selects. A rollback leaves
30 * the cluster converted, which is harmless: the entries are the same, and
31 * scans read each page's format rather than trusting the cached flag.
32 */
33
34 #include <postgres.h>
35
36 #include <access/genam.h>
37 #include <access/generic_xlog.h>
38 #include <access/htup_details.h>
39 #include <access/relation.h>
40 #include <access/reloptions.h>
41 #include <access/table.h>
42 #include <access/tableam.h>
43 #include <access/transam.h>
44 #include <access/xact.h>
45 #include <catalog/index.h>
46 #include <catalog/indexing.h>
47 #include <catalog/objectaddress.h>
48 #include <catalog/pg_class.h>
49 #include <executor/tuptable.h>
50 #include <fmgr.h>
51 #include <miscadmin.h>
52 #include <nodes/makefuncs.h>
53 #include <nodes/parsenodes.h>
54 #include <storage/bufmgr.h>
55 #include <storage/lmgr.h>
56 #include <storage/procarray.h>
57 #include <utils/acl.h>
58 #include <utils/builtins.h>
59 #include <utils/injection_point.h>
60 #include <utils/inval.h>
61 #include <utils/lsyscache.h>
62 #include <utils/rel.h>
63 #include <utils/snapmgr.h>
64 #include <utils/syscache.h>
65
66 #include "amcache.h"
67 #include "build.h"
68 #include "index/centroid_page.h"
69 #include "index/index_base.h"
70 #include "index/index_build.h"
71 #include "index/posting_convert.h"
72 #include "index/posting_page.h"
73 #include "index/posting_split.h"
74 #include "inspect.h"
75 #include "meta.h"
76 #include "pg/bufstorage.h"
77 #include "support_pg.h"
78 #include "typeinfo.h"
79 #include "types/vec32.h"
80
81 /*
82 * Lock mode the mutating maintenance entry points take on the index.
83 *
84 * ShareUpdateExclusiveLock rather than RowExclusiveLock, because it conflicts
85 * with itself: two maintenance calls on one index have to serialize. A split
86 * mints ids for its new clusters from the leaf count it read (nlist + j) and
87 * writes the updated count back when it finishes, so two overlapping passes
88 * would hand the same ids to different lists and persist a count too low by
89 * one pass's worth -- which then undercounts leaves for the automatic probe
90 * count and the cost model, and leaves cluster ids ambiguous for
91 * convert_posting_to_fastscan and tids_clusters.
92 *
93 * Like VACUUM's lock (the same mode, for the same "one housekeeper at a time"
94 * reason) it still admits reads and inserts, so maintenance does not block
95 * queries.
96 *
97 * Held until end of transaction, not until the relation is closed: the new
98 * leaf count reaches other backends as a relcache invalidation, which is only
99 * delivered at commit.
100 */
101 #define PRISM_MAINT_LOCK ShareUpdateExclusiveLock
102
103 /*
104 * Refuse to run inside a caller's transaction.
105 *
106 * These procedures reorganize the index; they do not change the data it points
107 * at. Their page writes are not transactional either -- a ROLLBACK leaves the
108 * lists split, the old chains retired and the leaf count raised, while
109 * discarding the relcache invalidation that tells other backends the leaf
110 * count moved. Letting them run inside a transaction block therefore offers a
111 * rollback that does not roll anything back.
112 *
113 * It is also what lets a pass commit as it goes. Splitting each list in its
114 * own transaction -- so a long pass bounds its transaction and can reclaim
115 * what its earlier splits retired -- is impossible from inside a caller's
116 * transaction, which is the reason a procedure was the right shape for this to
117 * begin with.
118 *
119 * The same test VACUUM makes, in the form a procedure has available: a
120 * top-level CALL gets a non-atomic call context, anything else (a transaction
121 * block, a function, a DO block) gets an atomic one.
122 */
123 static void
124 70 require_own_transaction(FunctionCallInfo fcinfo, const char *procname)
125 {
126 140 CallContext *cc = (fcinfo->context != NULL &&
127
1/2
✓ Branch 0 taken 70 times.
✗ Branch 1 not taken.
70 IsA(fcinfo->context, CallContext))
128 ? (CallContext *)fcinfo->context
129
1/2
✓ Branch 0 taken 70 times.
✗ Branch 1 not taken.
70 : NULL;
130
131
2/2
✓ Branch 0 taken 68 times.
✓ Branch 1 taken 2 times.
70 if (cc != NULL && !cc->atomic)
132 68 return;
133
134
1/2
✓ Branch 1 taken 2 times.
✗ Branch 2 not taken.
70 ereport(ERROR,
135 (errcode(ERRCODE_ACTIVE_SQL_TRANSACTION),
136 errmsg("%s cannot run inside a transaction block", procname),
137 errdetail(
138 "It reorganizes the index outside transaction control, "
139 "so a rollback would not undo it."),
140 errhint("Call it on its own, outside BEGIN/COMMIT.")));
141 }
142
143 /*
144 * A PROCEDURE cannot be declared STRICT, so a NULL argument arrives here as a
145 * zero rather than short-circuiting to a NULL result. Left unchecked, a NULL
146 * index reads as OID 0 and fails with "could not open relation with OID 0",
147 * and a NULL block number as block 0 -- errors that describe the internal
148 * consequence instead of the caller's mistake.
149 */
150 static void
151 744 reject_null_arg(FunctionCallInfo fcinfo, int argno, const char *argname)
152 {
153
2/2
✓ Branch 0 taken 3 times.
✓ Branch 1 taken 741 times.
744 if (PG_ARGISNULL(argno))
154
1/2
✓ Branch 1 taken 3 times.
✗ Branch 2 not taken.
3 ereport(ERROR,
155 (errcode(ERRCODE_NULL_VALUE_NOT_ALLOWED),
156 errmsg("%s must not be null", argname)));
157 741 }
158
159 15 PG_FUNCTION_INFO_V1(vs_convert_posting_to_fastscan);
160 13 PG_FUNCTION_INFO_V1(vs_split_posting_list);
161 25 PG_FUNCTION_INFO_V1(vs_rebalance);
162
163 /*
164 * Authorization. convert_posting_to_fastscan mutates the index, so it requires
165 * ownership of the *table* the index belongs to -- the same relation model
166 * PostgreSQL's pgrowlocks/pgstattuple use for relation-level operations.
167 * EXECUTE stays granted to PUBLIC; this runtime check does the per-object
168 * authorization a static GRANT cannot express for a regclass argument.
169 * Superusers pass automatically.
170 */
171 static void
172 764 require_index_owner(Relation index, LOCKMODE lockmode)
173 {
174 764 Oid heaprelid = IndexGetRelation(RelationGetRelid(index), false);
175
2/2
✓ Branch 2 taken 8 times.
✓ Branch 3 taken 756 times.
764 if (!object_ownercheck(RelationRelationId, heaprelid, GetUserId()))
176 {
177 8 char *relname = get_rel_name(heaprelid);
178 8 ObjectType objtype = get_relkind_objtype(get_rel_relkind(heaprelid));
179 8 relation_close(index, lockmode);
180 8 aclcheck_error(ACLCHECK_NOT_OWNER, objtype, relname);
181 }
182 756 }
183
184 /*
185 * Open the index for a maintenance pass and take the maintenance lock.
186 *
187 * The caller is checked under AccessShareLock before the maintenance lock is
188 * requested. ShareUpdateExclusiveLock conflicts with VACUUM and DDL, so a
189 * caller that is going to be refused must not queue a request for it on a
190 * relation it has no privileges on.
191 *
192 * The AccessShareLock is released before the wait. A transaction holding
193 * ShareUpdateExclusiveLock on the index that upgrades to AccessExclusiveLock
194 * (REINDEX, DROP INDEX) would otherwise deadlock with a waiter still holding
195 * the weaker lock. The check runs again under the maintenance lock, since
196 * ownership may have changed meanwhile.
197 */
198 static Relation
199 397 open_index_for_maintenance(Oid indexoid)
200 {
201 397 Relation index = index_open(indexoid, AccessShareLock);
202
203 /* index_open admits a partitioned index, which has no storage. */
204
2/2
✓ Branch 0 taken 3 times.
✓ Branch 1 taken 390 times.
393 if (index->rd_rel->relkind != RELKIND_INDEX)
205
1/2
✓ Branch 1 taken 3 times.
✗ Branch 2 not taken.
3 ereport(ERROR,
206 (errcode(ERRCODE_WRONG_OBJECT_TYPE),
207 errmsg("cannot run maintenance on partitioned index \"%s\"",
208 RelationGetRelationName(index)),
209 errhint("Run it on the index of each partition.")));
210 390 prism_check_index(index);
211 386 require_index_owner(index, AccessShareLock);
212 379 NameData name;
213 379 namestrcpy(&name, RelationGetRelationName(index));
214 379 index_close(index, AccessShareLock);
215
216 379 index = try_index_open(indexoid, PRISM_MAINT_LOCK);
217
2/2
✓ Branch 0 taken 1 times.
✓ Branch 1 taken 378 times.
379 if (index == NULL)
218
1/2
✓ Branch 1 taken 1 times.
✗ Branch 2 not taken.
1 ereport(ERROR,
219 (errcode(ERRCODE_UNDEFINED_OBJECT),
220 errmsg("index \"%s\" was dropped while waiting for the "
221 "maintenance lock",
222 NameStr(name))));
223 378 prism_check_index(index);
224 378 require_index_owner(index, PRISM_MAINT_LOCK);
225 377 return index;
226 }
227
228 /*
229 * Writable pointer to a leaf entry's child block number on a centroid page.
230 * The location depends on the page format: an AoS meta array for the
231 * meta-based formats, or the packed per-group child array for a fastscan
232 * centroid page. This must match how collect_leaf_entries reads the child, or
233 * the compare-and-set in update_centroid_posting_head acts on the wrong slot.
234 */
235 static BlockNumber *
236 644 centroid_child_ptr(Page page, uint16_t entry_idx, Dimension dim)
237 {
238
2/2
✓ Branch 1 taken 574 times.
✓ Branch 2 taken 70 times.
644 if (prism_centroid_page_format(page) == PRISM_CENTROID_FMT_FASTSCAN)
239 {
240 574 char *content = (char *)PageGetContents(page);
241 574 uint32_t g = entry_idx / VS_FASTSCAN_GROUP;
242 574 uint32_t slot = entry_idx % VS_FASTSCAN_GROUP;
243 574 return &prism_centroid_fastscan_group_child(content, g, dim)[slot];
244 }
245 70 return &prism_centroid_meta_mut(page, entry_idx)->child_blkno;
246 }
247
248 /*
249 * Point a centroid leaf entry at new_head via WAL, but only if it still
250 * points at expected_old_head. The compare-and-set runs under the same
251 * exclusive lock as the write, with no gap. The maintenance entry points hold
252 * a self-conflicting lock on the index (PRISM_MAINT_LOCK), so two
253 * of them cannot race on one cluster in the first place -- but the
254 * compare-and-set stays as a gate that does not depend on callers agreeing
255 * about lock modes. The head pointer -- not the posting page's fastscan flag
256 * -- is what conversion actually updates, so it is the correct thing to test.
257 *
258 * Returns true if it performed the update. Returns false if another
259 * converter already moved the head, writing the current head to
260 * *current_head_out (the caller's freshly built chain is then orphaned,
261 * to be reclaimed by a later rebuild/VACUUM).
262 */
263 static bool
264 322 update_centroid_posting_head(
265 Relation index,
266 BlockNumber centroid_page,
267 uint16_t entry_idx,
268 BlockNumber expected_old_head,
269 BlockNumber new_head,
270 Dimension dim,
271 BlockNumber *current_head_out)
272 {
273 322 Buffer buf = ReadBuffer(index, centroid_page);
274 322 LockBuffer(buf, BUFFER_LOCK_EXCLUSIVE);
275
276
1/2
✗ Branch 2 not taken.
✓ Branch 3 taken 322 times.
322 if (*centroid_child_ptr(BufferGetPage(buf), entry_idx, dim) !=
277 expected_old_head)
278 {
279 ✗ *current_head_out =
280 ✗ *centroid_child_ptr(BufferGetPage(buf), entry_idx, dim);
281 ✗ UnlockReleaseBuffer(buf);
282 ✗ return false;
283 }
284
285 322 GenericXLogState *state = GenericXLogStart(index);
286 322 Page page = GenericXLogRegisterBuffer(state, buf, GENERIC_XLOG_FULL_IMAGE);
287 322 *centroid_child_ptr(page, entry_idx, dim) = new_head;
288
289 322 GenericXLogFinish(state);
290 322 UnlockReleaseBuffer(buf);
291 322 return true;
292 }
293
294 /*
295 * Set PRISM_META_FLAG_FASTSCAN on the metadata page if not already set.
296 * Returns true if the flag changed.
297 */
298 static bool
299 324 ensure_meta_fastscan_flag(Relation index)
300 {
301 324 Buffer buf = ReadBuffer(index, 0);
302 324 LockBuffer(buf, BUFFER_LOCK_SHARE);
303 324 Page page = BufferGetPage(buf);
304 324 PrismMetaPage *mp = (PrismMetaPage *)PageGetSpecialPointer(page);
305 324 bool needs_update = !(mp->flags & PRISM_META_FLAG_FASTSCAN);
306 324 UnlockReleaseBuffer(buf);
307
308
2/2
✓ Branch 0 taken 7 times.
✓ Branch 1 taken 317 times.
324 if (needs_update)
309 {
310 7 GenericXLogState *state = GenericXLogStart(index);
311 7 buf = ReadBuffer(index, 0);
312 7 LockBuffer(buf, BUFFER_LOCK_EXCLUSIVE);
313 7 page = GenericXLogRegisterBuffer(state, buf, GENERIC_XLOG_FULL_IMAGE);
314 7 mp = (PrismMetaPage *)PageGetSpecialPointer(page);
315 7 mp->flags |= PRISM_META_FLAG_FASTSCAN;
316 7 GenericXLogFinish(state);
317 7 UnlockReleaseBuffer(buf);
318 }
319 324 return needs_update;
320 }
321
322 /* ----------------------------------------------------------------
323 * CALL prism_convert_posting_to_fastscan(regclass, int4)
324 *
325 * Converts one cluster's posting chain from AoS to fastscan.
326 * Updates the centroid leaf entry and sets the metadata flag.
327 * Reports the new posting head block number via NOTICE.
328 * ---------------------------------------------------------------- */
329 Datum
330 332 vs_convert_posting_to_fastscan(PG_FUNCTION_ARGS)
331 {
332 332 reject_null_arg(fcinfo, 0, "index_oid");
333 332 reject_null_arg(fcinfo, 1, "cluster_id");
334
335 332 Oid indexoid = PG_GETARG_OID(0);
336 332 int32 cluster_id = PG_GETARG_INT32(1);
337 332 Relation index = open_index_for_maintenance(indexoid);
338
339 /* Read metadata */
340 325 Buffer meta_buf = ReadBuffer(index, 0);
341 325 LockBuffer(meta_buf, BUFFER_LOCK_SHARE);
342 325 Page meta_page = BufferGetPage(meta_buf);
343
344 325 const PrismMetaPage *meta = (const PrismMetaPage *)PageGetSpecialPointer(
345 meta_page);
346
347
1/2
✗ Branch 0 not taken.
✓ Branch 1 taken 325 times.
325 if (meta->magic != PRISM_META_MAGIC)
348 {
349 ✗ UnlockReleaseBuffer(meta_buf);
350 ✗ index_close(index, NoLock);
351 ✗ ereport(ERROR,
352 (errcode(ERRCODE_WRONG_OBJECT_TYPE),
353 errmsg("\"%s\" is not a prism index",
354 RelationGetRelationName(index))));
355 }
356
357 325 BlockNumber first_centroid = meta->first_centroid;
358 325 Dimension dim = meta->dim;
359 325 uint8_t nlevels = meta->nlevels;
360 325 UnlockReleaseBuffer(meta_buf);
361
362 /*
363 * Find the leaf for this cluster. The argument is the stored cluster_id --
364 * what prism_posting_pages reports and what callers pass -- not a
365 * positional index. collect_leaf_entries returns leaves in tree-traversal
366 * order, which coincides with cluster_id only for a single-page flat tree;
367 * on any deeper or multi-page tree the two diverge. Match on each leaf's
368 * own head cluster_id so the argument means the same thing everywhere.
369 */
370 325 LeafEntry *leaves;
371 325 int nleaves =
372 325 collect_leaf_entries(index, first_centroid, nlevels, dim, &leaves);
373
374 325 LeafEntry *leaf = NULL;
375
2/2
✓ Branch 1 taken 33925 times.
✓ Branch 2 taken 1 times.
33926 for (int i = 0; i < nleaves; i++)
376 {
377 33925 Buffer hbuf = ReadBuffer(index, leaves[i].posting_head);
378 33925 LockBuffer(hbuf, BUFFER_LOCK_SHARE);
379 33925 uint32_t cid = prism_posting_opaque(BufferGetPage(hbuf))->cluster_id;
380 33925 UnlockReleaseBuffer(hbuf);
381
2/2
✓ Branch 0 taken 324 times.
✓ Branch 1 taken 33601 times.
33925 if (cid == (uint32_t)cluster_id)
382 {
383 324 leaf = &leaves[i];
384 324 break;
385 }
386 }
387
388
2/2
✓ Branch 0 taken 1 times.
✓ Branch 1 taken 324 times.
325 if (leaf == NULL)
389 {
390 1 pfree(leaves);
391 1 index_close(index, NoLock);
392
1/2
✓ Branch 1 taken 1 times.
✗ Branch 2 not taken.
1 ereport(ERROR,
393 (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
394 errmsg("cluster %d not found or has no posting list",
395 cluster_id)));
396 }
397
398 324 BlockNumber old_head = leaf->posting_head;
399 324 BlockNumber centroid_page = leaf->centroid_page;
400 324 uint16_t entry_idx = leaf->entry_idx;
401 324 pfree(leaves);
402
403 /* Convert the posting chain */
404 324 VsPgStorage storage;
405 324 vs_pg_storage_init(&storage, index, NULL, DISTANCE_L2);
406
407 /*
408 * Online conversion, unlike a full index build, has no closing
409 * log_newpage_range() to blanket-WAL the new pages. Keep build_mode off
410 * so each fastscan page is WAL-logged as it is committed (per-page
411 * GenericXLog full image). Otherwise the pages would be dirtied but never
412 * shipped, while the centroid repoint below *is* WAL-logged — leaving a
413 * standby whose centroid points at posting heads it never received.
414 */
415 324 storage.build_mode = false;
416
417 324 bool has_fastscan_base;
418 324 BlockNumber new_head = prism_posting_convert_to_fastscan(
419 &storage.base, old_head, dim, &has_fastscan_base);
420
421
2/2
✓ Branch 0 taken 2 times.
✓ Branch 1 taken 322 times.
324 if (has_fastscan_base)
422 {
423 /* Calling again repairs a conversion that failed before setting the
424 * flag. */
425
1/2
✗ Branch 1 not taken.
✓ Branch 2 taken 2 times.
2 if (ensure_meta_fastscan_flag(index))
426 ✗ CacheInvalidateRelcache(index);
427 2 index_close(index, NoLock);
428
1/2
✓ Branch 1 taken 2 times.
✗ Branch 2 not taken.
2 ereport(NOTICE,
429 (errmsg("cluster %d already has a fastscan base (head block "
430 "%u)",
431 cluster_id,
432 old_head)));
433 2 PG_RETURN_VOID();
434 }
435
436 /*
437 * Publish the new head, but only if a concurrent converter has not
438 * already moved it. If it has, our new_head chain is orphaned and the
439 * winner's head is returned instead.
440 */
441 322 BlockNumber current_head;
442
1/2
✗ Branch 1 not taken.
✓ Branch 2 taken 322 times.
322 if (!update_centroid_posting_head(
443 index,
444 centroid_page,
445 entry_idx,
446 old_head,
447 new_head,
448 dim,
449 &current_head))
450 {
451 ✗ index_close(index, NoLock);
452 ✗ ereport(NOTICE,
453 (errmsg("cluster %d already converted by a concurrent "
454 "call (head block %u)",
455 cluster_id,
456 current_head)));
457 ✗ PG_RETURN_VOID();
458 }
459
460 /* Other backends cache the flag for the planner's cost estimate and the
461 * format a split writes, so drop their cached copy once it is set. Scans
462 * read each page's format and do not depend on it. */
463
2/2
✓ Branch 1 taken 7 times.
✓ Branch 2 taken 315 times.
322 if (ensure_meta_fastscan_flag(index))
464 7 CacheInvalidateRelcache(index);
465
466 /*
467 * Keep PRISM_MAINT_LOCK until end of transaction (NoLock here releases the
468 * reference, not the lock). The invalidation is only delivered at commit,
469 * so releasing the lock now would let the next maintenance call run on a
470 * stale cached metapage.
471 */
472 322 index_close(index, NoLock);
473
474
2/2
✓ Branch 1 taken 261 times.
✓ Branch 2 taken 61 times.
322 ereport(NOTICE,
475 (errmsg("converted cluster %d to fastscan (new head block %u)",
476 cluster_id,
477 new_head)));
478 PG_RETURN_VOID();
479 }
480
481 /* ----------------------------------------------------------------
482 * Heap vector fetch for re-clustering (the PrismSplitEnv seam)
483 * ---------------------------------------------------------------- */
484
485 typedef struct PgSplitFetchCtx
486 {
487 Relation heap;
488 AttrNumber attnum;
489 TupleTableSlot *slot;
490 IndexFetchTableData *fetch;
491 /*
492 * Non-vacuumable: every row version some transaction could still need --
493 * live, recently deleted, or written by a transaction that has not
494 * finished. Only a version already dead to everyone is rejected, which is
495 * the one case where dropping the entry loses nothing, since VACUUM would
496 * remove it anyway.
497 *
498 * Filtering on visibility to *this* transaction instead drops entries
499 * that are still needed. A row deleted after an older scan took its
500 * snapshot is invisible here, but that scan has to keep finding it, and
501 * once the split flips the centroid leaf the new lists are the only place
502 * left to find it. The split is a re-clustering, not a garbage
503 * collection: global removability is the only criterion on which it may
504 * leave an entry out.
505 */
506 SnapshotData snapshot;
507 /* How to read the indexed column as float32 -- the index's own type, not
508 * an assumed one. Carries the conversion buffer, so it outlives a fetch.
509 */
510 Vec32Access access;
511 /* For the reserve-nlist seam, which has only this context to work from. */
512 VsStorage *storage;
513 } PgSplitFetchCtx;
514
515 static bool
516 32407 pg_split_fetch_vector(
517 void *ctx, ItemPointerData tid, float *out, Dimension dim)
518 {
519 32407 PgSplitFetchCtx *c = (PgSplitFetchCtx *)ctx;
520
521 /* Runs in the walk's per-entry context (see ChainTidCb), which is reset
522 * after every entry -- so the detoast below, and a TOAST reassembly if
523 * the vector is stored out of line, need no cleanup of their own.
524 *
525 * Fetched the way the executor fetches an index entry, so a HOT-updated
526 * row is found through its chain. A row the snapshot rejects is dead to
527 * every transaction (see PgSplitFetchCtx.snapshot), so the entry drops
528 * out of the split and is left for VACUUM. */
529 32407 bool call_again = false;
530 32407 bool all_dead = false;
531
2/2
✓ Branch 0 taken 32391 times.
✓ Branch 1 taken 16 times.
32407 if (!table_index_fetch_tuple(
532 32407 c->fetch, &tid, &c->snapshot, c->slot, &call_again, &all_dead))
533 return false;
534
535 /* Test hook: pauses between fetching a row whose insert has not committed
536 * and reading its vector -- the window lock_toast_for_maintenance
537 * describes, which t/003_split_toast_race.pl reproduces. */
538 #ifdef USE_INJECTION_POINTS
539
2/2
✓ Branch 1 taken 25 times.
✓ Branch 2 taken 32366 times.
32391 if (IS_INJECTION_POINT_ATTACHED("prism-split-fetched-uncommitted"))
540 {
541 25 bool shouldfree;
542 25 HeapTuple tup = ExecFetchSlotHeapTuple(c->slot, false, &shouldfree);
543
544
2/2
✓ Branch 1 taken 1 times.
✓ Branch 2 taken 24 times.
25 if (TransactionIdIsInProgress(HeapTupleHeaderGetRawXmin(tup->t_data)))
545 1 INJECTION_POINT("prism-split-fetched-uncommitted", NULL);
546
1/2
✗ Branch 0 not taken.
✓ Branch 1 taken 25 times.
25 if (shouldfree)
547 ✗ heap_freetuple(tup);
548 }
549 #endif
550
551 32391 bool isnull;
552 32391 Datum val = slot_getattr(c->slot, c->attnum, &isnull);
553 32391 bool ok = false;
554
1/2
✓ Branch 0 taken 32391 times.
✗ Branch 1 not taken.
32391 if (!isnull)
555 {
556 /*
557 * Read through the index's own type descriptor, as the insert and
558 * rerank paths do. Reading the datum as a float32 vector directly
559 * would be wrong for any other indexed type: a vec16 column passes
560 * the shape check this maintenance requires, and its 16-bit payload
561 * read as `dim` floats runs off the end of the value and feeds the
562 * split whatever follows it.
563 *
564 * Detoast explicitly rather than leaving it to the descriptor, so the
565 * copy can be released here. A vector wide enough to be stored out of
566 * line is copied on every fetch, and this runs once per entry of every
567 * list a pass touches -- keeping them would cost the whole pass's
568 * worth of vector data on top of the list being clustered.
569 */
570 32391 struct varlena *raw = (struct varlena *)DatumGetPointer(val);
571 32391 struct varlena *flat = pg_detoast_datum(raw);
572 32390 Vec32Ref vref = vec32_read(&c->access, PointerGetDatum(flat));
573
574
2/2
✓ Branch 0 taken 28672 times.
✓ Branch 1 taken 3718 times.
32390 memcpy(out, vref.data, (size_t)dim * sizeof(float));
575 32390 ok = true;
576
577
2/2
✓ Branch 0 taken 28672 times.
✓ Branch 1 taken 3718 times.
32390 if (flat != raw)
578 28672 pfree(flat);
579 }
580 32390 ExecClearTuple(c->slot);
581 32390 return ok;
582 }
583
584 /*
585 * Retire the split's old chain (the PrismSplitEnv seam). Rather than
586 * tombstoning it now — which would make scans skip a head a concurrent query
587 * may still be about to read from a stale pre-flip pointer — mark each page
588 * DELETED and stamp the head with the current next-XID. The chain stays linked
589 * and readable; VACUUM physically retires it once that XID clears the global
590 * visibility horizon (see vs_rebalance). Scans read DELETED pages
591 * (only TOMBSTONED is skipped), so an in-flight scanner still sees the full
592 * old list.
593 */
594 /*
595 * Start the read for the heap block holding `tid`, one step ahead of the walk
596 * that is about to fetch it. PrefetchBuffer does nothing when the block is
597 * already resident, so a cached heap pays a buffer-table probe per distinct
598 * block and no I/O; a cold one gets the read started while the current entry
599 * is still being decoded.
600 */
601 static void
602 4191 pg_prefetch_vector(void *ctx, ItemPointerData tid)
603 {
604 4191 PgSplitFetchCtx *c = (PgSplitFetchCtx *)ctx;
605
606 4191 PrefetchBuffer(c->heap, MAIN_FORKNUM, ItemPointerGetBlockNumber(&tid));
607 4191 }
608
609 static void
610 238 retire_page(PrismPostingPageOpaque *op, void *state)
611 {
612 238 op->flags |= PRISM_POSTING_PAGE_DELETED;
613 /* delete_xid overlays live_count/tail_blkno, unused once retired. */
614 238 op->delete_xid = *(const uint64 *)state;
615 238 }
616
617 static void
618 106 pg_retire_chain(void *ctx, VsStorage *posting_storage, BlockNumber head)
619 {
620 106 (void)ctx;
621 /*
622 * Stamp with this transaction's XID — the one that made the chain
623 * unreachable by committing the centroid flip. Any scan that could still
624 * hold a stale pointer took its snapshot no later than this XID, so once
625 * the global horizon passes it no such scan remains and the chain is safe
626 * to reclaim (the invariant btree page deletion uses). The split has
627 * already written WAL, so an XID is assigned.
628 */
629 106 uint64 dxid = U64FromFullTransactionId(GetTopFullTransactionId());
630
631 106 prism_posting_chain_mutate(posting_storage, head, retire_page, &dxid);
632 106 }
633
634 /* ----------------------------------------------------------------
635 * Helpers
636 * ---------------------------------------------------------------- */
637
638 /* Persist an updated leaf count into the metapage (block 0), in place. */
639 static void
640 140 persist_nlist(VsStorage *storage, uint32_t nlist)
641 {
642 140 Page page = vs_storage_write_page(storage, 0);
643 140 PrismMetaPage *meta = (PrismMetaPage *)PageGetSpecialPointer(page);
644 140 meta->nlist = nlist;
645 140 vs_storage_commit_page(storage, 0);
646 140 }
647
648 /*
649 * Persist the centroid page count (block 0), in place.
650 *
651 * A split that runs out of room on a level-0 centroid page extends the
652 * relation, so the count cannot be recovered from the block layout
653 * afterwards -- see PrismMetaPage.ncentroid_pages. Written once per
654 * maintenance pass rather than per split, alongside the leaf count.
655 *
656 * Losing this write cannot corrupt anything: nothing reads the count to
657 * find a page. It would leave the planner's descent term low until the next
658 * pass.
659 */
660 static void
661 34 persist_ncentroid_pages(VsStorage *storage, uint32_t ncentroid_pages)
662 {
663 34 Page page = vs_storage_write_page(storage, 0);
664 34 PrismMetaPage *meta = (PrismMetaPage *)PageGetSpecialPointer(page);
665 34 meta->ncentroid_pages = ncentroid_pages;
666 34 vs_storage_commit_page(storage, 0);
667 34 }
668
669 /*
670 * Persist the leaf count, so the ids counted from it survive a crash that
671 * leaves the new leaves reachable -- see PrismSplitEnv.reserve_nlist. The
672 * storage handle is reached through the split's fetch context, which is the
673 * only context the seam carries.
674 */
675 static void
676 106 pg_reserve_nlist(void *ctx, uint32_t nlist)
677 {
678 106 PgSplitFetchCtx *c = (PgSplitFetchCtx *)ctx;
679
680 106 persist_nlist(c->storage, nlist);
681 106 }
682
683 static void
684 51 require_supported_shape(Relation index, PrismIndexBase *base)
685 {
686
2/2
✓ Branch 0 taken 50 times.
✓ Branch 1 taken 1 times.
51 if (base->nlevels != 1 ||
687
2/2
✓ Branch 0 taken 1 times.
✓ Branch 1 taken 49 times.
50 base->centroid_format != PRISM_CENTROID_FMT_RABITQ)
688 {
689 2 char *name = pstrdup(RelationGetRelationName(index));
690
1/2
✓ Branch 1 taken 2 times.
✗ Branch 2 not taken.
2 ereport(ERROR,
691 (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
692 errmsg("incremental split is not supported for index \"%s\"",
693 name),
694 errdetail(
695 "Only flat (single-level) indexes with RaBitQ "
696 "centroid pages are supported in this release.")));
697 }
698 49 }
699
700 /*
701 * The memory a split may use, from maintenance_work_mem --
702 * the budget an operator already raises for index work, and the same knob the
703 * bulk build sizes its clustering sample from. A split streams the list, so
704 * this bounds its memory whatever the list's size -- see
705 * prism_split_sample_cap, which turns the budget into a sample size after
706 * reserving what clustering costs alongside it.
707 */
708 static uint64_t
709 156 maint_memory_budget(void)
710 {
711 156 return (uint64_t)maintenance_work_mem * UINT64CONST(1024);
712 }
713
714 /*
715 * Refuse the pass if the budget cannot pay for a split at this dimension,
716 * rather than quietly exceeding it. Checked once per pass: the answer depends
717 * only on the dimension and the setting, so it cannot change list by list.
718 */
719 static void
720 49 require_memory_budget(Relation index, Dimension dim)
721 {
722
2/2
✓ Branch 0 taken 48 times.
✓ Branch 1 taken 1 times.
49 if (prism_split_sample_cap(maint_memory_budget(), dim) > 0)
723 48 return;
724
725 1 uint64 need = prism_split_min_budget_bytes(dim);
726 1 char *name = pstrdup(RelationGetRelationName(index));
727
728
1/2
✓ Branch 1 taken 1 times.
✗ Branch 2 not taken.
49 ereport(ERROR,
729 (errcode(ERRCODE_INSUFFICIENT_RESOURCES),
730 errmsg("maintenance_work_mem is too small to split a posting "
731 "list of index \"%s\"",
732 name),
733 errdetail(
734 "Splitting %u-dimension vectors needs at "
735 "least " UINT64_FORMAT
736 " kB, but maintenance_work_mem is %d kB.",
737 (uint32)dim,
738 (need + 1023) / 1024,
739 maintenance_work_mem),
740 errhint("Increase maintenance_work_mem and retry.")));
741 }
742
743 /*
744 * Is this posting page a live chain head -- reachable, not retired, not all
745 * dead? Written the same way wherever it is asked (the maintenance scan, the
746 * re-read under the head lock, vacuum's head recognition), so the three cannot
747 * drift.
748 */
749 static bool
750 109 posting_head_is_live(const PrismPostingPageOpaque *op)
751 {
752
2/4
✓ Branch 0 taken 109 times.
✗ Branch 1 not taken.
✓ Branch 2 taken 109 times.
✗ Branch 3 not taken.
109 return prism_posting_is_head_start(op->flags) &&
753
3/4
✓ Branch 0 taken 109 times.
✗ Branch 1 not taken.
✓ Branch 2 taken 2 times.
✓ Branch 3 taken 107 times.
218 !(op->flags & PRISM_POSTING_PAGE_TOMBSTONED) &&
754 !(op->flags & PRISM_POSTING_PAGE_DELETED);
755 }
756
757 /*
758 * Split the posting head at `head` if it is a live first page and, when
759 * target > 0, holds more entries than the split trigger
760 * (prism_split_trigger). Serialized against inserts to the same
761 * cluster by the head page lock. Returns true and fills *res if a split
762 * happened.
763 *
764 * The live_count test here is only a cheap early-out on a page already read.
765 * The authoritative check is inside prism_posting_split, against the entry
766 * count after collection: live_count does not account for entries whose vector
767 * can no longer be fetched, so a list can look oversized here and turn out not
768 * to be.
769 *
770 * target also sets the width -- round(count / target) parts, so each new list
771 * rests at the target with room to grow back to the trigger. With target == 0
772 * the split is unconditional and 2-way: the manual escape hatch.
773 */
774 static bool
775 109 split_one_head(
776 Relation index,
777 PrismIndexBase *base,
778 PgSplitFetchCtx *fc,
779 BlockNumber head,
780 uint32_t target,
781 PrismSplitResult *res)
782 {
783 109 LockPage(index, head, ExclusiveLock);
784
785 109 Page p = vs_storage_read_page(base->posting_storage, head);
786
1/2
✓ Branch 1 taken 109 times.
✗ Branch 2 not taken.
109 bool live_head = prism_page_is_posting(p) &&
787
2/2
✓ Branch 0 taken 107 times.
✓ Branch 1 taken 2 times.
109 posting_head_is_live(prism_posting_opaque(p));
788 /* live_count is meaningful only when the head is live: delete_xid overlays
789 * it once DELETED, which posting_head_is_live excludes. */
790 107 uint32_t live = live_head ? prism_posting_opaque(p)->live_count : 0;
791 109 vs_storage_release_page(base->posting_storage, head);
792
793
4/4
✓ Branch 0 taken 107 times.
✓ Branch 1 taken 2 times.
✓ Branch 2 taken 104 times.
✓ Branch 3 taken 3 times.
109 if (!live_head ||
794
1/2
✗ Branch 0 not taken.
✓ Branch 1 taken 104 times.
104 (target > 0 && (uint64_t)live <= prism_split_trigger(target)))
795 {
796 2 UnlockPage(index, head, ExclusiveLock);
797 2 return false;
798 }
799
800 107 PrismSplitEnv env = {
801 .fetch_vector = pg_split_fetch_vector,
802 .prefetch_vector = pg_prefetch_vector,
803 .retire_chain = pg_retire_chain,
804 .reserve_nlist = pg_reserve_nlist,
805 .ctx = fc,
806 };
807 /*
808 * Test hook: fires holding the old head's page lock, with the centroid
809 * leaf still pointing at it. That is the window an isolation test needs --
810 * an insert routed now reaches this head, blocks on the page lock, and
811 * once the split below has flipped the leaf and retired the chain it wakes
812 * to find the head retired and has to route again. Firing after the split
813 * instead would prove nothing: the leaf would already point elsewhere, so
814 * the insert would route straight to a new head and never contend.
815 *
816 * No-op unless PG was built with injection points and a test attached an
817 * action.
818 */
819 107 INJECTION_POINT("prism-split-locked", NULL);
820
821 107 PrismSplitConfig cfg = {
822 .target_entries = target,
823 .sample_budget_bytes = maint_memory_budget(),
824 };
825 107 int rc = prism_posting_split(base, head, &cfg, &env, res);
826
827 106 UnlockPage(index, head, ExclusiveLock);
828
829
2/4
✓ Branch 0 taken 106 times.
✗ Branch 1 not taken.
✗ Branch 2 not taken.
✓ Branch 3 taken 106 times.
106 return rc == 0 && res->did_split;
830 }
831
832 /*
833 * Resolve the resting list size maintenance should aim at.
834 *
835 * Derived from the row count alone, deliberately ignoring the nlist
836 * reloption. Above the dimension's per-list target squared that is the target
837 * itself; below it the sqrt floor in prism_auto_nlist makes it smaller, which
838 * is the regime where a hardcoded target would fight the build and merge a
839 * small index down to too few lists.
840 *
841 * It used to honour an explicit nlist instead, on the grounds that a
842 * rebalanced index should keep the shape the build chose -- the cost model
843 * and the automatic nprobe both key off nlist. That is a real property and
844 * this gives it up: re-partitioning changes how many lists a query probes.
845 *
846 * What it bought was worse. With target = rows / nlist the target scales with
847 * the table, so an index built with an explicit nlist never splits on growth
848 * at all: lists grow in proportion, the trigger is never reached, and a pass
849 * correctly reports splitting nothing while every probe scans more entries
850 * than the last time. A number typed once at CREATE INDEX would silently
851 * switch off maintenance for the life of the index -- and once maintenance is
852 * VACUUM-driven, nothing would ever revisit it.
853 *
854 * A list should rest at the size that keeps a probe's cost flat, which is
855 * what prism_target_entries_per_dim is for. nlist stays what the user asked
856 * the *build* for; it is not a maintenance policy.
857 *
858 * target_pages, by contrast, IS read here, from the index's current
859 * reloptions rather than from whatever the build saw. It names the resting
860 * shape directly, so ALTER INDEX ... SET (target_pages = ...) followed by
861 * rebalance() is the supported way to re-partition an index without
862 * rebuilding it -- deliberate, unlike the nlist case above, where honouring
863 * the option silently switched maintenance off.
864 */
865 static uint32_t
866 4 resolve_target_entries(Relation heap, Relation index, Dimension dim)
867 {
868 4 const PrismOptions *opts = (const PrismOptions *)index->rd_options;
869
1/2
✓ Branch 0 taken 4 times.
✗ Branch 1 not taken.
4 uint32_t tpages = (opts != NULL) ? (uint32_t)opts->target_pages : 0;
870
871 4 return prism_target_entries_per_list(
872 prism_estimate_heap_tuples(heap), 0, dim, tpages);
873 }
874
875 /* Common setup: base + storage + heap fetch context. */
876 typedef struct MaintCtx
877 {
878 PrismIndexBase base;
879 VsPgStorage storage;
880 Relation heap;
881 /* The heap's TOAST relation, locked for the pass. NULL if it has none. */
882 Relation toast;
883 PgSplitFetchCtx fetch;
884 ResourceOwner params_owner;
885 /*
886 * Scratch for one list's split. Splitting a list holds every one of its
887 * vectors at full precision, so the peak is inherent -- but a pass over
888 * many lists must not stack those peaks. Reset between lists (see
889 * maint_split_done) so the cost is one list's worth, not the pass's.
890 */
891 MemoryContext split_ctx;
892 } MaintCtx;
893
894 /*
895 * Lock the heap's TOAST relation for the length of the pass. Returns NULL for
896 * a heap that has none.
897 *
898 * A vector wide enough to be stored out of line is reassembled from the TOAST
899 * relation on every fetch, and the versions the split must keep include ones
900 * written by transactions that have not finished yet. If such a transaction
901 * aborts, its TOAST chunks are dead to everyone the instant it does -- no
902 * snapshot holds them back, the way a committed delete's are held back by the
903 * horizon. A VACUUM of the TOAST relation in that window removes chunks this
904 * pass is part way through reading, and the read fails with "missing chunk
905 * number".
906 *
907 * ShareUpdateExclusiveLock is VACUUM's own lock, so holding it here excludes
908 * exactly that and nothing else: the heap stays open to reads, to writes, and
909 * to its own VACUUM. Autovacuum asks for a TOAST relation's lock
910 * conditionally and skips the relation rather than waiting, so a long pass
911 * delays TOAST cleanup instead of stalling a worker on it.
912 *
913 * VACUUM is all this keeps out. On-access pruning needs no relation lock, and
914 * removes a rolled-back insert's chunks too when the TOAST page is nearly full
915 * and already prunable from some other delete. If that lands between fetching
916 * a row and reading its vector, the split fails with "missing chunk number".
917 * The old list stays in place, so nothing is lost and running the split again
918 * succeeds. The window is narrow enough that this is accepted rather than
919 * guarded against; t/003_split_toast_race.pl reproduces it.
920 *
921 * Taken after the heap's own lock, never before. CLUSTER, REINDEX and VACUUM
922 * all lock the heap first and its TOAST relation second, so acquiring in the
923 * other order here would close a deadlock cycle with them.
924 */
925 static Relation
926 49 lock_toast_for_maintenance(Relation heap)
927 {
928 49 Oid toastoid = heap->rd_rel->reltoastrelid;
929
930
1/2
✓ Branch 0 taken 49 times.
✗ Branch 1 not taken.
49 if (!OidIsValid(toastoid))
931 return NULL;
932
933 49 return table_open(toastoid, ShareUpdateExclusiveLock);
934 }
935
936 static void
937 51 maint_begin(Relation index, MaintCtx *m)
938 {
939 51 m->params_owner = CurrentResourceOwner;
940 51 prism_index_base_init(index, &m->base);
941 51 require_supported_shape(index, &m->base);
942
943 49 vs_pg_storage_init(&m->storage, index, NULL, m->base.metric);
944 49 m->base.centroid_storage = &m->storage.base;
945 49 m->base.posting_storage = &m->storage.base;
946 49 m->base.page_base = NULL;
947
948 49 m->heap = table_open(index->rd_index->indrelid, AccessShareLock);
949 49 m->toast = lock_toast_for_maintenance(m->heap);
950 49 m->fetch.heap = m->heap;
951 49 m->fetch.attnum = index->rd_index->indkey.values[0];
952 49 m->fetch.slot = table_slot_create(m->heap, NULL);
953 #if PG_VERSION_NUM >= 190000
954 m->fetch.fetch = table_index_fetch_begin(m->heap, SO_NONE);
955 #else
956 49 m->fetch.fetch = table_index_fetch_begin(m->heap);
957 #endif
958 49 InitNonVacuumableSnapshot(m->fetch.snapshot, GlobalVisTestFor(m->heap));
959 49 m->fetch.access = vec32_access(
960 49 prism_cache_type_info(index), m->base.dim, CurrentMemoryContext);
961 49 m->fetch.storage = &m->storage.base;
962
963 /* Created here, but not switched into: everything above has to outlive the
964 * per-list resets. */
965 49 m->split_ctx = AllocSetContextCreate(
966 CurrentMemoryContext, "prism split", ALLOCSET_DEFAULT_SIZES);
967 49 }
968
969 /*
970 * Run one list's split with its scratch accounted separately, and release that
971 * scratch before returning. Splitting is where a maintenance pass allocates,
972 * and one list is the logical point at which none of it is needed any more:
973 * the result is returned by value and the index state the caller keeps reading
974 * lives in the pass's own context.
975 */
976 static bool
977 109 split_one_head_in_scratch(
978 Relation index,
979 MaintCtx *m,
980 BlockNumber head,
981 uint32_t target,
982 PrismSplitResult *res)
983 {
984 109 MemoryContext old = MemoryContextSwitchTo(m->split_ctx);
985 109 bool did = split_one_head(index, &m->base, &m->fetch, head, target, res);
986 108 MemoryContextSwitchTo(old);
987 108 MemoryContextReset(m->split_ctx);
988 108 return did;
989 }
990
991 /*
992 * Drop the nlist reloption once maintenance has moved the leaf count away
993 * from it.
994 *
995 * A split restructures the index the way an ALTER plus REINDEX would, only
996 * incrementally and without the exclusive lock -- so the declaration has to
997 * stop claiming a width the index no longer has. Otherwise a later REINDEX
998 * rebuilds at the number typed at CREATE INDEX: an index built with
999 * nlist = 100, grown a hundredfold and split to match, comes back with 100
1000 * lists, and no user could reasonably be expected to ALTER the right value in
1001 * beforehand.
1002 *
1003 * Cleared rather than set to the new count. Writing 10000 in would assert the
1004 * user asked for exactly 10000, which they did not, and it would be a fresh
1005 * pin that goes stale on the next growth cycle. Removing it lets every later
1006 * rebuild derive from the rows as they then are.
1007 *
1008 * Only when the reloption is set. Left out, auto-derivation already lands
1009 * where the splits were heading, and writing anything in would convert "size
1010 * this for my data" into a permanent pin.
1011 *
1012 * The tuple lock is required, not decoration: reloptions live in a pg_class
1013 * column that is also updated in place (ANALYZE's reltuples, say), so a plain
1014 * heap_update here can lose a concurrent inplace update. PostgreSQL warns
1015 * about exactly that -- "missing lock for relation ... @ TID" -- and holding
1016 * AccessExclusiveLock on the index does not satisfy it, because the lock it
1017 * wants is on the catalog row. The index-level lock the pass already holds
1018 * (PRISM_MAINT_LOCK, ShareUpdateExclusiveLock) is what ALTER INDEX ... SET
1019 * takes, so no escalation is needed for the index itself.
1020 */
1021 static void
1022 34 clear_nlist_reloption(Relation index)
1023 {
1024 34 PrismOptions *opts = (PrismOptions *)index->rd_options;
1025
1026
3/4
✓ Branch 0 taken 34 times.
✗ Branch 1 not taken.
✓ Branch 2 taken 4 times.
✓ Branch 3 taken 30 times.
34 if (opts == NULL || opts->nlist <= 0)
1027 4 return; /* never declared: nothing to clear */
1028
1029 30 Relation pgclass = table_open(RelationRelationId, RowExclusiveLock);
1030 30 HeapTuple tuple = SearchSysCacheCopy1(
1031 RELOID, ObjectIdGetDatum(RelationGetRelid(index)));
1032
1033
1/2
✗ Branch 0 not taken.
✓ Branch 1 taken 30 times.
30 if (!HeapTupleIsValid(tuple))
1034 ✗ elog(ERROR,
1035 "cache lookup failed for index %u",
1036 RelationGetRelid(index));
1037
1038 30 bool isnull;
1039 30 Datum old =
1040 30 SysCacheGetAttr(RELOID, tuple, Anum_pg_class_reloptions, &isnull);
1041 30 List *reset = list_make1(makeDefElem(pstrdup("nlist"), NULL, -1));
1042
1/2
✓ Branch 0 taken 30 times.
✗ Branch 1 not taken.
60 Datum newopts = transformRelOptions(
1043 isnull ? (Datum)0 : old, reset, NULL, NULL, false, true);
1044
1045 30 Datum repl_val[Natts_pg_class] = {0};
1046 30 bool repl_null[Natts_pg_class] = {false};
1047 30 bool repl_repl[Natts_pg_class] = {false};
1048
1049
1/2
✓ Branch 0 taken 30 times.
✗ Branch 1 not taken.
30 if (DatumGetPointer(newopts) != NULL)
1050 30 repl_val[Anum_pg_class_reloptions - 1] = newopts;
1051 else
1052 ✗ repl_null[Anum_pg_class_reloptions - 1] = true;
1053 30 repl_repl[Anum_pg_class_reloptions - 1] = true;
1054
1055 30 HeapTuple newtuple = heap_modify_tuple(
1056 tuple, RelationGetDescr(pgclass), repl_val, repl_null, repl_repl);
1057
1058 /*
1059 * Keep the old tid: CatalogTupleUpdate rewrites newtuple->t_self to where
1060 * the new version lands, so unlocking through it would release a lock on
1061 * the wrong row and leave this one held at commit.
1062 */
1063 30 ItemPointerData otid = newtuple->t_self;
1064
1065 30 LockTuple(pgclass, &otid, InplaceUpdateTupleLock);
1066 30 CatalogTupleUpdate(pgclass, &otid, newtuple);
1067 30 UnlockTuple(pgclass, &otid, InplaceUpdateTupleLock);
1068
1069 30 heap_freetuple(newtuple);
1070 30 heap_freetuple(tuple);
1071 30 table_close(pgclass, RowExclusiveLock);
1072 }
1073
1074 static void
1075 47 maint_end(Relation index, MaintCtx *m, bool changed)
1076 {
1077
2/2
✓ Branch 0 taken 34 times.
✓ Branch 1 taken 13 times.
47 if (changed)
1078 {
1079 34 persist_nlist(&m->storage.base, m->base.nlist);
1080 34 persist_ncentroid_pages(&m->storage.base, m->base.ncentroid_pages);
1081 /* The declaration no longer describes the index -- see
1082 * clear_nlist_reloption. */
1083 34 clear_nlist_reloption(index);
1084 /* Drop the cached metapage so later queries see the new leaf count. */
1085 34 CacheInvalidateRelcache(index);
1086 }
1087 47 MemoryContextDelete(m->split_ctx);
1088 47 table_index_fetch_end(m->fetch.fetch);
1089 47 ExecDropSingleTupleTableSlot(m->fetch.slot);
1090 /* Both released here rather than at commit: nothing after this reads the
1091 * heap, so there is no reason to keep VACUUM out any longer. */
1092
1/2
✓ Branch 0 taken 47 times.
✗ Branch 1 not taken.
47 if (m->toast != NULL)
1093 47 table_close(m->toast, ShareUpdateExclusiveLock);
1094 47 table_close(m->heap, AccessShareLock);
1095 47 prism_release_params(m->base.dim, m->base.rabitq_seed, m->params_owner);
1096 47 }
1097
1098 /* ----------------------------------------------------------------
1099 * SQL entry points
1100 * ---------------------------------------------------------------- */
1101
1102 /*
1103 * CALL prism_split_posting_list(index regclass, head_blkno bigint)
1104 *
1105 * Split the single posting list whose head page is head_blkno. Reports via
1106 * NOTICE whether a split happened or was declined (not a live head, too few
1107 * entries, or degenerate data).
1108 */
1109 Datum
1110 13 vs_split_posting_list(PG_FUNCTION_ARGS)
1111 {
1112 13 require_own_transaction(fcinfo, "prism_split_posting_list()");
1113 13 reject_null_arg(fcinfo, 0, "index_oid");
1114 12 reject_null_arg(fcinfo, 1, "head_blkno");
1115
1116 11 Oid indexoid = PG_GETARG_OID(0);
1117 11 int64 blk64 = PG_GETARG_INT64(1);
1118 11 Relation index = open_index_for_maintenance(indexoid);
1119
1120 5 BlockNumber nblocks = RelationGetNumberOfBlocks(index);
1121
2/4
✓ Branch 0 taken 5 times.
✗ Branch 1 not taken.
✗ Branch 2 not taken.
✓ Branch 3 taken 5 times.
5 if (blk64 < 1 || blk64 >= (int64)nblocks)
1122 {
1123 ✗ index_close(index, NoLock);
1124 ✗ ereport(ERROR,
1125 (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
1126 errmsg("block number " INT64_FORMAT " out of range", blk64)));
1127 }
1128
1129 5 MaintCtx m;
1130 5 maint_begin(index, &m);
1131 5 require_memory_budget(index, m.base.dim);
1132
1133 5 PrismSplitResult res;
1134 5 bool did =
1135 5 split_one_head_in_scratch(index, &m, (BlockNumber)blk64, 0, &res);
1136
1137 5 maint_end(index, &m, did);
1138 /*
1139 * Keep PRISM_MAINT_LOCK until end of transaction (NoLock here releases the
1140 * reference, not the lock). maint_end queues a relcache invalidation for
1141 * the new leaf count, and that is only delivered at commit -- release the
1142 * lock now and the next maintenance call could take it, still holding a
1143 * cached index base with the stale count, and mint cluster ids that
1144 * collide with the ones just written.
1145 */
1146 5 index_close(index, NoLock);
1147
1148
2/2
✓ Branch 0 taken 3 times.
✓ Branch 1 taken 2 times.
5 if (did)
1149
1/2
✓ Branch 1 taken 3 times.
✗ Branch 2 not taken.
3 ereport(NOTICE,
1150 (errmsg("split posting list at block " INT64_FORMAT
1151 " into %u lists",
1152 blk64,
1153 res.nparts)));
1154 else
1155 /*
1156 * split_one_head declines for several reasons -- not a live head, too
1157 * few entries, or degenerate data yielding an empty k-means cluster --
1158 * so report the outcome without guessing which.
1159 */
1160
1/2
✓ Branch 1 taken 2 times.
✗ Branch 2 not taken.
2 ereport(NOTICE,
1161 (errmsg("posting list at block " INT64_FORMAT " not split",
1162 blk64)));
1163
1164 5 PG_RETURN_VOID();
1165 }
1166
1167 /* ----------------------------------------------------------------
1168 * CALL prism_rebalance(index regclass, target_entries int4 DEFAULT NULL)
1169 *
1170 * Manual LIRE rebalancing entry point. Scans the index and splits every live
1171 * posting-list head that has grown past the split trigger into lists of about
1172 * target_entries entries each, and physically retires any already-DELETED old
1173 * split chain whose delete_xid has cleared the global visibility horizon.
1174 * Reports the number of lists split via NOTICE. New heads created during the
1175 * pass land past the snapshotted block count and are left for a later call.
1176 *
1177 * target_entries is the size a list *rests* at, not a bound it never crosses.
1178 * A list is left alone until it reaches target_entries *
1179 * PRISM_SPLIT_TRIGGER_FACTOR, so the operating band is
1180 * [target/factor, target*factor] with the target at its centre: room to absorb
1181 * inserts and deletes, and room for the unevenness of a k-means split.
1182 * Pinning the trigger at the target instead
1183 * would leave every fresh list one insert away from splitting again.
1184 *
1185 * NULL derives the target from the index itself (see resolve_target_entries),
1186 * which is what an operator should almost always want; passing a value is an
1187 * override.
1188 *
1189 * Runs in a single transaction, so a chain this pass retires does not become
1190 * reclaimable within it: the pass's own XID cannot clear the visibility
1191 * horizon while it is still running. Reclaiming those chains therefore falls
1192 * to a subsequent call.
1193 *
1194 * Splitting is the only rebalancing performed here, and it is driven by the
1195 * caller -- nothing schedules it.
1196 * ---------------------------------------------------------------- */
1197 Datum
1198 57 vs_rebalance(PG_FUNCTION_ARGS)
1199 {
1200 57 require_own_transaction(fcinfo, "prism_rebalance()");
1201 55 reject_null_arg(fcinfo, 0, "index_oid");
1202
1203
2/2
✓ Branch 0 taken 46 times.
✓ Branch 1 taken 8 times.
54 Oid indexoid = PG_GETARG_OID(0);
1204 /* SQL arg is integer (int4). Unlike the index, a null target is
1205 * meaningful: it asks for the size to be derived from the index. */
1206 54 bool target_given = !PG_ARGISNULL(1);
1207
2/2
✓ Branch 0 taken 46 times.
✓ Branch 1 taken 8 times.
54 int32 target_arg = target_given ? PG_GETARG_INT32(1) : 0;
1208 54 Relation index = open_index_for_maintenance(indexoid);
1209
2/2
✓ Branch 0 taken 1 times.
✓ Branch 1 taken 46 times.
47 if (target_given && target_arg < 1)
1210 {
1211 1 index_close(index, NoLock);
1212
1/2
✓ Branch 1 taken 1 times.
✗ Branch 2 not taken.
1 ereport(ERROR,
1213 (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
1214 errmsg("target_entries must be positive")));
1215 }
1216
1217 46 MaintCtx m;
1218 46 maint_begin(index, &m);
1219 44 require_memory_budget(index, m.base.dim);
1220
1221 39 uint32_t target =
1222 target_given ? (uint32_t)target_arg
1223
2/2
✓ Branch 0 taken 4 times.
✓ Branch 1 taken 39 times.
43 : resolve_target_entries(m.heap, index, m.base.dim);
1224 43 uint64_t trigger = prism_split_trigger(target);
1225
1226 43 BlockNumber nblocks = RelationGetNumberOfBlocks(index);
1227 43 BlockNumber start = Max(m.base.first_posting, 1);
1228 43 int32 nsplits = 0;
1229 43 int32 nreclaimed = 0;
1230
1231
2/2
✓ Branch 0 taken 392 times.
✓ Branch 1 taken 42 times.
434 for (BlockNumber blk = start; blk < nblocks; blk++)
1232 {
1233
1/2
✗ Branch 0 not taken.
✓ Branch 1 taken 392 times.
392 CHECK_FOR_INTERRUPTS();
1234
1235 392 Page p = vs_storage_read_page(&m.storage.base, blk);
1236 392 bool posting = prism_page_is_posting(p);
1237 774 const PrismPostingPageOpaque *op = posting ? prism_posting_opaque(p)
1238
2/2
✓ Branch 0 taken 382 times.
✓ Branch 1 taken 10 times.
392 : NULL;
1239
1240
4/4
✓ Branch 0 taken 230 times.
✓ Branch 1 taken 152 times.
✓ Branch 2 taken 225 times.
✓ Branch 3 taken 5 times.
382 bool is_head = posting && prism_posting_is_head_start(op->flags) &&
1241 !(op->flags & PRISM_POSTING_PAGE_TOMBSTONED);
1242
2/2
✓ Branch 0 taken 202 times.
✓ Branch 1 taken 23 times.
225 bool retired = is_head && (op->flags & PRISM_POSTING_PAGE_DELETED);
1243
2/2
✓ Branch 0 taken 202 times.
✓ Branch 1 taken 190 times.
392 bool candidate = is_head && !retired &&
1244
2/2
✓ Branch 0 taken 98 times.
✓ Branch 1 taken 104 times.
202 (uint64_t)op->live_count > trigger;
1245 /* delete_xid overlays live_count and is meaningful only when DELETED.
1246 */
1247
2/2
✓ Branch 0 taken 23 times.
✓ Branch 1 taken 369 times.
392 uint64 dxid = retired ? op->delete_xid : 0;
1248 392 vs_storage_release_page(&m.storage.base, blk);
1249
1250
2/2
✓ Branch 0 taken 104 times.
✓ Branch 1 taken 288 times.
392 if (candidate)
1251 {
1252 /* Pass the target so split_one_head re-checks under the head
1253 * lock and prism_posting_split re-checks again after collection --
1254 * the list may have shrunk since the unlocked read above, and
1255 * live_count does not see unfetchable entries at all. */
1256 104 PrismSplitResult res;
1257
1/2
✓ Branch 1 taken 103 times.
✗ Branch 2 not taken.
104 if (split_one_head_in_scratch(index, &m, blk, target, &res))
1258 103 nsplits++;
1259 }
1260
2/2
✓ Branch 0 taken 265 times.
✓ Branch 1 taken 23 times.
288 else if (
1261
2/2
✓ Branch 1 taken 3 times.
✓ Branch 2 taken 20 times.
23 retired && GlobalVisCheckRemovableFullXid(
1262 m.heap, FullTransactionIdFromU64(dxid)))
1263 {
1264 /* No snapshot can still hold a stale pointer into this chain, so
1265 * it is safe to physically retire it (its own commits are durable
1266 * independent of maint_end, which only persists nlist). */
1267 20 prism_posting_chain_tombstone(&m.storage.base, blk);
1268 20 nreclaimed++;
1269 }
1270 }
1271
1272 42 maint_end(index, &m, nsplits > 0);
1273 /*
1274 * Keep PRISM_MAINT_LOCK until end of transaction (NoLock here releases the
1275 * reference, not the lock). maint_end queues a relcache invalidation for
1276 * the new leaf count, and that is only delivered at commit -- release the
1277 * lock now and the next maintenance call could take it, still holding a
1278 * cached index base with the stale count, and mint cluster ids that
1279 * collide with the ones just written.
1280 */
1281 42 index_close(index, NoLock);
1282
1283 /*
1284 * Report the reclaim count as well as the split count. A retired chain is
1285 * unreachable from the centroid tree, so nothing that inspects the index
1286 * can see it -- this NOTICE is the only way an operator can tell whether a
1287 * pass freed the chains an earlier one left behind, or whether a reader's
1288 * snapshot is still holding them.
1289 */
1290
2/2
✓ Branch 1 taken 36 times.
✓ Branch 2 taken 6 times.
42 ereport(NOTICE,
1291 (errmsg("rebalance: split %d posting list(s), reclaimed %d "
1292 "retired chain(s)",
1293 nsplits,
1294 nreclaimed)));
1295
1296 42 PG_RETURN_VOID();
1297 }
1298