Update xact.c comments for clarity.

src/backend/access/transam/xact.c

@@ -8,13 +8,13 @@
  *
  *
  * IDENTIFICATION
- *	  $Header: /cvsroot/pgsql/src/backend/access/transam/xact.c,v 1.137 2002/11/11 22:19:20 tgl Exp $
+ *	  $Header: /cvsroot/pgsql/src/backend/access/transam/xact.c,v 1.138 2002/11/13 03:12:05 momjian Exp $
  *
  * NOTES
  *		Transaction aborts can now occur two ways:
  *
- *		1)	system dies from some internal cause  (Assert, etc..)
- *		2)	user types abort
+ *		1)	system dies from some internal cause  (syntax error, etc..)
+ *		2)	user types ABORT
  *
  *		These two cases used to be treated identically, but now
  *		we need to distinguish them.  Why?	consider the following
@@ -30,8 +30,8 @@
  *		In case 1, we want to abort the transaction and return to the
  *		default state.	In case 2, there may be more commands coming
  *		our way which are part of the same transaction block and we have
- *		to ignore these commands until we see an END transaction.
- *		(or an ABORT! --djm)
+ *		to ignore these commands until we see a COMMIT transaction or
+ *		ROLLBACK.
  *
  *		Internal aborts are now handled by AbortTransactionBlock(), just as
  *		they always have been, and user aborts are now handled by
@@ -52,14 +52,6 @@
  *		  TransactionCommandContext until this point.
  *
  *	 NOTES
- *		This file is an attempt at a redesign of the upper layer
- *		of the V1 transaction system which was too poorly thought
- *		out to describe.  This new system hopes to be both simpler
- *		in design, simpler to extend and needs to contain added
- *		functionality to solve problems beyond the scope of the V1
- *		system.  (In particuler, communication of transaction
- *		information between parallel backends has to be supported)
- *
  *		The essential aspects of the transaction system are:
  *
  *				o  transaction id generation
@@ -69,7 +61,7 @@
  *				o  lock cleanup
  *
  *		Hence, the functional division of the transaction code is
- *		based on what of the above things need to be done during
+ *		based on which of the above things need to be done during
  *		a start/commit/abort transaction.  For instance, the
  *		routine AtCommit_Memory() takes care of all the memory
  *		cleanup stuff done at commit time.
@@ -99,17 +91,17 @@
  *				CommitTransactionBlock
  *				AbortTransactionBlock
  *
- *		These are invoked only in responce to a user "BEGIN", "END",
- *		or "ABORT" command.  The tricky part about these functions
+ *		These are invoked only in responce to a user "BEGIN WORK", "COMMIT",
+ *		or "ROLLBACK" command.  The tricky part about these functions
  *		is that they are called within the postgres main loop, in between
  *		the StartTransactionCommand() and CommitTransactionCommand().
  *
  *		For example, consider the following sequence of user commands:
  *
  *		1)		begin
- *		2)		retrieve (foo.all)
- *		3)		append foo (bar = baz)
- *		4)		end
+ *		2)		select * from foo
+ *		3)		insert into foo (bar = baz)
+ *		4)		commit
  *
  *		in the main processing loop, this results in the following
  *		transaction sequence:
@@ -120,15 +112,15 @@
  *			\	CommitTransactionCommand();
  *
  *			/	StartTransactionCommand();
- *		2) <	ProcessQuery();					<< retrieve (foo.all)
+ *		2) <	ProcessQuery();					<< select * from foo
  *			\	CommitTransactionCommand();
  *
  *			/	StartTransactionCommand();
- *		3) <	ProcessQuery();					<< append foo (bar = baz)
+ *		3) <	ProcessQuery();					<< insert into foo (bar = baz)
  *			\	CommitTransactionCommand();
  *
  *			/	StartTransactionCommand();
- *		4) /	ProcessUtility();				<< end
+ *		4) /	ProcessUtility();				<< commit
  *		   \		CommitTransactionBlock();
  *			\	CommitTransactionCommand();
  *
@@ -139,19 +131,14 @@
  *		outside these calls they need to do normal start/commit
  *		processing.
  *
- *		Furthermore, suppose the "retrieve (foo.all)" caused an abort
+ *		Furthermore, suppose the "select * from foo" caused an abort
  *		condition.	We would then want to abort the transaction and
- *		ignore all subsequent commands up to the "end".
+ *		ignore all subsequent commands up to the "commit".
  *		-cim 3/23/90
  *
  *-------------------------------------------------------------------------
  */
 
-/*
- * Large object clean up added in CommitTransaction() to prevent buffer leaks.
- * [PA, 7/17/98]
- * [PA] is Pascal André <andre@via.ecp.fr>
- */
 #include "postgres.h"
 
 #include <unistd.h>
@@ -201,9 +188,8 @@ static void CommitTransaction(void);
 static void RecordTransactionAbort(void);
 static void StartTransaction(void);
 
-/* ----------------
+/*
  *	global variables holding the current transaction state.
- * ----------------
  */
 static TransactionStateData CurrentTransactionStateData = {
 	0,							/* transaction id */
@@ -211,7 +197,7 @@ static TransactionStateData CurrentTransactionStateData = {
 	0,							/* scan command id */
 	0x0,						/* start time */
 	TRANS_DEFAULT,				/* transaction state */
-	TBLOCK_DEFAULT				/* transaction block state */
+	TBLOCK_DEFAULT				/* transaction block state of client queries */
 };
 
 TransactionState CurrentTransactionState = &CurrentTransactionStateData;
@@ -853,7 +839,6 @@ AtCleanup_Memory(void)
 
 /* --------------------------------
  *	StartTransaction
- *
  * --------------------------------
  */
 static void
@@ -930,7 +915,6 @@ CurrentXactInProgress(void)
 
 /* --------------------------------
  *	CommitTransaction
- *
  * --------------------------------
  */
 static void
@@ -1051,7 +1035,6 @@ CommitTransaction(void)
 
 /* --------------------------------
  *	AbortTransaction
- *
  * --------------------------------
  */
 static void
@@ -1158,7 +1141,6 @@ AbortTransaction(void)
 
 /* --------------------------------
  *	CleanupTransaction
- *
  * --------------------------------
  */
 static void
@@ -1730,6 +1712,11 @@ IsTransactionBlock(void)
 	return false;
 }
 
+
+/*
+ *	XLOG support routines
+ */
+
 void
 xact_redo(XLogRecPtr lsn, XLogRecord *record)
 {

src/include/access/xact.h

@@ -7,7 +7,7 @@
  * Portions Copyright (c) 1996-2002, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $Id: xact.h,v 1.46 2002/10/21 22:06:20 tgl Exp $
+ * $Id: xact.h,v 1.47 2002/11/13 03:12:05 momjian Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -46,9 +46,11 @@ typedef struct TransactionStateData
 
 typedef TransactionStateData *TransactionState;
 
-/* ----------------
- *		transaction states
- * ----------------
+/*
+ *	transaction states - transaction state from server perspective
+ *	
+ *	Syntax error could cause transaction to abort, but client code thinks
+ *	it is still in a transaction, so we have to wait for COMMIT/ROLLBACK.
  */
 #define TRANS_DEFAULT			0
 #define TRANS_START				1
@@ -56,9 +58,8 @@ typedef TransactionStateData *TransactionState;
 #define TRANS_COMMIT			3
 #define TRANS_ABORT				4
 
-/* ----------------
- *		transaction block states
- * ----------------
+/*
+ *	transaction block states - transaction state of client queries
  */
 #define TBLOCK_DEFAULT			0
 #define TBLOCK_BEGIN			1