2626
2727#define DEFAULT_TABLE_ACCESS_METHOD "heap"
2828
29+ /* GUCs */
2930extern char * default_table_access_method ;
3031extern bool synchronize_seqscans ;
3132
@@ -40,7 +41,7 @@ struct ValidateIndexState;
4041
4142
4243/*
43- * Result codes for table_{update,delete,lock}_tuple , and for visibility
44+ * Result codes for table_{update,delete,lock_tuple} , and for visibility
4445 * routines inside table AMs.
4546 */
4647typedef enum TM_Result
@@ -68,8 +69,8 @@ typedef enum TM_Result
6869
6970/*
7071 * The affected tuple is currently being modified by another session. This
71- * will only be returned if (update/delete/lock)_tuple are instructed not
72- * to wait.
72+ * will only be returned iftable_ (update/delete/lock_tuple) are
73+ *instructed not to wait.
7374 */
7475TM_BeingModified ,
7576
@@ -82,12 +83,15 @@ typedef enum TM_Result
8283 * When table_update, table_delete, or table_lock_tuple fail because the target
8384 * tuple is already outdated, they fill in this struct to provide information
8485 * to the caller about what happened.
86+ *
8587 * ctid is the target's ctid link: it is the same as the target's TID if the
8688 * target was deleted, or the location of the replacement tuple if the target
8789 * was updated.
90+ *
8891 * xmax is the outdating transaction's XID. If the caller wants to visit the
8992 * replacement tuple, it must check that this matches before believing the
9093 * replacement is really a match.
94+ *
9195 * cmax is the outdating command's CID, but only when the failure code is
9296 * TM_SelfModified (i.e., something in the current transaction outdated the
9397 * tuple); otherwise cmax is zero. (We make this restriction because
@@ -108,10 +112,10 @@ typedef struct TM_FailureData
108112#define TABLE_INSERT_FROZEN 0x0004
109113#define TABLE_INSERT_NO_LOGICAL 0x0008
110114
111- /* flag bitsfortable_lock_tuple */
115+ /* flag bitsfor table_lock_tuple */
112116/* Follow tuples whose update is in progress if lock modes don't conflict */
113117#define TUPLE_LOCK_FLAG_LOCK_UPDATE_IN_PROGRESS (1 << 0)
114- /* Follow update chain and locklastest version of tuple */
118+ /* Follow update chain and locklatest version of tuple */
115119#define TUPLE_LOCK_FLAG_FIND_LAST_VERSION (1 << 1)
116120
117121
@@ -128,8 +132,8 @@ typedef void (*IndexBuildCallback) (Relation index,
128132 * server-lifetime manner, typically as a static const struct, which then gets
129133 * returned by FormData_pg_am.amhandler.
130134 *
131- *I most cases it's not appropriate todirectly call the callbacks directly,
132- *instead use the table_* wrapper functions.
135+ *In most cases it's not appropriate to call the callbacks directly, use the
136+ * table_* wrapper functions instead .
133137 *
134138 * GetTableAmRoutine() asserts that required callbacks are filled in, remember
135139 * to update when adding a callback.
@@ -194,7 +198,7 @@ typedef struct TableAmRoutine
194198void (* scan_end ) (TableScanDesc scan );
195199
196200/*
197- * Restart relation scan. If set_params is set to true,allow {strat,
201+ * Restart relation scan. If set_params is set to true,allow_ {strat,
198202 * sync, pagemode} (see scan_begin) changes should be taken into account.
199203 */
200204void (* scan_rescan ) (TableScanDesc scan ,struct ScanKeyData * key ,
@@ -222,7 +226,7 @@ typedef struct TableAmRoutine
222226
223227/*
224228 * Initialize ParallelTableScanDesc for a parallel scan of this relation.
225- * pscan will be sized according to parallelscan_estimate() for the same
229+ *` pscan` will be sized according to parallelscan_estimate() for the same
226230 * relation.
227231 */
228232Size (* parallelscan_initialize ) (Relation rel ,
@@ -243,7 +247,7 @@ typedef struct TableAmRoutine
243247
244248/*
245249 * Prepare to fetch tuples from the relation, as needed when fetching
246- * tuples for an index scan. The callback has to returna
250+ * tuples for an index scan. The callback has to returnan
247251 * IndexFetchTableData, which the AM will typically embed in a larger
248252 * structure with additional information.
249253 *
@@ -268,16 +272,16 @@ typedef struct TableAmRoutine
268272 * test, return true, false otherwise.
269273 *
270274 * Note that AMs that do not necessarily update indexes when indexed
271- * columns do not change, need to return the current/correct version of a
272- * tupleas appropriate , even if the tid points to an older version of the
273- * tuple.
275+ * columns do not change, need to return the current/correct version of
276+ *the tuplethat is visible to the snapshot , even if the tid points to an
277+ *older version of the tuple.
274278 *
275279 * *call_again is false on the first call to index_fetch_tuple for a tid.
276280 * If there potentially is another tuple matching the tid, *call_again
277281 * needs be set to true by index_fetch_tuple, signalling to the caller
278282 * that index_fetch_tuple should be called again for the same tid.
279283 *
280- * *all_dead, if all_dead is not NULL, should be set to trueif by
284+ * *all_dead, if all_dead is not NULL, should be set to true by
281285 * index_fetch_tuple iff it is guaranteed that no backend needs to see
282286 * that tuple. Index AMs can use that do avoid returning that tid in
283287 * future searches.
@@ -288,14 +292,14 @@ typedef struct TableAmRoutine
288292TupleTableSlot * slot ,
289293bool * call_again ,bool * all_dead );
290294
295+
291296/* ------------------------------------------------------------------------
292297 * Callbacks for non-modifying operations on individual tuples
293298 * ------------------------------------------------------------------------
294299 */
295300
296-
297301/*
298- * Fetch tuple at `tid` into `slot, after doing a visibility test
302+ * Fetch tuple at `tid` into `slot` , after doing a visibility test
299303 * according to `snapshot`. If a tuple was found and passed the visibility
300304 * test, returns true, false otherwise.
301305 */
@@ -390,13 +394,13 @@ typedef struct TableAmRoutine
390394/*
391395 * Perform operations necessary to complete insertions made via
392396 * tuple_insert and multi_insert with a BulkInsertState specified. This
393- *e.g. maye.g. used to flush the relation wheninserting with
394- * TABLE_INSERT_SKIP_WALspecified .
397+ * mayfor example be used to flush the relation, whenthe
398+ * TABLE_INSERT_SKIP_WALoption was used .
395399 *
396400 * Typically callers of tuple_insert and multi_insert will just pass all
397- * the flagsthe apply to them, and each AM has to decide which of them
398- * make sense for it, and then only take actions in finish_bulk_insert
399- *that make sense for a specific AM .
401+ * the flagsthat apply to them, and each AM has to decide which of them
402+ * make sense for it, and then only take actions in finish_bulk_insert for
403+ *those flags, and ignore others .
400404 *
401405 * Optional callback.
402406 */
@@ -412,10 +416,10 @@ typedef struct TableAmRoutine
412416 * This callback needs to create a new relation filenode for `rel`, with
413417 * appropriate durability behaviour for `persistence`.
414418 *
415- * On output *freezeXid, *minmultishould be set to the values appropriate
416- * for pg_class.{relfrozenxid, relminmxid} have to be set to . For AMs that
417- *don't need those fields to be filled they can be set to
418- *InvalidTransactionId, InvalidMultiXactId respectively.
419+ * On output *freezeXid, *minmultimust be set to the values appropriate
420+ * for pg_class.{relfrozenxid, relminmxid}. For AMs that don't need those
421+ * fields to be filled they can be set to InvalidTransactionId and
422+ * InvalidMultiXactId, respectively.
419423 *
420424 * See also table_relation_set_new_filenode().
421425 */
@@ -463,7 +467,7 @@ typedef struct TableAmRoutine
463467 * locked with a ShareUpdateExclusive lock.
464468 *
465469 * Note that neither VACUUM FULL (and CLUSTER), nor ANALYZE go through
466- * this routine, even if (in the latter case), part of the same VACUUM
470+ * this routine, even if (for ANALYZE) it is part of the same VACUUM
467471 * command.
468472 *
469473 * There probably, in the future, needs to be a separate callback to
@@ -487,8 +491,8 @@ typedef struct TableAmRoutine
487491 * sampling, e.g. because it's a metapage that could never contain tuples.
488492 *
489493 * XXX: This obviously is primarily suited for block-based AMs. It's not
490- * clear what a good interface for non block based AMs would be, sodon't
491- *try to invent one yet.
494+ * clear what a good interface for non block based AMs would be, sothere
495+ *isn't one yet.
492496 */
493497bool (* scan_analyze_next_block ) (TableScanDesc scan ,
494498BlockNumber blockno ,
@@ -537,7 +541,7 @@ typedef struct TableAmRoutine
537541/*
538542 * See table_relation_estimate_size().
539543 *
540- * While block oriented, it shouldn't be too hardto for an AM that
544+ * While block oriented, it shouldn't be too hard for an AM that doesn't
541545 * doesn't internally use blocks to convert into a usable representation.
542546 */
543547void (* relation_estimate_size ) (Relation rel ,int32 * attr_widths ,
@@ -553,7 +557,7 @@ typedef struct TableAmRoutine
553557/*
554558 * Prepare to fetch / check / return tuples from `tbmres->blockno` as part
555559 * of a bitmap table scan. `scan` was started via table_beginscan_bm().
556- * Return false if there's no tuples to be found on the page, true
560+ * Return false if there are no tuples to be found on the page, true
557561 * otherwise.
558562 *
559563 * This will typically read and pin the target block, and do the necessary
@@ -617,8 +621,8 @@ typedef struct TableAmRoutine
617621 * Note that it's not acceptable to hold deadlock prone resources such as
618622 * lwlocks until scan_sample_next_tuple() has exhausted the tuples on the
619623 * block - the tuple is likely to be returned to an upper query node, and
620- * the next call could be off a long while. Holding buffer pinsetc is
621- * obviously OK.
624+ * the next call could be off a long while. Holding buffer pinsand such
625+ *is obviously OK.
622626 *
623627 * Currently it is required to implement this interface, as there's no
624628 * alternative way (contrary e.g. to bitmap scans) to implement sample
@@ -707,7 +711,6 @@ table_beginscan_strat(Relation rel, Snapshot snapshot,
707711 false, false, false);
708712}
709713
710-
711714/*
712715 * table_beginscan_bm is an alternative entry point for setting up a
713716 * TableScanDesc for a bitmap heap scan. Although that scan technology is
@@ -762,7 +765,6 @@ table_endscan(TableScanDesc scan)
762765scan -> rs_rd -> rd_tableam -> scan_end (scan );
763766}
764767
765-
766768/*
767769 * Restart a relation scan.
768770 */
@@ -795,7 +797,6 @@ table_rescan_set_params(TableScanDesc scan, struct ScanKeyData *key,
795797 */
796798extern void table_scan_update_snapshot (TableScanDesc scan ,Snapshot snapshot );
797799
798-
799800/*
800801 * Return next tuple from `scan`, store in slot.
801802 */
@@ -833,7 +834,7 @@ extern void table_parallelscan_initialize(Relation rel,
833834 * table_parallelscan_initialize(), for the same relation. The initialization
834835 * does not need to have happened in this backend.
835836 *
836- * Caller must hold a suitable lock on thecorrect relation.
837+ * Caller must hold a suitable lock on the relation.
837838 */
838839extern TableScanDesc table_beginscan_parallel (Relation rel ,
839840ParallelTableScanDesc pscan );
@@ -904,7 +905,7 @@ table_index_fetch_end(struct IndexFetchTableData *scan)
904905 * The difference between this function and table_fetch_row_version is that
905906 * this function returns the currently visible version of a row if the AM
906907 * supports storing multiple row versions reachable via a single index entry
907- * (like heap's HOT). Whereas table_fetch_row_version only evaluates the the
908+ * (like heap's HOT). Whereas table_fetch_row_version only evaluates the
908909 * tuple exactly at `tid`. Outside of index entry ->table tuple lookups,
909910 * table_fetch_row_version is what's usually needed.
910911 */
@@ -940,7 +941,7 @@ extern bool table_index_fetch_tuple_check(Relation rel,
940941
941942
942943/*
943- * Fetch tuple at `tid` into `slot, after doing a visibility test according to
944+ * Fetch tuple at `tid` into `slot` , after doing a visibility test according to
944945 * `snapshot`. If a tuple was found and passed the visibility test, returns
945946 * true, false otherwise.
946947 *
@@ -1009,8 +1010,8 @@ table_compute_xid_horizon_for_tuples(Relation rel,
10091010 * behaviour of the AM. Several options might be ignored by AMs not supporting
10101011 * them.
10111012 *
1012- * If the TABLE_INSERT_SKIP_WAL option is specified, the new tuplewill not
1013- *necessarily logged to WAL, even for a non-temp relation. It is the AMs
1013+ * If the TABLE_INSERT_SKIP_WAL option is specified, the new tupledoesn't
1014+ *need to be logged to WAL, even for a non-temp relation. It is the AMs
10141015 * choice whether this optimization is supported.
10151016 *
10161017 * If the TABLE_INSERT_SKIP_FSM option is specified, AMs are free to not reuse
@@ -1030,7 +1031,7 @@ table_compute_xid_horizon_for_tuples(Relation rel,
10301031 * relation.
10311032 *
10321033 * Note that most of these options will be applied when inserting into the
1033- * heap's TOAST table, too, if the tuple requires any out-of-line data
1034+ * heap's TOAST table, too, if the tuple requires any out-of-line data.
10341035 *
10351036 *
10361037 * The BulkInsertState object (if any; bistate can be NULL for default
@@ -1082,7 +1083,7 @@ table_complete_speculative(Relation rel, TupleTableSlot *slot,
10821083}
10831084
10841085/*
1085- * Insert multipletuple into a table.
1086+ * Insert multipletuples into a table.
10861087 *
10871088 * This is like table_insert(), but inserts multiple tuples in one
10881089 * operation. That's often faster than calling table_insert() in a loop,
@@ -1121,10 +1122,9 @@ table_multi_insert(Relation rel, TupleTableSlot **slots, int nslots,
11211122 *changingPart - true iff the tuple is being moved to another partition
11221123 *table due to an update of the partition key. Otherwise, false.
11231124 *
1124- * Normal, successful return value is TM_Ok, which
1125- * actually means we did delete it. Failure return codes are
1126- * TM_SelfModified, TM_Updated, or TM_BeingModified
1127- * (the last only possible if wait == false).
1125+ * Normal, successful return value is TM_Ok, which means we did actually
1126+ * delete it. Failure return codes are TM_SelfModified, TM_Updated, and
1127+ * TM_BeingModified (the last only possible if wait == false).
11281128 *
11291129 * In the failure cases, the routine fills *tmfd with the tuple's t_ctid,
11301130 * t_xmax, and, if possible, and, if possible, t_cmax. See comments for
@@ -1160,10 +1160,9 @@ table_delete(Relation rel, ItemPointer tid, CommandId cid,
11601160 * update_indexes - in success cases this is set to true if new index entries
11611161 *are required for this tuple
11621162 *
1163- * Normal, successful return value is TM_Ok, which
1164- * actually means we *did* update it. Failure return codes are
1165- * TM_SelfModified, TM_Updated, or TM_BeingModified
1166- * (the last only possible if wait == false).
1163+ * Normal, successful return value is TM_Ok, which means we did actually
1164+ * update it. Failure return codes are TM_SelfModified, TM_Updated, and
1165+ * TM_BeingModified (the last only possible if wait == false).
11671166 *
11681167 * On success, the slot's tts_tid and tts_tableOid are updated to match the new
11691168 * stored tuple; in particular, slot->tts_tid is set to the TID where the
@@ -1201,8 +1200,8 @@ table_update(Relation rel, ItemPointer otid, TupleTableSlot *slot,
12011200 *flags:
12021201 *If TUPLE_LOCK_FLAG_LOCK_UPDATE_IN_PROGRESS, follow the update chain to
12031202 *also lock descendant tuples if lock modes don't conflict.
1204- *If TUPLE_LOCK_FLAG_FIND_LAST_VERSION, update chain and lock latest
1205- *version.
1203+ *If TUPLE_LOCK_FLAG_FIND_LAST_VERSION,follow the update chain and lock
1204+ *latest version.
12061205 *
12071206 * Output parameters:
12081207 **slot: contains the target tuple
@@ -1303,7 +1302,7 @@ table_relation_copy_data(Relation rel, RelFileNode newrnode)
13031302 * is copied in that index's order; if use_sort is false and OidIndex is
13041303 * InvalidOid, no sorting is performed.
13051304 *
1306- * OldestXmin, FreezeXid, MultiXactCutoffneed to currently valid values for
1305+ * OldestXmin, FreezeXid, MultiXactCutoffmust be currently valid values for
13071306 * the table.
13081307 *
13091308 * *num_tuples, *tups_vacuumed, *tups_recently_dead will contain statistics
@@ -1329,15 +1328,15 @@ table_relation_copy_for_cluster(Relation OldHeap, Relation NewHeap,
13291328}
13301329
13311330/*
1332- * Perform VACUUM on the relation. The VACUUM can be user
1331+ * Perform VACUUM on the relation. The VACUUM can be user- triggered or by
13331332 * autovacuum. The specific actions performed by the AM will depend heavily on
13341333 * the individual AM.
13351334
13361335 * On entry a transaction needs to already been established, and the
1337- *transaction is locked with a ShareUpdateExclusive lock.
1336+ *table is locked with a ShareUpdateExclusive lock.
13381337 *
13391338 * Note that neither VACUUM FULL (and CLUSTER), nor ANALYZE go through this
1340- * routine, even if (in the latter case), part of the same VACUUM command.
1339+ * routine, even if (for ANALYZE) it is part of the same VACUUM command.
13411340 */
13421341static inline void
13431342table_relation_vacuum (Relation rel ,struct VacuumParams * params ,
@@ -1363,7 +1362,7 @@ table_scan_analyze_next_block(TableScanDesc scan, BlockNumber blockno,
13631362}
13641363
13651364/*
1366- * Iterate over tuplestuples in the block selected with
1365+ * Iterate over tuples in the block selected with
13671366 * table_scan_analyze_next_block() (which needs to have returned true, and
13681367 * this routine may not have returned false for the same block before). If a
13691368 * tuple that's suitable for sampling is found, true is returned and a tuple
@@ -1383,7 +1382,7 @@ table_scan_analyze_next_tuple(TableScanDesc scan, TransactionId OldestXmin,
13831382}
13841383
13851384/*
1386- *table_index_build_range_scan - scan the table to find tuples to be indexed
1385+ *table_index_build_scan - scan the table to find tuples to be indexed
13871386 *
13881387 * This is called back from an access-method-specific index build procedure
13891388 * after the AM has done whatever setup it needs. The parent heap relation
@@ -1515,8 +1514,8 @@ table_relation_estimate_size(Relation rel, int32 *attr_widths,
15151514/*
15161515 * Prepare to fetch / check / return tuples from `tbmres->blockno` as part of
15171516 * a bitmap table scan. `scan` needs to have been started via
1518- * table_beginscan_bm(). Returns false if there's no tuples to be found on the
1519- * page, true otherwise.
1517+ * table_beginscan_bm(). Returns false if there are no tuples to be found on
1518+ *the page, true otherwise.
15201519 *
15211520 * Note, this is an optionally implemented function, therefore should only be
15221521 * used after verifying the presence (at plan time or such).