Doc: add comments about PreventInTransactionBlock/IsInTransactionBlock.

Add a little to the header comments for these functions to make it
clearer what guarantees about commit behavior are provided to callers.
(See commit f92944137 for context.)

Although this is only a comment change, it's really documentation
aimed at authors of extensions, so it seems appropriate to back-patch.

Yugo Nagata and Tom Lane, per further discussion of bug #17434.

Discussion: https://postgr.es/m/17434-d9f7a064ce2a88a3@postgresql.org

diff --git a/src/backend/access/transam/xact.c b/src/backend/access/transam/xact.c
index 477ca9c7b26c9abfa83130c67ed90def94d93ac0..2cfd3c9b552d557fe38cc8a6e673578b8a36d632 100644 (file)
--- a/src/backend/access/transam/xact.c
+++ b/src/backend/access/transam/xact.c
@@ -3386,6 +3386,10 @@ AbortCurrentTransaction(void)
  * a transaction block, typically because they have non-rollback-able
  * side effects or do internal commits.
  *
+ * If this routine completes successfully, then the calling statement is
+ * guaranteed that if it completes without error, its results will be
+ * committed immediately.
+ *
  * If we have already started a transaction block, issue an error; also issue
  * an error if we appear to be running inside a user-defined function (which
  * could issue more commands and possibly cause a failure after the statement
@@ -3511,6 +3515,10 @@ CheckTransactionBlock(bool isTopLevel, bool throwError, const char *stmtType)
  * a transaction block than when running as single commands.  ANALYZE is
  * currently the only example.
  *
+ * If this routine returns "false", then the calling statement is
+ * guaranteed that if it completes without error, its results will be
+ * committed immediately.
+ *
  * isTopLevel: passed down from ProcessUtility to determine whether we are
  * inside a function.
  */