Refactor how we form HeapTuples for CatalogTuple(Insert|Update)

This commit provides a set of macros that should be used when inserting
or updating tuples.  These macros help declare state necessary when
tracking updates and forming new tuples.  There are macros used to set
fields to new values or to NULL.  Finally there are macros for inserting
or updating these tuples.

There are a few reasons to standardize catalog modification code and
move it away from direct Form/GETSTRUCT or values/nulls/replaces-style
access.  First, these models can be error prone and require attention to
a variety of details that can easily be overlooked.  Second, at present
while we know what fields are modified we don't preserve that
information and pass it on to the heap_update() code.  Third, at some
point we'll need in-memory representations completely decoupled from the
disk to support upgradeable catalogs.

Previous this patch there are two methods for accomplishing this task;
Form/GETSTRUCT, and values/nulls/replaces. This new method provides a
more intuitive and less error-prone approach without changing the
fundamentals of the process, meaning this should remain backward
compatible.  It is now possible to retain knowledge of the set of
mutated attributes when working with catalog tuples.  A follow-on patch
will use this to avoid the overhead of HeapDetermineColumnsInfo() in
heap_update() where (while holding a lock) we re-discover the set of
modified by comparing old/new HeapTuple Datums when trying to identify
indexed attributes that have new values and should prevent HOT updates.

The "Form/GETSTRUCT" model allows for direct access to the tuple data
that is then modified, copied, and then updated via
CatalogTupleUpdate().

Old:
  Form_pg_index form = (Form_pg_index) GETSTRUCT(tuple);

  form->inisclustered = false;
  CatalogTupleUpdate(relation, &tuple->t_self, tuple);

New:
  CatalogUpdateFieldContext(pg_index, ctx);
  CatalogSetForm(pg_index, ctx, tuple);

  CatalogTupleUpdateField(ctx, pg_index, indisclustered, false);
  ModifyCatalogTupleField(relation, tuple, ctx);

The "values/nulls/replaces" model collects the necessary information to
either update or create a heap tuple using heap_modify_tuple() or
heap_form_tuple() or sometimes heap_modify_tuple_by_cols().  While all
those functions remain unchanged and can be used there is a new model.

Old:
  bool    nulls[Natts_pg_type];
  bool    replaces[Natts_pg_type];
  Datum   values[Natts_pg_type];

  values[Anum_pg_type_typtype - 1] = CharGetDatum(typeType);
  nulls[Anum_pg_type_typdefaultbin - 1] = true;
  replaces[Anum_pg_type_oid - 1] = false;

  tup = heap_modify_tuple(tuple, desc, values, nulls, replaces);

  CatalogTupleUpdate(relation, &tuple->t_self, tuple);

New:
  CatalogUpdateValuesContext(pg_type, ctx);

  CatalogTupleUpdateValue(ctx, pg_type, typtype, CharGetDatum(typeType));
  ModifyCatalogTupleValues(relation, tuple, ctx);

The heap_update_tuple() function is functionally equivalent to
heap_modify_tuple(), but takes a Bitmapset called "updated" rather than
an array of bool generally called "replaces" as a method for indicating
what was modified.  Additionally, this new function tries to balance the
tradeoffs of calling heap_getattr() versus heap_deform_tuple() based
on the ratio of attributes updated and their known runtime complexities.
Both paths are functionally equivalent.

The changes also include initialization of the values/nulls arrays
rather than loops or memset().

There is no impact to non-catalog related paths.

Author: gburd

src/backend/access/common/heaptuple.c

@@ -1325,6 +1325,125 @@ heap_modify_tuple_by_cols(HeapTuple tuple,
 	return newTuple;
 }
 
