Hi, On 2019-01-10 15:58:41 -0800, Andres Freund wrote: > A number of postgres files have sections like heapam's > > * INTERFACE ROUTINES > ... > They're often out-of-date, and I personally never found them to be > useful. A few people, including yours truly, have been removing a few > here and there when overhauling a subsystem to avoid having to update > and then adjust them. > > I think it might be a good idea to just do that for all at once. Having > to consider separately committing a removal, updating them without > fixing preexisting issues, or just leaving them outdated on a regular > basis imo is a usless distraction.
As the reaction was positive, here's a first draft of a commit removing them. A few comments: - I left two INTERFACE ROUTINES blocks intact, because they actually add somewhat useful information. Namely fd.c's, which actually seems useful, and predicate.c's about which I'm less sure. - I tried to move all comments about the routines in the INTERFACE section to the functions if they didn't have a roughly equivalent comment. Even if the comment wasn't that useful. Particularly just about all the function comments in executor/node*.c files are useless, but I thought that's something best to be cleaned up separately. - After removing the INTERFACE ROUTINES blocks a number of executor files had a separate comment block with just a NOTES section. I merged these with the file header comment blocks, and indented them to match. I think this is better, but I'm only like 60% convinced of that. Comments? I'll revisit this patch on Monday or so, make another pass through it, and push it then. Greetings, Andres Freund
>From 6979b669d3599de6c9aafa3588b34f80b6906ad5 Mon Sep 17 00:00:00 2001 From: Andres Freund <and...@anarazel.de> Date: Fri, 11 Jan 2019 17:10:45 -0800 Subject: [PATCH] Remove most INTERFACE ROUTINES comments. They frequently get out of date, and most of the time don't add anything useful. Author: Andres Freund Discussion: https://postgr.es/m/20190110235841.7wqchihf4kvo2...@alap3.anarazel.de --- src/backend/access/heap/heapam.c | 18 --- src/backend/access/heap/syncscan.c | 4 - src/backend/access/heap/tuptoaster.c | 11 -- src/backend/access/heap/visibilitymap.c | 9 -- src/backend/access/index/indexam.c | 24 ---- src/backend/catalog/heap.c | 5 - src/backend/catalog/index.c | 11 +- src/backend/executor/execMain.c | 28 +---- src/backend/executor/execUtils.c | 34 +----- src/backend/executor/nodeAppend.c | 49 ++++---- src/backend/executor/nodeBitmapAnd.c | 27 ++--- src/backend/executor/nodeBitmapHeapscan.c | 15 +-- src/backend/executor/nodeBitmapIndexscan.c | 12 +- src/backend/executor/nodeBitmapOr.c | 27 ++--- src/backend/executor/nodeForeignscan.c | 11 +- src/backend/executor/nodeFunctionscan.c | 11 +- src/backend/executor/nodeHash.c | 6 - src/backend/executor/nodeIndexonlyscan.c | 24 ++-- src/backend/executor/nodeIndexscan.c | 24 ++-- src/backend/executor/nodeLimit.c | 6 - src/backend/executor/nodeLockRows.c | 8 +- src/backend/executor/nodeMaterial.c | 12 +- src/backend/executor/nodeMergeAppend.c | 45 ++++---- src/backend/executor/nodeMergejoin.c | 124 ++++++++++----------- src/backend/executor/nodeModifyTable.c | 45 ++++---- src/backend/executor/nodeNestloop.c | 8 +- src/backend/executor/nodeSeqscan.c | 14 +-- src/backend/executor/nodeSubplan.c | 6 +- src/backend/executor/nodeSubqueryscan.c | 12 +- src/backend/executor/nodeTableFuncscan.c | 13 +-- src/backend/executor/nodeTidscan.c | 11 +- src/backend/executor/nodeUnique.c | 15 +-- src/backend/executor/nodeValuesscan.c | 13 +-- src/backend/libpq/pqcomm.c | 31 ------ src/backend/libpq/pqformat.c | 44 +------- src/backend/tcop/dest.c | 17 +-- src/backend/utils/cache/relcache.c | 21 ++-- src/interfaces/libpq/fe-auth.c | 8 -- 38 files changed, 247 insertions(+), 556 deletions(-) diff --git a/src/backend/access/heap/heapam.c b/src/backend/access/heap/heapam.c index 2c4a1453576..be3355e12a2 100644 --- a/src/backend/access/heap/heapam.c +++ b/src/backend/access/heap/heapam.c @@ -11,24 +11,6 @@ * src/backend/access/heap/heapam.c * * - * INTERFACE ROUTINES - * relation_open - open any relation by relation OID - * relation_openrv - open any relation specified by a RangeVar - * relation_close - close any relation - * heap_open - open a heap relation by relation OID - * heap_openrv - open a heap relation specified by a RangeVar - * heap_close - (now just a macro for relation_close) - * heap_beginscan - begin relation scan - * heap_rescan - restart a relation scan - * heap_endscan - end relation scan - * heap_getnext - retrieve next tuple in scan - * heap_fetch - retrieve tuple with given tid - * heap_insert - insert tuple into a relation - * heap_multi_insert - insert multiple tuples into a relation - * heap_delete - delete a tuple from a relation - * heap_update - replace a tuple in a relation with another tuple - * heap_sync - sync heap, for when no WAL has been written - * * NOTES * This file contains the heap_ routines which implement * the POSTGRES heap access method used for all POSTGRES diff --git a/src/backend/access/heap/syncscan.c b/src/backend/access/heap/syncscan.c index c0a45dc75a9..0eeb05dbeb4 100644 --- a/src/backend/access/heap/syncscan.c +++ b/src/backend/access/heap/syncscan.c @@ -31,10 +31,6 @@ * scan position. The whole mechanism is only applied for tables exceeding * a threshold size (but that is not the concern of this module). * - * INTERFACE ROUTINES - * ss_get_location - return current scan location of a relation - * ss_report_location - update current scan location - * * * Portions Copyright (c) 1996-2019, PostgreSQL Global Development Group * Portions Copyright (c) 1994, Regents of the University of California diff --git a/src/backend/access/heap/tuptoaster.c b/src/backend/access/heap/tuptoaster.c index 0ffc5392a6d..4a1bbe88e69 100644 --- a/src/backend/access/heap/tuptoaster.c +++ b/src/backend/access/heap/tuptoaster.c @@ -11,17 +11,6 @@ * src/backend/access/heap/tuptoaster.c * * - * INTERFACE ROUTINES - * toast_insert_or_update - - * Try to make a given tuple fit into one page by compressing - * or moving off attributes - * - * toast_delete - - * Reclaim toast storage when a tuple is deleted - * - * heap_tuple_untoast_attr - - * Fetch back a given value from the "secondary" relation - * *------------------------------------------------------------------------- */ diff --git a/src/backend/access/heap/visibilitymap.c b/src/backend/access/heap/visibilitymap.c index 931ae81fd6d..6f5e7d8c42a 100644 --- a/src/backend/access/heap/visibilitymap.c +++ b/src/backend/access/heap/visibilitymap.c @@ -10,15 +10,6 @@ * IDENTIFICATION * src/backend/access/heap/visibilitymap.c * - * INTERFACE ROUTINES - * visibilitymap_clear - clear bits for one page in the visibility map - * visibilitymap_pin - pin a map page for setting a bit - * visibilitymap_pin_ok - check whether correct map page is already pinned - * visibilitymap_set - set a bit in a previously pinned page - * visibilitymap_get_status - get status of bits - * visibilitymap_count - count number of bits set in visibility map - * visibilitymap_truncate - truncate the visibility map - * * NOTES * * The visibility map is a bitmap with two bits (all-visible and all-frozen) diff --git a/src/backend/access/index/indexam.c b/src/backend/access/index/indexam.c index 4a0238f9edc..babde733a7b 100644 --- a/src/backend/access/index/indexam.c +++ b/src/backend/access/index/indexam.c @@ -10,30 +10,6 @@ * IDENTIFICATION * src/backend/access/index/indexam.c * - * INTERFACE ROUTINES - * index_open - open an index relation by relation OID - * index_close - close an index relation - * index_beginscan - start a scan of an index with amgettuple - * index_beginscan_bitmap - start a scan of an index with amgetbitmap - * index_rescan - restart a scan of an index - * index_endscan - end a scan - * index_insert - insert an index tuple into a relation - * index_markpos - mark a scan position - * index_restrpos - restore a scan position - * index_parallelscan_estimate - estimate shared memory for parallel scan - * index_parallelscan_initialize - initialize parallel scan - * index_parallelrescan - (re)start a parallel scan of an index - * index_beginscan_parallel - join parallel index scan - * index_getnext_tid - get the next TID from a scan - * index_fetch_heap - get the scan's next heap tuple - * index_getnext - get the next heap tuple from a scan - * index_getbitmap - get all tuples from a scan - * index_bulk_delete - bulk deletion of index tuples - * index_vacuum_cleanup - post-deletion cleanup of an index - * index_can_return - does index support index-only scans? - * index_getprocid - get a support procedure OID - * index_getprocinfo - get a support procedure's lookup info - * * NOTES * This file contains the index_ routines which used * to be a scattered collection of stuff in access/genam. diff --git a/src/backend/catalog/heap.c b/src/backend/catalog/heap.c index 472285d3913..05aeccfe725 100644 --- a/src/backend/catalog/heap.c +++ b/src/backend/catalog/heap.c @@ -11,11 +11,6 @@ * src/backend/catalog/heap.c * * - * INTERFACE ROUTINES - * heap_create() - Create an uncataloged heap relation - * heap_create_with_catalog() - Create a cataloged relation - * heap_drop_with_catalog() - Removes named relation from catalogs - * * NOTES * this code taken from access/heap/create.c, which contains * the old heap_create_with_catalog, amcreate, and amdestroy. diff --git a/src/backend/catalog/index.c b/src/backend/catalog/index.c index c91408046af..7447e46b51f 100644 --- a/src/backend/catalog/index.c +++ b/src/backend/catalog/index.c @@ -10,13 +10,6 @@ * IDENTIFICATION * src/backend/catalog/index.c * - * - * INTERFACE ROUTINES - * index_create() - Create a cataloged index relation - * index_drop() - Removes index relation from catalogs - * BuildIndexInfo() - Prepare to insert index tuples - * FormIndexDatum() - Construct datum vector for one index tuple - * *------------------------------------------------------------------------- */ #include "postgres.h" @@ -674,6 +667,7 @@ UpdateIndexRelation(Oid indexoid, /* * index_create + * Create a cataloged index relation * * heapRelation: table to build index on (suitably locked by caller) * indexRelationName: what it say @@ -1439,7 +1433,8 @@ index_constraint_create(Relation heapRelation, } /* - * index_drop + * index_drop + * Removes index relation from catalogs * * NOTE: this routine should now only be called through performDeletion(), * else associated dependencies won't be cleaned up. diff --git a/src/backend/executor/execMain.c b/src/backend/executor/execMain.c index 26e41902f3a..629d5d4eea4 100644 --- a/src/backend/executor/execMain.c +++ b/src/backend/executor/execMain.c @@ -3,29 +3,6 @@ * execMain.c * top level executor interface routines * - * INTERFACE ROUTINES - * ExecutorStart() - * ExecutorRun() - * ExecutorFinish() - * ExecutorEnd() - * - * These four procedures are the external interface to the executor. - * In each case, the query descriptor is required as an argument. - * - * ExecutorStart must be called at the beginning of execution of any - * query plan and ExecutorEnd must always be called at the end of - * execution of a plan (unless it is aborted due to error). - * - * ExecutorRun accepts direction and count arguments that specify whether - * the plan is to be executed forwards, backwards, and for how many tuples. - * In some cases ExecutorRun may be called multiple times to process all - * the tuples for a plan. It is also acceptable to stop short of executing - * the whole plan (but only if it is a SELECT). - * - * ExecutorFinish must be called after the final ExecutorRun call and - * before ExecutorEnd. This can be omitted only in case of EXPLAIN, - * which should also omit ExecutorRun. - * * Portions Copyright (c) 1996-2019, PostgreSQL Global Development Group * Portions Copyright (c) 1994, Regents of the University of California * @@ -33,6 +10,11 @@ * IDENTIFICATION * src/backend/executor/execMain.c * + * NOTES + * This file contains the external interface routines to the executor. See + * the comments above ExecutorStart(), ExecutorRun(), ExecutorFinish(), + * ExecutorEnd() for description of the interface. + * *------------------------------------------------------------------------- */ #include "postgres.h" diff --git a/src/backend/executor/execUtils.c b/src/backend/executor/execUtils.c index 24ab43d5e5c..cb8515cd077 100644 --- a/src/backend/executor/execUtils.c +++ b/src/backend/executor/execUtils.c @@ -10,38 +10,12 @@ * IDENTIFICATION * src/backend/executor/execUtils.c * + * NOTES + * This file has traditionally been the place to stick misc. + * executor support stuff that doesn't really go anyplace else. + * *------------------------------------------------------------------------- */ -/* - * INTERFACE ROUTINES - * CreateExecutorState Create/delete executor working state - * FreeExecutorState - * CreateExprContext - * CreateStandaloneExprContext - * FreeExprContext - * ReScanExprContext - * - * ExecAssignExprContext Common code for plan node init routines. - * etc - * - * ExecOpenScanRelation Common code for scan node init routines. - * - * ExecInitRangeTable Set up executor's range-table-related data. - * - * ExecGetRangeTableRelation Fetch Relation for a rangetable entry. - * - * executor_errposition Report syntactic position of an error. - * - * RegisterExprContextCallback Register function shutdown callback - * UnregisterExprContextCallback Deregister function shutdown callback - * - * GetAttributeByName Runtime extraction of columns from tuples. - * GetAttributeByNum - * - * NOTES - * This file has traditionally been the place to stick misc. - * executor support stuff that doesn't really go anyplace else. - */ #include "postgres.h" diff --git a/src/backend/executor/nodeAppend.c b/src/backend/executor/nodeAppend.c index f3be2429dbe..1308a26a2d7 100644 --- a/src/backend/executor/nodeAppend.c +++ b/src/backend/executor/nodeAppend.c @@ -10,24 +10,16 @@ * IDENTIFICATION * src/backend/executor/nodeAppend.c * - *------------------------------------------------------------------------- - */ -/* INTERFACE ROUTINES - * ExecInitAppend - initialize the append node - * ExecAppend - retrieve the next tuple from the node - * ExecEndAppend - shut down the append node - * ExecReScanAppend - rescan the append node + * NOTES + * Each append node contains a list of one or more subplans which + * must be iteratively processed (forwards or backwards). + * Tuples are retrieved by executing the 'whichplan'th subplan + * until the subplan stops returning tuples, at which point that + * plan is shut down and the next started up. * - * NOTES - * Each append node contains a list of one or more subplans which - * must be iteratively processed (forwards or backwards). - * Tuples are retrieved by executing the 'whichplan'th subplan - * until the subplan stops returning tuples, at which point that - * plan is shut down and the next started up. - * - * Append nodes don't make use of their left and right - * subtrees, rather they maintain a list of subplans so - * a typical append node looks like this in the plan tree: + * Append nodes don't make use of their left and right + * subtrees, rather they maintain a list of subplans so + * a typical append node looks like this in the plan tree: * * ... * / @@ -36,16 +28,16 @@ * nil nil ... ... ... * subplans * - * Append nodes are currently used for unions, and to support - * inheritance queries, where several relations need to be scanned. - * For example, in our standard person/student/employee/student-emp - * example, where student and employee inherit from person - * and student-emp inherits from student and employee, the - * query: + * Append nodes are currently used for unions, and to support + * inheritance queries, where several relations need to be scanned. + * For example, in our standard person/student/employee/student-emp + * example, where student and employee inherit from person + * and student-emp inherits from student and employee, the + * query: * - * select name from person + * select name from person * - * generates the plan: + * generates the plan: * * | * Append -------+-------+--------+--------+ @@ -53,6 +45,7 @@ * nil nil Scan Scan Scan Scan * | | | | * person employee student student-emp + *------------------------------------------------------------------------- */ #include "postgres.h" @@ -335,6 +328,12 @@ ExecEndAppend(AppendState *node) ExecEndNode(appendplans[i]); } +/* ---------------------------------------------------------------- + * ExecReScanAppend + * + * Rescan the append node. + * ---------------------------------------------------------------- + */ void ExecReScanAppend(AppendState *node) { diff --git a/src/backend/executor/nodeBitmapAnd.c b/src/backend/executor/nodeBitmapAnd.c index 7ae6dd63fe7..37bc1fd6696 100644 --- a/src/backend/executor/nodeBitmapAnd.c +++ b/src/backend/executor/nodeBitmapAnd.c @@ -10,21 +10,14 @@ * IDENTIFICATION * src/backend/executor/nodeBitmapAnd.c * + * NOTES + * BitmapAnd nodes don't make use of their left and right + * subtrees, rather they maintain a list of subplans, + * much like Append nodes. The logic is much simpler than + * Append, however, since we needn't cope with forward/backward + * execution. *------------------------------------------------------------------------- */ -/* INTERFACE ROUTINES - * ExecInitBitmapAnd - initialize the BitmapAnd node - * MultiExecBitmapAnd - retrieve the result bitmap from the node - * ExecEndBitmapAnd - shut down the BitmapAnd node - * ExecReScanBitmapAnd - rescan the BitmapAnd node - * - * NOTES - * BitmapAnd nodes don't make use of their left and right - * subtrees, rather they maintain a list of subplans, - * much like Append nodes. The logic is much simpler than - * Append, however, since we needn't cope with forward/backward - * execution. - */ #include "postgres.h" @@ -104,6 +97,8 @@ ExecInitBitmapAnd(BitmapAnd *node, EState *estate, int eflags) /* ---------------------------------------------------------------- * MultiExecBitmapAnd + * + * Retrieve the result bitmap from the node. * ---------------------------------------------------------------- */ Node * @@ -197,6 +192,12 @@ ExecEndBitmapAnd(BitmapAndState *node) } } +/* ---------------------------------------------------------------- + * ExecReScanBitmapAnd + * + * Rescan the BitmapAnd node. + * ---------------------------------------------------------------- + */ void ExecReScanBitmapAnd(BitmapAndState *node) { diff --git a/src/backend/executor/nodeBitmapHeapscan.c b/src/backend/executor/nodeBitmapHeapscan.c index f8d70f25920..2aa30dc8834 100644 --- a/src/backend/executor/nodeBitmapHeapscan.c +++ b/src/backend/executor/nodeBitmapHeapscan.c @@ -25,14 +25,7 @@ * *------------------------------------------------------------------------- */ -/* - * INTERFACE ROUTINES - * ExecBitmapHeapScan scans a relation using bitmap info - * ExecBitmapHeapNext workhorse for above - * ExecInitBitmapHeapScan creates and initializes state info. - * ExecReScanBitmapHeapScan prepares to rescan the plan. - * ExecEndBitmapHeapScan releases all storage. - */ + #include "postgres.h" #include <math.h> @@ -67,7 +60,7 @@ static bool BitmapShouldInitializeSharedState( /* ---------------------------------------------------------------- - * BitmapHeapNext + * BitmapHeapNext - workhorse for ExecBitmapHeapScan * * Retrieve next tuple from the BitmapHeapScan node's currentRelation * ---------------------------------------------------------------- @@ -732,7 +725,7 @@ ExecBitmapHeapScan(PlanState *pstate) } /* ---------------------------------------------------------------- - * ExecReScanBitmapHeapScan(node) + * ExecReScanBitmapHeapScan(node) - prepares to rescan the plan. * ---------------------------------------------------------------- */ void @@ -779,7 +772,7 @@ ExecReScanBitmapHeapScan(BitmapHeapScanState *node) } /* ---------------------------------------------------------------- - * ExecEndBitmapHeapScan + * ExecEndBitmapHeapScan - releases all storage. * ---------------------------------------------------------------- */ void diff --git a/src/backend/executor/nodeBitmapIndexscan.c b/src/backend/executor/nodeBitmapIndexscan.c index 2526c3a2fc0..85f185e2dc8 100644 --- a/src/backend/executor/nodeBitmapIndexscan.c +++ b/src/backend/executor/nodeBitmapIndexscan.c @@ -12,13 +12,7 @@ * *------------------------------------------------------------------------- */ -/* - * INTERFACE ROUTINES - * MultiExecBitmapIndexScan scans a relation using index. - * ExecInitBitmapIndexScan creates and initializes state info. - * ExecReScanBitmapIndexScan prepares to rescan the plan. - * ExecEndBitmapIndexScan releases all storage. - */ + #include "postgres.h" #include "executor/execdebug.h" @@ -43,6 +37,8 @@ ExecBitmapIndexScan(PlanState *pstate) /* ---------------------------------------------------------------- * MultiExecBitmapIndexScan(node) + * + * Scans a relation using index. * ---------------------------------------------------------------- */ Node * @@ -169,6 +165,8 @@ ExecReScanBitmapIndexScan(BitmapIndexScanState *node) /* ---------------------------------------------------------------- * ExecEndBitmapIndexScan + * + * Releases all storage. * ---------------------------------------------------------------- */ void diff --git a/src/backend/executor/nodeBitmapOr.c b/src/backend/executor/nodeBitmapOr.c index 89d5a0c073a..74fbacd6373 100644 --- a/src/backend/executor/nodeBitmapOr.c +++ b/src/backend/executor/nodeBitmapOr.c @@ -10,21 +10,14 @@ * IDENTIFICATION * src/backend/executor/nodeBitmapOr.c * + * NOTES + * BitmapOr nodes don't make use of their left and right + * subtrees, rather they maintain a list of subplans, + * much like Append nodes. The logic is much simpler than + * Append, however, since we needn't cope with forward/backward + * execution. *------------------------------------------------------------------------- */ -/* INTERFACE ROUTINES - * ExecInitBitmapOr - initialize the BitmapOr node - * MultiExecBitmapOr - retrieve the result bitmap from the node - * ExecEndBitmapOr - shut down the BitmapOr node - * ExecReScanBitmapOr - rescan the BitmapOr node - * - * NOTES - * BitmapOr nodes don't make use of their left and right - * subtrees, rather they maintain a list of subplans, - * much like Append nodes. The logic is much simpler than - * Append, however, since we needn't cope with forward/backward - * execution. - */ #include "postgres.h" @@ -105,6 +98,8 @@ ExecInitBitmapOr(BitmapOr *node, EState *estate, int eflags) /* ---------------------------------------------------------------- * MultiExecBitmapOr + * + * Retrieve the result bitmap from the node. * ---------------------------------------------------------------- */ Node * @@ -215,6 +210,12 @@ ExecEndBitmapOr(BitmapOrState *node) } } +/* ---------------------------------------------------------------- + * ExecReScanBitmapOr + * + * Rescan the BitmapOr node. + * ---------------------------------------------------------------- + */ void ExecReScanBitmapOr(BitmapOrState *node) { diff --git a/src/backend/executor/nodeForeignscan.c b/src/backend/executor/nodeForeignscan.c index 40b6fbe891a..c5a9f1ebf27 100644 --- a/src/backend/executor/nodeForeignscan.c +++ b/src/backend/executor/nodeForeignscan.c @@ -12,14 +12,7 @@ * *------------------------------------------------------------------------- */ -/* - * INTERFACE ROUTINES - * - * ExecForeignScan scans a foreign table. - * ExecInitForeignScan creates and initializes state info. - * ExecReScanForeignScan rescans the foreign relation. - * ExecEndForeignScan releases any resources allocated. - */ + #include "postgres.h" #include "executor/executor.h" @@ -126,6 +119,8 @@ ExecForeignScan(PlanState *pstate) /* ---------------------------------------------------------------- * ExecInitForeignScan + * + * Creates and initializes state info. * ---------------------------------------------------------------- */ ForeignScanState * diff --git a/src/backend/executor/nodeFunctionscan.c b/src/backend/executor/nodeFunctionscan.c index 0370f2e2b70..083fdee39c3 100644 --- a/src/backend/executor/nodeFunctionscan.c +++ b/src/backend/executor/nodeFunctionscan.c @@ -12,14 +12,7 @@ * *------------------------------------------------------------------------- */ -/* - * INTERFACE ROUTINES - * ExecFunctionScan scans a function. - * ExecFunctionNext retrieve next tuple in sequential order. - * ExecInitFunctionScan creates and initializes a functionscan node. - * ExecEndFunctionScan releases any storage allocated. - * ExecReScanFunctionScan rescans the function - */ + #include "postgres.h" #include "catalog/pg_type.h" @@ -274,6 +267,8 @@ ExecFunctionScan(PlanState *pstate) /* ---------------------------------------------------------------- * ExecInitFunctionScan + * + * Creates and initializes a functionscan node. * ---------------------------------------------------------------- */ FunctionScanState * diff --git a/src/backend/executor/nodeHash.c b/src/backend/executor/nodeHash.c index 856daf6a7f3..8205ef1536e 100644 --- a/src/backend/executor/nodeHash.c +++ b/src/backend/executor/nodeHash.c @@ -14,12 +14,6 @@ * *------------------------------------------------------------------------- */ -/* - * INTERFACE ROUTINES - * MultiExecHash - generate an in-memory hash table of the relation - * ExecInitHash - initialize node and subnodes - * ExecEndHash - shutdown node and subnodes - */ #include "postgres.h" diff --git a/src/backend/executor/nodeIndexonlyscan.c b/src/backend/executor/nodeIndexonlyscan.c index c96a2c3ae9d..f181e3fd42e 100644 --- a/src/backend/executor/nodeIndexonlyscan.c +++ b/src/backend/executor/nodeIndexonlyscan.c @@ -12,22 +12,6 @@ * *------------------------------------------------------------------------- */ -/* - * INTERFACE ROUTINES - * ExecIndexOnlyScan scans an index - * IndexOnlyNext retrieve next tuple - * ExecInitIndexOnlyScan creates and initializes state info. - * ExecReScanIndexOnlyScan rescans the indexed relation. - * ExecEndIndexOnlyScan releases all storage. - * ExecIndexOnlyMarkPos marks scan position. - * ExecIndexOnlyRestrPos restores scan position. - * ExecIndexOnlyScanEstimate estimates DSM space needed for - * parallel index-only scan - * ExecIndexOnlyScanInitializeDSM initialize DSM for parallel - * index-only scan - * ExecIndexOnlyScanReInitializeDSM reinitialize DSM for fresh scan - * ExecIndexOnlyScanInitializeWorker attach to DSM info in parallel worker - */ #include "postgres.h" #include "access/relscan.h" @@ -304,6 +288,8 @@ IndexOnlyRecheck(IndexOnlyScanState *node, TupleTableSlot *slot) /* ---------------------------------------------------------------- * ExecIndexOnlyScan(node) + * + * Scans an index. * ---------------------------------------------------------------- */ static TupleTableSlot * @@ -366,6 +352,8 @@ ExecReScanIndexOnlyScan(IndexOnlyScanState *node) /* ---------------------------------------------------------------- * ExecEndIndexOnlyScan + * + * Releases all storage. * ---------------------------------------------------------------- */ void @@ -415,6 +403,8 @@ ExecEndIndexOnlyScan(IndexOnlyScanState *node) /* ---------------------------------------------------------------- * ExecIndexOnlyMarkPos * + * Marks scan position. + * * Note: we assume that no caller attempts to set a mark before having read * at least one tuple. Otherwise, ioss_ScanDesc might still be NULL. * ---------------------------------------------------------------- @@ -452,6 +442,8 @@ ExecIndexOnlyMarkPos(IndexOnlyScanState *node) /* ---------------------------------------------------------------- * ExecIndexOnlyRestrPos + * + * Restores scan position. * ---------------------------------------------------------------- */ void diff --git a/src/backend/executor/nodeIndexscan.c b/src/backend/executor/nodeIndexscan.c index f255551786e..5bc15b91c66 100644 --- a/src/backend/executor/nodeIndexscan.c +++ b/src/backend/executor/nodeIndexscan.c @@ -12,21 +12,7 @@ * *------------------------------------------------------------------------- */ -/* - * INTERFACE ROUTINES - * ExecIndexScan scans a relation using an index - * IndexNext retrieve next tuple using index - * IndexNextWithReorder same, but recheck ORDER BY expressions - * ExecInitIndexScan creates and initializes state info. - * ExecReScanIndexScan rescans the indexed relation. - * ExecEndIndexScan releases all storage. - * ExecIndexMarkPos marks scan position. - * ExecIndexRestrPos restores scan position. - * ExecIndexScanEstimate estimates DSM space needed for parallel index scan - * ExecIndexScanInitializeDSM initialize DSM for parallel indexscan - * ExecIndexScanReInitializeDSM reinitialize DSM for fresh scan - * ExecIndexScanInitializeWorker attach to DSM info in parallel worker - */ + #include "postgres.h" #include "access/nbtree.h" @@ -537,6 +523,8 @@ reorderqueue_pop(IndexScanState *node) /* ---------------------------------------------------------------- * ExecIndexScan(node) + * + * Scans a relation using an index. * ---------------------------------------------------------------- */ static TupleTableSlot * @@ -798,6 +786,8 @@ ExecIndexAdvanceArrayKeys(IndexArrayKeyInfo *arrayKeys, int numArrayKeys) /* ---------------------------------------------------------------- * ExecEndIndexScan + * + * Releases all storage. * ---------------------------------------------------------------- */ void @@ -842,6 +832,8 @@ ExecEndIndexScan(IndexScanState *node) /* ---------------------------------------------------------------- * ExecIndexMarkPos * + * Marks scan position. + * * Note: we assume that no caller attempts to set a mark before having read * at least one tuple. Otherwise, iss_ScanDesc might still be NULL. * ---------------------------------------------------------------- @@ -879,6 +871,8 @@ ExecIndexMarkPos(IndexScanState *node) /* ---------------------------------------------------------------- * ExecIndexRestrPos + * + * Restores scan position. * ---------------------------------------------------------------- */ void diff --git a/src/backend/executor/nodeLimit.c b/src/backend/executor/nodeLimit.c index baa669abe84..6fc76ff06c8 100644 --- a/src/backend/executor/nodeLimit.c +++ b/src/backend/executor/nodeLimit.c @@ -12,12 +12,6 @@ * *------------------------------------------------------------------------- */ -/* - * INTERFACE ROUTINES - * ExecLimit - extract a limited range of tuples - * ExecInitLimit - initialize node and subnodes.. - * ExecEndLimit - shutdown node and subnodes - */ #include "postgres.h" diff --git a/src/backend/executor/nodeLockRows.c b/src/backend/executor/nodeLockRows.c index c80536931ec..d1497e99463 100644 --- a/src/backend/executor/nodeLockRows.c +++ b/src/backend/executor/nodeLockRows.c @@ -12,12 +12,6 @@ * *------------------------------------------------------------------------- */ -/* - * INTERFACE ROUTINES - * ExecLockRows - fetch locked rows - * ExecInitLockRows - initialize node and subnodes.. - * ExecEndLockRows - shutdown node and subnodes - */ #include "postgres.h" @@ -34,6 +28,8 @@ /* ---------------------------------------------------------------- * ExecLockRows + * + * Fetch locked rows. * ---------------------------------------------------------------- */ static TupleTableSlot * /* return: a tuple or NULL */ diff --git a/src/backend/executor/nodeMaterial.c b/src/backend/executor/nodeMaterial.c index cc93bbe45b0..768300db172 100644 --- a/src/backend/executor/nodeMaterial.c +++ b/src/backend/executor/nodeMaterial.c @@ -12,13 +12,7 @@ * *------------------------------------------------------------------------- */ -/* - * INTERFACE ROUTINES - * ExecMaterial - materialize the result of a subplan - * ExecInitMaterial - initialize node and subnodes - * ExecEndMaterial - shutdown node and subnodes - * - */ + #include "postgres.h" #include "executor/executor.h" @@ -158,6 +152,8 @@ ExecMaterial(PlanState *pstate) /* ---------------------------------------------------------------- * ExecInitMaterial + * + * Initialize node and subnodes. * ---------------------------------------------------------------- */ MaterialState * @@ -234,6 +230,8 @@ ExecInitMaterial(Material *node, EState *estate, int eflags) /* ---------------------------------------------------------------- * ExecEndMaterial + * + * Shutdown node and subnodes. * ---------------------------------------------------------------- */ void diff --git a/src/backend/executor/nodeMergeAppend.c b/src/backend/executor/nodeMergeAppend.c index 7ba53ba1859..36ec26fdebe 100644 --- a/src/backend/executor/nodeMergeAppend.c +++ b/src/backend/executor/nodeMergeAppend.c @@ -10,31 +10,24 @@ * IDENTIFICATION * src/backend/executor/nodeMergeAppend.c * + * NOTES + * A MergeAppend node contains a list of one or more subplans. + * These are each expected to deliver tuples that are sorted according + * to a common sort key. The MergeAppend node merges these streams + * to produce output sorted the same way. + * + * MergeAppend nodes don't make use of their left and right + * subtrees, rather they maintain a list of subplans so + * a typical MergeAppend node looks like this in the plan tree: + * + * ... + * / + * MergeAppend---+------+------+--- nil + * / \ | | | + * nil nil ... ... ... + * subplans *------------------------------------------------------------------------- */ -/* INTERFACE ROUTINES - * ExecInitMergeAppend - initialize the MergeAppend node - * ExecMergeAppend - retrieve the next tuple from the node - * ExecEndMergeAppend - shut down the MergeAppend node - * ExecReScanMergeAppend - rescan the MergeAppend node - * - * NOTES - * A MergeAppend node contains a list of one or more subplans. - * These are each expected to deliver tuples that are sorted according - * to a common sort key. The MergeAppend node merges these streams - * to produce output sorted the same way. - * - * MergeAppend nodes don't make use of their left and right - * subtrees, rather they maintain a list of subplans so - * a typical MergeAppend node looks like this in the plan tree: - * - * ... - * / - * MergeAppend---+------+------+--- nil - * / \ | | | - * nil nil ... ... ... - * subplans - */ #include "postgres.h" @@ -372,6 +365,12 @@ ExecEndMergeAppend(MergeAppendState *node) ExecEndNode(mergeplans[i]); } +/* ---------------------------------------------------------------- + * ExecReScanMergeAppend + * + * Rescan the MergeAppend node. + * ---------------------------------------------------------------- + */ void ExecReScanMergeAppend(MergeAppendState *node) { diff --git a/src/backend/executor/nodeMergejoin.c b/src/backend/executor/nodeMergejoin.c index 2a1d000b03d..3b64630eea8 100644 --- a/src/backend/executor/nodeMergejoin.c +++ b/src/backend/executor/nodeMergejoin.c @@ -10,86 +10,80 @@ * IDENTIFICATION * src/backend/executor/nodeMergejoin.c * - *------------------------------------------------------------------------- - */ -/* - * INTERFACE ROUTINES - * ExecMergeJoin mergejoin outer and inner relations. - * ExecInitMergeJoin creates and initializes run time states - * ExecEndMergeJoin cleans up the node. - * * NOTES * - * Merge-join is done by joining the inner and outer tuples satisfying - * join clauses of the form ((= outerKey innerKey) ...). - * The join clause list is provided by the query planner and may contain - * more than one (= outerKey innerKey) clause (for composite sort key). + * Merge-join is done by joining the inner and outer tuples satisfying + * join clauses of the form ((= outerKey innerKey) ...). + * The join clause list is provided by the query planner and may contain + * more than one (= outerKey innerKey) clause (for composite sort key). * - * However, the query executor needs to know whether an outer - * tuple is "greater/smaller" than an inner tuple so that it can - * "synchronize" the two relations. For example, consider the following - * relations: + * However, the query executor needs to know whether an outer + * tuple is "greater/smaller" than an inner tuple so that it can + * "synchronize" the two relations. For example, consider the following + * relations: * - * outer: (0 ^1 1 2 5 5 5 6 6 7) current tuple: 1 - * inner: (1 ^3 5 5 5 5 6) current tuple: 3 + * outer: (0 ^1 1 2 5 5 5 6 6 7) current tuple: 1 + * inner: (1 ^3 5 5 5 5 6) current tuple: 3 * - * To continue the merge-join, the executor needs to scan both inner - * and outer relations till the matching tuples 5. It needs to know - * that currently inner tuple 3 is "greater" than outer tuple 1 and - * therefore it should scan the outer relation first to find a - * matching tuple and so on. + * To continue the merge-join, the executor needs to scan both inner + * and outer relations till the matching tuples 5. It needs to know + * that currently inner tuple 3 is "greater" than outer tuple 1 and + * therefore it should scan the outer relation first to find a + * matching tuple and so on. * - * Therefore, rather than directly executing the merge join clauses, - * we evaluate the left and right key expressions separately and then - * compare the columns one at a time (see MJCompare). The planner - * passes us enough information about the sort ordering of the inputs - * to allow us to determine how to make the comparison. We may use the - * appropriate btree comparison function, since Postgres' only notion - * of ordering is specified by btree opfamilies. + * Therefore, rather than directly executing the merge join clauses, + * we evaluate the left and right key expressions separately and then + * compare the columns one at a time (see MJCompare). The planner + * passes us enough information about the sort ordering of the inputs + * to allow us to determine how to make the comparison. We may use the + * appropriate btree comparison function, since Postgres' only notion + * of ordering is specified by btree opfamilies. * * - * Consider the above relations and suppose that the executor has - * just joined the first outer "5" with the last inner "5". The - * next step is of course to join the second outer "5" with all - * the inner "5's". This requires repositioning the inner "cursor" - * to point at the first inner "5". This is done by "marking" the - * first inner 5 so we can restore the "cursor" to it before joining - * with the second outer 5. The access method interface provides - * routines to mark and restore to a tuple. + * Consider the above relations and suppose that the executor has + * just joined the first outer "5" with the last inner "5". The + * next step is of course to join the second outer "5" with all + * the inner "5's". This requires repositioning the inner "cursor" + * to point at the first inner "5". This is done by "marking" the + * first inner 5 so we can restore the "cursor" to it before joining + * with the second outer 5. The access method interface provides + * routines to mark and restore to a tuple. * * - * Essential operation of the merge join algorithm is as follows: + * Essential operation of the merge join algorithm is as follows: * - * Join { - * get initial outer and inner tuples INITIALIZE + * Join { + * get initial outer and inner tuples INITIALIZE + * do forever { + * while (outer != inner) { SKIP_TEST + * if (outer < inner) + * advance outer SKIPOUTER_ADVANCE + * else + * advance inner SKIPINNER_ADVANCE + * } + * mark inner position SKIP_TEST * do forever { - * while (outer != inner) { SKIP_TEST - * if (outer < inner) - * advance outer SKIPOUTER_ADVANCE - * else - * advance inner SKIPINNER_ADVANCE - * } - * mark inner position SKIP_TEST - * do forever { - * while (outer == inner) { - * join tuples JOINTUPLES - * advance inner position NEXTINNER - * } - * advance outer position NEXTOUTER - * if (outer == mark) TESTOUTER - * restore inner position to mark TESTOUTER - * else - * break // return to top of outer loop + * while (outer == inner) { + * join tuples JOINTUPLES + * advance inner position NEXTINNER * } + * advance outer position NEXTOUTER + * if (outer == mark) TESTOUTER + * restore inner position to mark TESTOUTER + * else + * break // return to top of outer loop * } * } + * } * - * The merge join operation is coded in the fashion - * of a state machine. At each state, we do something and then - * proceed to another state. This state is stored in the node's - * execution state information and is preserved across calls to - * ExecMergeJoin. -cim 10/31/89 + * The merge join operation is coded in the fashion + * of a state machine. At each state, we do something and then + * proceed to another state. This state is stored in the node's + * execution state information and is preserved across calls to + * ExecMergeJoin. -cim 10/31/89 + *------------------------------------------------------------------------- */ + #include "postgres.h" #include "access/nbtree.h" @@ -594,6 +588,8 @@ ExecMergeTupleDump(MergeJoinState *mergestate) /* ---------------------------------------------------------------- * ExecMergeJoin + * + * Mergejoin outer and inner relations. * ---------------------------------------------------------------- */ static TupleTableSlot * @@ -1430,6 +1426,8 @@ ExecMergeJoin(PlanState *pstate) /* ---------------------------------------------------------------- * ExecInitMergeJoin + * + * Creates and initializes run time states. * ---------------------------------------------------------------- */ MergeJoinState * diff --git a/src/backend/executor/nodeModifyTable.c b/src/backend/executor/nodeModifyTable.c index 84ac2e63add..cdbdbe0df08 100644 --- a/src/backend/executor/nodeModifyTable.c +++ b/src/backend/executor/nodeModifyTable.c @@ -10,30 +10,23 @@ * IDENTIFICATION * src/backend/executor/nodeModifyTable.c * + * NOTES + * Each ModifyTable node contains a list of one or more subplans, + * much like an Append node. There is one subplan per result relation. + * The key reason for this is that in an inherited UPDATE command, each + * result relation could have a different schema (more or different + * columns) requiring a different plan tree to produce it. In an + * inherited DELETE, all the subplans should produce the same output + * rowtype, but we might still find that different plans are appropriate + * for different child relations. + * + * If the query specifies RETURNING, then the ModifyTable returns a + * RETURNING tuple after completing each row insert, update, or delete. + * It must be called again to continue the operation. Without RETURNING, + * we just loop within the node until all the work is done, then + * return NULL. This avoids useless call/return overhead. *------------------------------------------------------------------------- */ -/* INTERFACE ROUTINES - * ExecInitModifyTable - initialize the ModifyTable node - * ExecModifyTable - retrieve the next tuple from the node - * ExecEndModifyTable - shut down the ModifyTable node - * ExecReScanModifyTable - rescan the ModifyTable node - * - * NOTES - * Each ModifyTable node contains a list of one or more subplans, - * much like an Append node. There is one subplan per result relation. - * The key reason for this is that in an inherited UPDATE command, each - * result relation could have a different schema (more or different - * columns) requiring a different plan tree to produce it. In an - * inherited DELETE, all the subplans should produce the same output - * rowtype, but we might still find that different plans are appropriate - * for different child relations. - * - * If the query specifies RETURNING, then the ModifyTable returns a - * RETURNING tuple after completing each row insert, update, or delete. - * It must be called again to continue the operation. Without RETURNING, - * we just loop within the node until all the work is done, then - * return NULL. This avoids useless call/return overhead. - */ #include "postgres.h" @@ -2088,6 +2081,8 @@ ExecModifyTable(PlanState *pstate) /* ---------------------------------------------------------------- * ExecInitModifyTable + * + * Initialize the ModifyTable node. * ---------------------------------------------------------------- */ ModifyTableState * @@ -2628,6 +2623,12 @@ ExecEndModifyTable(ModifyTableState *node) ExecEndNode(node->mt_plans[i]); } +/* ---------------------------------------------------------------- + * ExecReScanModifyTable + * + * Rescan the ModifyTable node. + * ---------------------------------------------------------------- + */ void ExecReScanModifyTable(ModifyTableState *node) { diff --git a/src/backend/executor/nodeNestloop.c b/src/backend/executor/nodeNestloop.c index fc6667ef826..04efbb1a44c 100644 --- a/src/backend/executor/nodeNestloop.c +++ b/src/backend/executor/nodeNestloop.c @@ -12,12 +12,6 @@ * *------------------------------------------------------------------------- */ -/* - * INTERFACE ROUTINES - * ExecNestLoop - process a nestloop join of two plans - * ExecInitNestLoop - initialize the join - * ExecEndNestLoop - shut down the join - */ #include "postgres.h" @@ -257,6 +251,8 @@ ExecNestLoop(PlanState *pstate) /* ---------------------------------------------------------------- * ExecInitNestLoop + * + * Initialize the join. * ---------------------------------------------------------------- */ NestLoopState * diff --git a/src/backend/executor/nodeSeqscan.c b/src/backend/executor/nodeSeqscan.c index 8c46873daaf..7cd48ad9f7e 100644 --- a/src/backend/executor/nodeSeqscan.c +++ b/src/backend/executor/nodeSeqscan.c @@ -12,19 +12,7 @@ * *------------------------------------------------------------------------- */ -/* - * INTERFACE ROUTINES - * ExecSeqScan sequentially scans a relation. - * ExecSeqNext retrieve next tuple in sequential order. - * ExecInitSeqScan creates and initializes a seqscan node. - * ExecEndSeqScan releases any storage allocated. - * ExecReScanSeqScan rescans the relation - * - * ExecSeqScanEstimate estimates DSM space needed for parallel scan - * ExecSeqScanInitializeDSM initialize DSM for parallel scan - * ExecSeqScanReInitializeDSM reinitialize DSM for fresh parallel scan - * ExecSeqScanInitializeWorker attach to DSM info in parallel worker - */ + #include "postgres.h" #include "access/relscan.h" diff --git a/src/backend/executor/nodeSubplan.c b/src/backend/executor/nodeSubplan.c index 574e7bc4fa0..e4d7d47d9bc 100644 --- a/src/backend/executor/nodeSubplan.c +++ b/src/backend/executor/nodeSubplan.c @@ -19,11 +19,7 @@ * *------------------------------------------------------------------------- */ -/* - * INTERFACE ROUTINES - * ExecSubPlan - process a subselect - * ExecInitSubPlan - initialize a subselect - */ + #include "postgres.h" #include <limits.h> diff --git a/src/backend/executor/nodeSubqueryscan.c b/src/backend/executor/nodeSubqueryscan.c index 707ec0d1901..68052f7a521 100644 --- a/src/backend/executor/nodeSubqueryscan.c +++ b/src/backend/executor/nodeSubqueryscan.c @@ -16,15 +16,7 @@ * *------------------------------------------------------------------------- */ -/* - * INTERFACE ROUTINES - * ExecSubqueryScan scans a subquery. - * ExecSubqueryNext retrieve next tuple in sequential order. - * ExecInitSubqueryScan creates and initializes a subqueryscan node. - * ExecEndSubqueryScan releases any storage allocated. - * ExecReScanSubqueryScan rescans the relation - * - */ + #include "postgres.h" #include "executor/execdebug.h" @@ -91,6 +83,8 @@ ExecSubqueryScan(PlanState *pstate) /* ---------------------------------------------------------------- * ExecInitSubqueryScan + * + * Creates and initializes a subqueryscan node. * ---------------------------------------------------------------- */ SubqueryScanState * diff --git a/src/backend/executor/nodeTableFuncscan.c b/src/backend/executor/nodeTableFuncscan.c index 45d5f3c4244..1c7d0e7c263 100644 --- a/src/backend/executor/nodeTableFuncscan.c +++ b/src/backend/executor/nodeTableFuncscan.c @@ -12,14 +12,7 @@ * *------------------------------------------------------------------------- */ -/* - * INTERFACE ROUTINES - * ExecTableFuncscan scans a function. - * ExecFunctionNext retrieve next tuple in sequential order. - * ExecInitTableFuncscan creates and initializes a TableFuncscan node. - * ExecEndTableFuncscan releases any storage allocated. - * ExecReScanTableFuncscan rescans the function - */ + #include "postgres.h" #include "nodes/execnodes.h" @@ -105,6 +98,8 @@ ExecTableFuncScan(PlanState *pstate) /* ---------------------------------------------------------------- * ExecInitTableFuncscan + * + * Creates and initializes a TableFuncscan node. * ---------------------------------------------------------------- */ TableFuncScanState * @@ -237,7 +232,7 @@ ExecEndTableFuncScan(TableFuncScanState *node) /* ---------------------------------------------------------------- * ExecReScanTableFuncscan * - * Rescans the relation. + * Rescans the function. * ---------------------------------------------------------------- */ void diff --git a/src/backend/executor/nodeTidscan.c b/src/backend/executor/nodeTidscan.c index 9961e2b2c1a..ce17b7e04f3 100644 --- a/src/backend/executor/nodeTidscan.c +++ b/src/backend/executor/nodeTidscan.c @@ -12,14 +12,7 @@ * *------------------------------------------------------------------------- */ -/* - * INTERFACE ROUTINES - * - * ExecTidScan scans a relation using tids - * ExecInitTidScan creates and initializes state info. - * ExecReScanTidScan rescans the tid relation. - * ExecEndTidScan releases all storage. - */ + #include "postgres.h" #include "access/sysattr.h" @@ -455,6 +448,8 @@ ExecTidScan(PlanState *pstate) /* ---------------------------------------------------------------- * ExecReScanTidScan(node) + * + * Rescans the tid relation. * ---------------------------------------------------------------- */ void diff --git a/src/backend/executor/nodeUnique.c b/src/backend/executor/nodeUnique.c index ad7039937d0..21019bba8c0 100644 --- a/src/backend/executor/nodeUnique.c +++ b/src/backend/executor/nodeUnique.c @@ -18,17 +18,10 @@ * IDENTIFICATION * src/backend/executor/nodeUnique.c * - *------------------------------------------------------------------------- - */ -/* - * INTERFACE ROUTINES - * ExecUnique - generate a unique'd temporary relation - * ExecInitUnique - initialize node and subnodes - * ExecEndUnique - shutdown node and subnodes - * * NOTES - * Assumes tuples returned from subplan arrive in - * sorted order. + * Assumes tuples returned from subplan arrive in + * sorted order. + *------------------------------------------------------------------------- */ #include "postgres.h" @@ -41,6 +34,8 @@ /* ---------------------------------------------------------------- * ExecUnique + * + * Generate a unique'd temporary relation. * ---------------------------------------------------------------- */ static TupleTableSlot * /* return: a tuple or NULL */ diff --git a/src/backend/executor/nodeValuesscan.c b/src/backend/executor/nodeValuesscan.c index 0069a73588a..e20cb14224d 100644 --- a/src/backend/executor/nodeValuesscan.c +++ b/src/backend/executor/nodeValuesscan.c @@ -13,14 +13,7 @@ * *------------------------------------------------------------------------- */ -/* - * INTERFACE ROUTINES - * ExecValuesScan scans a values list. - * ExecValuesNext retrieve next tuple in sequential order. - * ExecInitValuesScan creates and initializes a valuesscan node. - * ExecEndValuesScan releases any storage allocated. - * ExecReScanValuesScan rescans the values list - */ + #include "postgres.h" #include "executor/executor.h" @@ -217,7 +210,7 @@ ExecValuesScan(PlanState *pstate) } /* ---------------------------------------------------------------- - * ExecInitValuesScan + * ExecInitValuesScan - creates and initializes a valuesscan node. * ---------------------------------------------------------------- */ ValuesScanState * @@ -320,7 +313,7 @@ ExecEndValuesScan(ValuesScanState *node) /* ---------------------------------------------------------------- * ExecReScanValuesScan * - * Rescans the relation. + * Rescans the value list. * ---------------------------------------------------------------- */ void diff --git a/src/backend/libpq/pqcomm.c b/src/backend/libpq/pqcomm.c index c39617a430a..90bfc6fd3f8 100644 --- a/src/backend/libpq/pqcomm.c +++ b/src/backend/libpq/pqcomm.c @@ -35,37 +35,6 @@ *------------------------------------------------------------------------- */ -/*------------------------ - * INTERFACE ROUTINES - * - * setup/teardown: - * StreamServerPort - Open postmaster's server port - * StreamConnection - Create new connection with client - * StreamClose - Close a client/backend connection - * TouchSocketFiles - Protect socket files against /tmp cleaners - * pq_init - initialize libpq at backend startup - * pq_comm_reset - reset libpq during error recovery - * pq_close - shutdown libpq at backend exit - * - * low-level I/O: - * pq_getbytes - get a known number of bytes from connection - * pq_getstring - get a null terminated string from connection - * pq_getmessage - get a message with length word from connection - * pq_getbyte - get next byte from connection - * pq_peekbyte - peek at next byte from connection - * pq_putbytes - send bytes to connection (not flushed until pq_flush) - * pq_flush - flush pending output - * pq_flush_if_writable - flush pending output if writable without blocking - * pq_getbyte_if_available - get a byte if available without blocking - * - * message-level I/O (and old-style-COPY-OUT cruft): - * pq_putmessage - send a normal message (suppressed in COPY OUT mode) - * pq_putmessage_noblock - buffer a normal message (suppressed in COPY OUT) - * pq_startcopyout - inform libpq that a COPY OUT transfer is beginning - * pq_endcopyout - end a COPY OUT transfer - * - *------------------------ - */ #include "postgres.h" #include <signal.h> diff --git a/src/backend/libpq/pqformat.c b/src/backend/libpq/pqformat.c index 805b996d6d8..6b81a298a69 100644 --- a/src/backend/libpq/pqformat.c +++ b/src/backend/libpq/pqformat.c @@ -9,7 +9,9 @@ * Note in particular the distinction between "raw data" and "text"; raw data * is message protocol characters and binary values that are not subject to * character set conversion, while text is converted by character encoding - * rules. + * rules. It is possible to append data to the StringInfo buffer using the + * regular StringInfo routines, but this is discouraged since required + * character set conversion may not occur. * * Incoming messages are similarly read into a StringInfo buffer, via * pq_getmessage, and then parsed and converted from that using the routines @@ -28,46 +30,6 @@ * *------------------------------------------------------------------------- */ -/* - * INTERFACE ROUTINES - * Message assembly and output: - * pq_beginmessage - initialize StringInfo buffer - * pq_sendbyte - append a raw byte to a StringInfo buffer - * pq_sendint - append a binary integer to a StringInfo buffer - * pq_sendint64 - append a binary 8-byte int to a StringInfo buffer - * pq_sendfloat4 - append a float4 to a StringInfo buffer - * pq_sendfloat8 - append a float8 to a StringInfo buffer - * pq_sendbytes - append raw data to a StringInfo buffer - * pq_sendcountedtext - append a counted text string (with character set conversion) - * pq_sendtext - append a text string (with conversion) - * pq_sendstring - append a null-terminated text string (with conversion) - * pq_send_ascii_string - append a null-terminated text string (without conversion) - * pq_endmessage - send the completed message to the frontend - * Note: it is also possible to append data to the StringInfo buffer using - * the regular StringInfo routines, but this is discouraged since required - * character set conversion may not occur. - * - * typsend support (construct a bytea value containing external binary data): - * pq_begintypsend - initialize StringInfo buffer - * pq_endtypsend - return the completed string as a "bytea*" - * - * Special-case message output: - * pq_puttextmessage - generate a character set-converted message in one step - * pq_putemptymessage - convenience routine for message with empty body - * - * Message parsing after input: - * pq_getmsgbyte - get a raw byte from a message buffer - * pq_getmsgint - get a binary integer from a message buffer - * pq_getmsgint64 - get a binary 8-byte int from a message buffer - * pq_getmsgfloat4 - get a float4 from a message buffer - * pq_getmsgfloat8 - get a float8 from a message buffer - * pq_getmsgbytes - get raw data from a message buffer - * pq_copymsgbytes - copy raw data from a message buffer - * pq_getmsgtext - get a counted text string (with conversion) - * pq_getmsgstring - get a null-terminated text string (with conversion) - * pq_getmsgrawstring - get a null-terminated text string - NO conversion - * pq_getmsgend - verify message fully consumed - */ #include "postgres.h" diff --git a/src/backend/tcop/dest.c b/src/backend/tcop/dest.c index ee9e349a5ba..8939e932413 100644 --- a/src/backend/tcop/dest.c +++ b/src/backend/tcop/dest.c @@ -10,21 +10,12 @@ * IDENTIFICATION * src/backend/tcop/dest.c * + * NOTES + * These routines do the appropriate work before and after tuples are + * returned by a query to keep the backend and the "destination" portals + * synchronized. *------------------------------------------------------------------------- */ -/* - * INTERFACE ROUTINES - * BeginCommand - initialize the destination at start of command - * CreateDestReceiver - create tuple receiver object for destination - * EndCommand - clean up the destination at end of command - * NullCommand - tell dest that an empty query string was recognized - * ReadyForQuery - tell dest that we are ready for a new query - * - * NOTES - * These routines do the appropriate work before and after - * tuples are returned by a query to keep the backend and the - * "destination" portals synchronized. - */ #include "postgres.h" diff --git a/src/backend/utils/cache/relcache.c b/src/backend/utils/cache/relcache.c index 06503bc98b2..c67e0d71ccf 100644 --- a/src/backend/utils/cache/relcache.c +++ b/src/backend/utils/cache/relcache.c @@ -10,20 +10,12 @@ * IDENTIFICATION * src/backend/utils/cache/relcache.c * + * NOTES + * The following code contains many undocumented hacks. Please be + * careful.... *------------------------------------------------------------------------- */ -/* - * INTERFACE ROUTINES - * RelationCacheInitialize - initialize relcache (to empty) - * RelationCacheInitializePhase2 - initialize shared-catalog entries - * RelationCacheInitializePhase3 - finish initializing relcache - * RelationIdGetRelation - get a reldesc by relation id - * RelationClose - close an open relation - * - * NOTES - * The following code contains many undocumented hacks. Please be - * careful.... - */ + #include "postgres.h" #include <sys/file.h> @@ -3439,6 +3431,11 @@ RelationSetNewRelfilenode(Relation relation, char persistence, #define INITRELCACHESIZE 400 +/* + * RelationCacheInitialize + * + * Initialize relcache (to empty). + */ void RelationCacheInitialize(void) { diff --git a/src/interfaces/libpq/fe-auth.c b/src/interfaces/libpq/fe-auth.c index 08a5a9c1f30..9f55523ce1a 100644 --- a/src/interfaces/libpq/fe-auth.c +++ b/src/interfaces/libpq/fe-auth.c @@ -12,14 +12,6 @@ *------------------------------------------------------------------------- */ -/* - * INTERFACE ROUTINES - * frontend (client) routines: - * pg_fe_sendauth send authentication information - * pg_fe_getauthname get user's name according to the client side - * of the authentication system - */ - #include "postgres_fe.h" #ifdef WIN32 -- 2.18.0.rc2.dirty
