summary | shortlog | log | commit | commitdiff | tree
raw | patch | inline | side by side (parent: 122fa9f)
raw | patch | inline | side by side (parent: 122fa9f)
| author | Andres Freund <andres@anarazel.de> | |
| Mon, 8 Apr 2019 17:25:16 +0000 (10:25 -0700) | ||
| committer | Andres Freund <andres@anarazel.de> | |
| Mon, 8 Apr 2019 23:24:36 +0000 (16:24 -0700) |
Author: Heikki Linnakangas
Discussion: https://postgr.es/m/9a7fb9cc-2419-5db7-8840-ddc10c93f122@iki.fi
Discussion: https://postgr.es/m/9a7fb9cc-2419-5db7-8840-ddc10c93f122@iki.fi
| src/include/access/tableam.h | patch | blob | blame | history |
index 51398f35c01df67294ae8d0e93bccbbea54837aa..6fbfcb96c98c3785184af34314bc34a39c6136f4 100644 (file)
#define DEFAULT_TABLE_ACCESS_METHOD "heap"
+/* GUCs */
extern char *default_table_access_method;
extern bool synchronize_seqscans;
/*
- * Result codes for table_{update,delete,lock}_tuple, and for visibility
+ * Result codes for table_{update,delete,lock_tuple}, and for visibility
* routines inside table AMs.
*/
typedef enum TM_Result
/*
* The affected tuple is currently being modified by another session. This
- * will only be returned if (update/delete/lock)_tuple are instructed not
- * to wait.
+ * will only be returned if table_(update/delete/lock_tuple) are
+ * instructed not to wait.
*/
TM_BeingModified,
* When table_update, table_delete, or table_lock_tuple fail because the target
* tuple is already outdated, they fill in this struct to provide information
* to the caller about what happened.
+ *
* ctid is the target's ctid link: it is the same as the target's TID if the
* target was deleted, or the location of the replacement tuple if the target
* was updated.
+ *
* xmax is the outdating transaction's XID. If the caller wants to visit the
* replacement tuple, it must check that this matches before believing the
* replacement is really a match.
+ *
* cmax is the outdating command's CID, but only when the failure code is
* TM_SelfModified (i.e., something in the current transaction outdated the
* tuple); otherwise cmax is zero. (We make this restriction because
#define TABLE_INSERT_FROZEN 0x0004
#define TABLE_INSERT_NO_LOGICAL 0x0008
-/* flag bits fortable_lock_tuple */
+/* flag bits for table_lock_tuple */
/* Follow tuples whose update is in progress if lock modes don't conflict */
#define TUPLE_LOCK_FLAG_LOCK_UPDATE_IN_PROGRESS (1 << 0)
-/* Follow update chain and lock lastest version of tuple */
+/* Follow update chain and lock latest version of tuple */
#define TUPLE_LOCK_FLAG_FIND_LAST_VERSION (1 << 1)
* server-lifetime manner, typically as a static const struct, which then gets
* returned by FormData_pg_am.amhandler.
*
- * I most cases it's not appropriate to directly call the callbacks directly,
- * instead use the table_* wrapper functions.
+ * In most cases it's not appropriate to call the callbacks directly, use the
+ * table_* wrapper functions instead.
*
* GetTableAmRoutine() asserts that required callbacks are filled in, remember
* to update when adding a callback.
void (*scan_end) (TableScanDesc scan);
/*
- * Restart relation scan. If set_params is set to true, allow{strat,
+ * Restart relation scan. If set_params is set to true, allow_{strat,
* sync, pagemode} (see scan_begin) changes should be taken into account.
*/
void (*scan_rescan) (TableScanDesc scan, struct ScanKeyData *key,
/*
* Initialize ParallelTableScanDesc for a parallel scan of this relation.
- * pscan will be sized according to parallelscan_estimate() for the same
+ * `pscan` will be sized according to parallelscan_estimate() for the same
* relation.
*/
Size (*parallelscan_initialize) (Relation rel,
/*
* Prepare to fetch tuples from the relation, as needed when fetching
- * tuples for an index scan. The callback has to return a
+ * tuples for an index scan. The callback has to return an
* IndexFetchTableData, which the AM will typically embed in a larger
* structure with additional information.
*
* test, return true, false otherwise.
*
* Note that AMs that do not necessarily update indexes when indexed
- * columns do not change, need to return the current/correct version of a
- * tuple as appropriate, even if the tid points to an older version of the
- * tuple.
+ * columns do not change, need to return the current/correct version of
+ * the tuple that is visible to the snapshot, even if the tid points to an
+ * older version of the tuple.
*
* *call_again is false on the first call to index_fetch_tuple for a tid.
* If there potentially is another tuple matching the tid, *call_again
* needs be set to true by index_fetch_tuple, signalling to the caller
* that index_fetch_tuple should be called again for the same tid.
*
- * *all_dead, if all_dead is not NULL, should be set to true if by
+ * *all_dead, if all_dead is not NULL, should be set to true by
* index_fetch_tuple iff it is guaranteed that no backend needs to see
* that tuple. Index AMs can use that do avoid returning that tid in
* future searches.
TupleTableSlot *slot,
bool *call_again, bool *all_dead);
+
/* ------------------------------------------------------------------------
* Callbacks for non-modifying operations on individual tuples
* ------------------------------------------------------------------------
*/
-
/*
- * Fetch tuple at `tid` into `slot, after doing a visibility test
+ * Fetch tuple at `tid` into `slot`, after doing a visibility test
* according to `snapshot`. If a tuple was found and passed the visibility
* test, returns true, false otherwise.
*/
/*
* Perform operations necessary to complete insertions made via
* tuple_insert and multi_insert with a BulkInsertState specified. This
- * e.g. may e.g. used to flush the relation when inserting with
- * TABLE_INSERT_SKIP_WAL specified.
+ * may for example be used to flush the relation, when the
+ * TABLE_INSERT_SKIP_WAL option was used.
*
* Typically callers of tuple_insert and multi_insert will just pass all
- * the flags the apply to them, and each AM has to decide which of them
- * make sense for it, and then only take actions in finish_bulk_insert
- * that make sense for a specific AM.
+ * the flags that apply to them, and each AM has to decide which of them
+ * make sense for it, and then only take actions in finish_bulk_insert for
+ * those flags, and ignore others.
*
* Optional callback.
*/
* This callback needs to create a new relation filenode for `rel`, with
* appropriate durability behaviour for `persistence`.
*
- * On output *freezeXid, *minmulti should be set to the values appropriate
- * for pg_class.{relfrozenxid, relminmxid} have to be set to. For AMs that
- * don't need those fields to be filled they can be set to
- * InvalidTransactionId, InvalidMultiXactId respectively.
+ * On output *freezeXid, *minmulti must be set to the values appropriate
+ * for pg_class.{relfrozenxid, relminmxid}. For AMs that don't need those
+ * fields to be filled they can be set to InvalidTransactionId and
+ * InvalidMultiXactId, respectively.
*
* See also table_relation_set_new_filenode().
*/
* locked with a ShareUpdateExclusive lock.
*
* Note that neither VACUUM FULL (and CLUSTER), nor ANALYZE go through
- * this routine, even if (in the latter case), part of the same VACUUM
+ * this routine, even if (for ANALYZE) it is part of the same VACUUM
* command.
*
* There probably, in the future, needs to be a separate callback to
* sampling, e.g. because it's a metapage that could never contain tuples.
*
* XXX: This obviously is primarily suited for block-based AMs. It's not
- * clear what a good interface for non block based AMs would be, so don't
- * try to invent one yet.
+ * clear what a good interface for non block based AMs would be, so there
+ * isn't one yet.
*/
bool (*scan_analyze_next_block) (TableScanDesc scan,
BlockNumber blockno,
/*
* See table_relation_estimate_size().
*
- * While block oriented, it shouldn't be too hard to for an AM that
+ * While block oriented, it shouldn't be too hard for an AM that doesn't
* doesn't internally use blocks to convert into a usable representation.
*/
void (*relation_estimate_size) (Relation rel, int32 *attr_widths,
/*
* Prepare to fetch / check / return tuples from `tbmres->blockno` as part
* of a bitmap table scan. `scan` was started via table_beginscan_bm().
- * Return false if there's no tuples to be found on the page, true
+ * Return false if there are no tuples to be found on the page, true
* otherwise.
*
* This will typically read and pin the target block, and do the necessary
* Note that it's not acceptable to hold deadlock prone resources such as
* lwlocks until scan_sample_next_tuple() has exhausted the tuples on the
* block - the tuple is likely to be returned to an upper query node, and
- * the next call could be off a long while. Holding buffer pins etc is
- * obviously OK.
+ * the next call could be off a long while. Holding buffer pins and such
+ * is obviously OK.
*
* Currently it is required to implement this interface, as there's no
* alternative way (contrary e.g. to bitmap scans) to implement sample
false, false, false);
}
-
/*
* table_beginscan_bm is an alternative entry point for setting up a
* TableScanDesc for a bitmap heap scan. Although that scan technology is
scan->rs_rd->rd_tableam->scan_end(scan);
}
-
/*
* Restart a relation scan.
*/
*/
extern void table_scan_update_snapshot(TableScanDesc scan, Snapshot snapshot);
-
/*
* Return next tuple from `scan`, store in slot.
*/
* table_parallelscan_initialize(), for the same relation. The initialization
* does not need to have happened in this backend.
*
- * Caller must hold a suitable lock on the correct relation.
+ * Caller must hold a suitable lock on the relation.
*/
extern TableScanDesc table_beginscan_parallel(Relation rel,
ParallelTableScanDesc pscan);
* The difference between this function and table_fetch_row_version is that
* this function returns the currently visible version of a row if the AM
* supports storing multiple row versions reachable via a single index entry
- * (like heap's HOT). Whereas table_fetch_row_version only evaluates the the
+ * (like heap's HOT). Whereas table_fetch_row_version only evaluates the
* tuple exactly at `tid`. Outside of index entry ->table tuple lookups,
* table_fetch_row_version is what's usually needed.
*/
/*
- * Fetch tuple at `tid` into `slot, after doing a visibility test according to
+ * Fetch tuple at `tid` into `slot`, after doing a visibility test according to
* `snapshot`. If a tuple was found and passed the visibility test, returns
* true, false otherwise.
*
* behaviour of the AM. Several options might be ignored by AMs not supporting
* them.
*
- * If the TABLE_INSERT_SKIP_WAL option is specified, the new tuple will not
- * necessarily logged to WAL, even for a non-temp relation. It is the AMs
+ * If the TABLE_INSERT_SKIP_WAL option is specified, the new tuple doesn't
+ * need to be logged to WAL, even for a non-temp relation. It is the AMs
* choice whether this optimization is supported.
*
* If the TABLE_INSERT_SKIP_FSM option is specified, AMs are free to not reuse
* relation.
*
* Note that most of these options will be applied when inserting into the
- * heap's TOAST table, too, if the tuple requires any out-of-line data
+ * heap's TOAST table, too, if the tuple requires any out-of-line data.
*
*
* The BulkInsertState object (if any; bistate can be NULL for default
}
/*
- * Insert multiple tuple into a table.
+ * Insert multiple tuples into a table.
*
* This is like table_insert(), but inserts multiple tuples in one
* operation. That's often faster than calling table_insert() in a loop,
* changingPart - true iff the tuple is being moved to another partition
* table due to an update of the partition key. Otherwise, false.
*
- * Normal, successful return value is TM_Ok, which
- * actually means we did delete it. Failure return codes are
- * TM_SelfModified, TM_Updated, or TM_BeingModified
- * (the last only possible if wait == false).
+ * Normal, successful return value is TM_Ok, which means we did actually
+ * delete it. Failure return codes are TM_SelfModified, TM_Updated, and
+ * TM_BeingModified (the last only possible if wait == false).
*
* In the failure cases, the routine fills *tmfd with the tuple's t_ctid,
* t_xmax, and, if possible, and, if possible, t_cmax. See comments for
* update_indexes - in success cases this is set to true if new index entries
* are required for this tuple
*
- * Normal, successful return value is TM_Ok, which
- * actually means we *did* update it. Failure return codes are
- * TM_SelfModified, TM_Updated, or TM_BeingModified
- * (the last only possible if wait == false).
+ * Normal, successful return value is TM_Ok, which means we did actually
+ * update it. Failure return codes are TM_SelfModified, TM_Updated, and
+ * TM_BeingModified (the last only possible if wait == false).
*
* On success, the slot's tts_tid and tts_tableOid are updated to match the new
* stored tuple; in particular, slot->tts_tid is set to the TID where the
* flags:
* If TUPLE_LOCK_FLAG_LOCK_UPDATE_IN_PROGRESS, follow the update chain to
* also lock descendant tuples if lock modes don't conflict.
- * If TUPLE_LOCK_FLAG_FIND_LAST_VERSION, update chain and lock latest
- * version.
+ * If TUPLE_LOCK_FLAG_FIND_LAST_VERSION, follow the update chain and lock
+ * latest version.
*
* Output parameters:
* *slot: contains the target tuple
* is copied in that index's order; if use_sort is false and OidIndex is
* InvalidOid, no sorting is performed.
*
- * OldestXmin, FreezeXid, MultiXactCutoff need to currently valid values for
+ * OldestXmin, FreezeXid, MultiXactCutoff must be currently valid values for
* the table.
*
* *num_tuples, *tups_vacuumed, *tups_recently_dead will contain statistics
}
/*
- * Perform VACUUM on the relation. The VACUUM can be user triggered or by
+ * Perform VACUUM on the relation. The VACUUM can be user-triggered or by
* autovacuum. The specific actions performed by the AM will depend heavily on
* the individual AM.
* On entry a transaction needs to already been established, and the
- * transaction is locked with a ShareUpdateExclusive lock.
+ * table is locked with a ShareUpdateExclusive lock.
*
* Note that neither VACUUM FULL (and CLUSTER), nor ANALYZE go through this
- * routine, even if (in the latter case), part of the same VACUUM command.
+ * routine, even if (for ANALYZE) it is part of the same VACUUM command.
*/
static inline void
table_relation_vacuum(Relation rel, struct VacuumParams *params,
}
/*
- * Iterate over tuples tuples in the block selected with
+ * Iterate over tuples in the block selected with
* table_scan_analyze_next_block() (which needs to have returned true, and
* this routine may not have returned false for the same block before). If a
* tuple that's suitable for sampling is found, true is returned and a tuple
}
/*
- * table_index_build_range_scan - scan the table to find tuples to be indexed
+ * table_index_build_scan - scan the table to find tuples to be indexed
*
* This is called back from an access-method-specific index build procedure
* after the AM has done whatever setup it needs. The parent heap relation
/*
* Prepare to fetch / check / return tuples from `tbmres->blockno` as part of
* a bitmap table scan. `scan` needs to have been started via
- * table_beginscan_bm(). Returns false if there's no tuples to be found on the
- * page, true otherwise.
+ * table_beginscan_bm(). Returns false if there are no tuples to be found on
+ * the page, true otherwise.
*
* Note, this is an optionally implemented function, therefore should only be
* used after verifying the presence (at plan time or such).