+/*
+ * heap_update_tuple
+ *		Form a new tuple from an old tuple and a set of replacement values.
+ *
+ * Creates a new HeapTuple by selectively replacing attributes from the original
+ * tuple with new values. The 'updated' Bitmapset specifies which attributes
+ * (by attribute number, 1-based adjusted by FirstLowInvalidHeapAttributeNumber)
+ * should be replaced with corresponding entries from new_values and new_isnull
+ * arrays (0-based indices).
+ *
+ * Performance strategy:
+ * - If updating many attributes (> 2*natts/3), use heap_getattr() to extract
+ *   only the few non-updated attributes. This is O(k*n) where k is the number
+ *   of non-updated attributes, which is small when updating many.
+ * - If updating few attributes (<= 2*natts/3), use heap_deform_tuple() to
+ *   extract all attributes at once (O(n)), then replace the updated ones.
+ *   This avoids the O(n^2) cost of many heap_getattr() calls.
+ *
+ * The threshold of 2*natts/3 balances the fixed O(n) cost of heap_deform_tuple
+ * against the variable O(k*n) cost of heap_getattr, where k = natts - num_updated.
+ */
+HeapTuple
+heap_update_tuple(HeapTuple tuple,
+				  TupleDesc desc,
+				  const Datum *new_values,
+				  const bool *new_nulls,
+				  const Bitmapset *updated)
+{
+	int			natts = desc->natts;
+	int			num_updated;
+	Datum	   *values;
+	bool	   *nulls;
+	HeapTuple	new_tuple;
+
+	Assert(!bms_is_empty(updated));
+
+	num_updated = bms_num_members(updated);
+	Assert(num_updated <= natts);
+
+	values = (Datum *) palloc0(natts * sizeof(Datum));
+	nulls = (bool *) palloc0(natts * sizeof(bool));
+
+	/*
+	 * Choose strategy based on update density. When updating most attributes,
+	 * it's cheaper to extract the few unchanged ones individually.
+	 */
+	if (num_updated > (2 * natts) / 3)
+	{
+		/* Updating many: use heap_getattr for the few non-updated attributes */
+		for (int i = 0; i < natts; i++)
+		{
+			/*
+			 * Convert array index to attribute number, then to bitmapset
+			 * member. Array index i (0-based) -> attnum (1-based) -> bms
+			 * member.
+			 */
+			AttrNumber	attnum = i + 1;
+			int			member = attnum - FirstLowInvalidHeapAttributeNumber;
+
+			if (bms_is_member(member, updated))
+			{
+				/* Use replacement value */
+				if (unlikely(!new_values || !new_nulls))
+					values[i] = heap_getattr(tuple, attnum, desc, &nulls[i]);
+
+				if (likely(new_values))
+					values[i] = new_values[i];
+
+				if (likely(new_nulls))
+					nulls[i] = new_nulls[i];
+			}
+			else
+			{
+				/* Extract original value using heap_getattr (1-based) */
+				values[i] = heap_getattr(tuple, attnum, desc, &nulls[i]);
+			}
+		}
+	}
+	else
+	{
+		int			member = -1;
+
+		/* Updating few: deform entire tuple, then replace updated attributes */
+		heap_deform_tuple(tuple, desc, values, nulls);
+
+		while ((member = bms_next_member(updated, member)) >= 0)
+		{
+			/*
+			 * Convert bitmapset member to attribute number, then to array
+			 * index. bms_member -> attnum (1-based) -> array index i
+			 * (0-based).
+			 */
+			AttrNumber	attnum = member + FirstLowInvalidHeapAttributeNumber;
+			int			i = attnum - 1;
+
+			Assert(i >= 0 && i < natts);
+
+			if (likely(new_values))
+				values[i] = new_values[i];
+
+			if (likely(new_nulls))
+				nulls[i] = new_nulls[i];
+		}
+	}
+
+	/* Create the new tuple */
+	new_tuple = heap_form_tuple(desc, values, nulls);
+
+	pfree(values);
+	pfree(nulls);
+
+	/* Preserve tuple identity and location information from the original */
+	new_tuple->t_data->t_ctid = tuple->t_data->t_ctid;
+	new_tuple->t_self = tuple->t_self;
+	new_tuple->t_tableOid = tuple->t_tableOid;
+
+	return new_tuple;
+}
+
 /*
  * heap_deform_tuple
  *		Given a tuple, extract data into values/isnull arrays; this is

src/backend/catalog/indexing.c

@@ -225,58 +225,67 @@ CatalogTupleCheckConstraints(Relation heapRel, HeapTuple tup)
  *
  * This is a convenience routine for the common case of inserting a single
  * tuple in a system catalog; it inserts a new heap tuple, keeping indexes
- * current.  Avoid using it for multiple tuples, since opening the indexes
- * and building the index info structures is moderately expensive.
- * (Use CatalogTupleInsertWithInfo in such cases.)
+ * current.
+ *
+ * If 'indstate' is NULL, the function opens and closes the indexes internally.
+ * This is convenient for single-tuple updates but has overhead from opening the
+ * indexes and building index info structures.
+ *
+ * If 'indstate' is provided (non-NULL), it is used directly without opening or
+ * closing indexes. This allows callers to amortize index management costs across
+ * multiple tuple updates. Callers must use CatalogOpenIndexes() before the first
+ * update and CatalogCloseIndexes() after the last update.
+ *
+ * XXX: At some point we might cache the CatalogIndexState data somewhere (perhaps
+ * in the relcache) so that callers needn't trouble over this.
  */
 void
