mirror/postgresql
2
0
Fork 0
mirror of https://git.postgresql.org/git/postgresql.git synced 2025-01-06 15:24:56 +08:00
Code Issues Packages Projects Releases Wiki Activity

Doc: flesh out fmgr/README's description of context-node usage.

Browse Source 
I wrote this to provide a home for a planned discussion of error
return conventions for non-error-throwing functions.  But it seems
useful as documentation of existing code no matter what becomes of
that proposal, so commit separately.
This commit is contained in:
Tom Lane 2022-12-03 10:50:39 -05:00
parent 2605643a3a
commit 29452de734
1 changed files with 37 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
src/backend/utils/fmgr/README
View File

@ -78,11 +78,7 @@ to find out the OID of the specific function being called.
context is NULL for an "ordinary" function call, but may point to additional
info when the function is called in certain contexts. (For example, the
trigger manager will pass information about the current trigger event here.)
If context is used, it should point to some subtype of Node; the particular
kind of context is indicated by the node type field. (A callee should
always check the node type before assuming it knows what kind of context is
being passed.) fmgr itself puts no other restrictions on the use of this
field.
Further details appear in "Function Call Contexts" below.
resultinfo is NULL when calling any function from which a simple Datum
result is expected. It may point to some subtype of Node if the function
@ -236,6 +232,42 @@ context. When and if the value is actually stored into a tuple, the
tuple toaster will decide whether toasting is needed.
Function Call Contexts
----------------------
If a caller passes a non-NULL pointer in fcinfo->context, it should point
to some subtype of Node; the particular kind of context is indicated by the
node type field. (A callee should always check the node type, via IsA(),
before assuming it knows what kind of context is being passed.) fmgr
itself puts no other restrictions on the use of this field.
Current uses of this convention include:
* Trigger functions are passed an instance of struct TriggerData,
containing information about the trigger context. (The trigger function
does not receive any normal arguments.) See commands/trigger.h for
more information and macros that are commonly used by trigger functions.
* Aggregate functions (or to be precise, their transition and final
functions) are passed an instance of struct AggState, that is the executor
state node for the calling Agg plan node; or if they are called as window
functions, they receive an instance of struct WindowAggState. It is
recommended that these pointers be used only via AggCheckCallContext()
and sibling functions, which are declared in fmgr.h but are documented
only with their source code in src/backend/executor/nodeAgg.c. Typically
these context nodes are only of interest when the transition and final
functions wish to optimize execution based on knowing that they are being
used within an aggregate rather than as standalone SQL functions.
* True window functions receive an instance of struct WindowObject.
(Like trigger functions, they don't receive any normal arguments.)
See windowapi.h for more information.
* Procedures are passed an instance of struct CallContext, containing
information about the context of the CALL statement, particularly
whether it is within an "atomic" execution context.
Functions Accepting or Returning Sets
-------------------------------------