Add comments for AlteredTableInfo->rel

alvherre · alvherre · commit cc121d559696 · 2021-03-25T16:07:15.000-03:00
The prior commit which introduced it was pretty squalid in terms of
code documentation, so add some comments.
diff --git a/src/backend/commands/tablecmds.c b/src/backend/commands/tablecmds.c
@@ -157,8 +157,16 @@ typedef struct AlteredTableInfo
 	Oid			relid;			/* Relation to work on */
 	char		relkind;		/* Its relkind */
 	TupleDesc	oldDesc;		/* Pre-modification tuple descriptor */
-	/* Transiently set during Phase 2, normally set to NULL */
+
+	/*
+	 * Transiently set during Phase 2, normally set to NULL.
+	 *
+	 * ATRewriteCatalogs sets this when it starts, and closes when ATExecCmd
+	 * returns control.  This can be exploited by ATExecCmd subroutines to
+	 * close/reopen across transaction boundaries.
+	 */
 	Relation	rel;
+
 	/* Information saved by Phase 1 for Phase 2: */
 	List	   *subcmds[AT_NUM_PASSES]; /* Lists of AlterTableCmd */
 	/* Information saved by Phases 1/2 for Phase 3: */
@@ -4577,7 +4585,9 @@ ATRewriteCatalogs(List **wqueue, LOCKMODE lockmode,
 				continue;
 
 			/*
-			 * Appropriate lock was obtained by phase 1, needn't get it again
+			 * Open the relation and store it in tab.  This allows subroutines
+			 * close and reopen, if necessary.  Appropriate lock was obtained
+			 * by phase 1, needn't get it again.
 			 */
 			tab->rel = relation_open(tab->relid, NoLock);
 