-CatalogTupleInsert(Relation heapRel, HeapTuple tup)
+CatalogTupleInsert(Relation heapRel, HeapTuple tup,
+				   CatalogIndexState indstate)
 {
-	CatalogIndexState indstate;
-
-	CatalogTupleCheckConstraints(heapRel, tup);
-
-	indstate = CatalogOpenIndexes(heapRel);
+	bool		close_indexes = false;
 
-	simple_heap_insert(heapRel, tup);
-
-	CatalogIndexInsert(indstate, tup, TU_All);
-	CatalogCloseIndexes(indstate);
-}
+	/* Open indexes if not provided by caller */
+	if (indstate == NULL)
+	{
+		indstate = CatalogOpenIndexes(heapRel);
+		close_indexes = true;
+	}
 
-/*
- * CatalogTupleInsertWithInfo - as above, but with caller-supplied index info
- *
- * This should be used when it's important to amortize CatalogOpenIndexes/
- * CatalogCloseIndexes work across multiple insertions.  At some point we
- * might cache the CatalogIndexState data somewhere (perhaps in the relcache)
- * so that callers needn't trouble over this ... but we don't do so today.
- */
-void
-CatalogTupleInsertWithInfo(Relation heapRel, HeapTuple tup,
-						   CatalogIndexState indstate)
-{
 	CatalogTupleCheckConstraints(heapRel, tup);
 
 	simple_heap_insert(heapRel, tup);
 
 	CatalogIndexInsert(indstate, tup, TU_All);
+
+	/* Close indexes only if we opened them ourselves */
+	if (close_indexes)
+		CatalogCloseIndexes(indstate);
 }
 
 /*
- * CatalogTuplesMultiInsertWithInfo - as above, but for multiple tuples
+ * CatalogTuplesMultiInsert - as above, but for multiple tuples
  *
  * Insert multiple tuples into the given catalog relation at once, with an
  * amortized cost of CatalogOpenIndexes.
  */
 void
