| 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 | ¤t_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 |