-CatalogTuplesMultiInsertWithInfo(Relation heapRel, TupleTableSlot **slot,
-								 int ntuples, CatalogIndexState indstate)
+CatalogTuplesMultiInsert(Relation heapRel, TupleTableSlot **slot,
+						 int ntuples, CatalogIndexState indstate)
 {
+	bool		close_indexes = false;
+
 	/* Nothing to do */
 	if (ntuples <= 0)
 		return;
 
+	/* Open indexes if not provided by caller */
+	if (indstate == NULL)
+	{
+		indstate = CatalogOpenIndexes(heapRel);
+		close_indexes = true;
+	}
+
 	heap_multi_insert(heapRel, slot, ntuples,
 					  GetCurrentCommandId(true), 0, NULL);
 
@@ -296,54 +305,55 @@ CatalogTuplesMultiInsertWithInfo(Relation heapRel, TupleTableSlot **slot,
 		if (should_free)
 			heap_freetuple(tuple);
 	}
+
+	/* Close indexes only if we opened them ourselves */
+	if (close_indexes)
+		CatalogCloseIndexes(indstate);
 }
 
 /*
  * CatalogTupleUpdate - do heap and indexing work for updating a catalog tuple
  *
  * Update the tuple identified by "otid", replacing it with the data in "tup".
  *
- * This is a convenience routine for the common case of updating a single
- * tuple in a system catalog; it updates one heap tuple, keeping indexes
- * current.  Avoid using it for multiple tuples, since opening the indexes
- * and building the index info structures is moderately expensive.
- * (Use CatalogTupleUpdateWithInfo in such cases.)
+ * This function updates a heap tuple in a system catalog and keeps its indexes
+ * current. The 'updated' bitmapset specifies which columns were modified.
+ *
+ * If 'indstate' is NULL, the function opens and closes the indexes internally.
+ * This is convenient for single-tuple updates but has overhead from opening the
+ * indexes and building index info structures.
+ *
+ * If 'indstate' is provided (non-NULL), it is used directly without opening or
+ * closing indexes. This allows callers to amortize index management costs across
+ * multiple tuple updates. Callers must use CatalogOpenIndexes() before the first
+ * update and CatalogCloseIndexes() after the last update.
+ *
+ * XXX: At some point we might cache the CatalogIndexState data somewhere (perhaps
+ * in the relcache) so that callers needn't trouble over this.
  */
 void
-CatalogTupleUpdate(Relation heapRel, const ItemPointerData *otid, HeapTuple tup)
+CatalogTupleUpdate(Relation heapRel, const ItemPointerData *otid, HeapTuple tuple,
+				   const Bitmapset *updated, CatalogIndexState indstate)
 {
-	CatalogIndexState indstate;
 	TU_UpdateIndexes updateIndexes = TU_All;
+	bool		close_indexes = false;
 
-	CatalogTupleCheckConstraints(heapRel, tup);
-
-	indstate = CatalogOpenIndexes(heapRel);
-
-	simple_heap_update(heapRel, otid, tup, &updateIndexes);
-
-	CatalogIndexInsert(indstate, tup, updateIndexes);
-	CatalogCloseIndexes(indstate);
-}
+	CatalogTupleCheckConstraints(heapRel, tuple);
 
-/*
- * CatalogTupleUpdateWithInfo - as above, but with caller-supplied index info
- *
- * This should be used when it's important to amortize CatalogOpenIndexes/
- * CatalogCloseIndexes work across multiple updates.  At some point we
- * might cache the CatalogIndexState data somewhere (perhaps in the relcache)
- * so that callers needn't trouble over this ... but we don't do so today.
- */
-void
-CatalogTupleUpdateWithInfo(Relation heapRel, const ItemPointerData *otid, HeapTuple tup,
-						   CatalogIndexState indstate)
-{
-	TU_UpdateIndexes updateIndexes = TU_All;
+	/* Open indexes if not provided by caller */
+	if (indstate == NULL)
+	{
+		indstate = CatalogOpenIndexes(heapRel);
+		close_indexes = true;
+	}
 
-	CatalogTupleCheckConstraints(heapRel, tup);
+	simple_heap_update(heapRel, otid, tuple, &updateIndexes);
 
-	simple_heap_update(heapRel, otid, tup, &updateIndexes);
+	CatalogIndexInsert(indstate, tuple, updateIndexes);
 
-	CatalogIndexInsert(indstate, tup, updateIndexes);
+	/* Close indexes only if we opened them ourselves */
+	if (close_indexes)
+		CatalogCloseIndexes(indstate);
 }
 
 /*
@@ -355,11 +365,6 @@ CatalogTupleUpdateWithInfo(Relation heapRel, const ItemPointerData *otid, HeapTu
  * cleanup will be done later by VACUUM.  However, callers of this function
  * shouldn't have to know that; we'd like a uniform abstraction for all
  * catalog tuple changes.  Hence, provide this currently-trivial wrapper.
- *
- * The abstraction is a bit leaky in that we don't provide an optimized
- * CatalogTupleDeleteWithInfo version, because there is currently nothing to
- * optimize.  If we ever need that, rather than touching a lot of call sites,
- * it might be better to do something about caching CatalogIndexState.
  */
 void
 CatalogTupleDelete(Relation heapRel, const ItemPointerData *tid)