pgstat: consistent function comment formatting.

There was a wild mishmash of function comment formatting in pgstat, making it
hard to know what to use for any new function and hard to extend existing
comments (particularly due to randomly different forms of indentation).

Author: Andres Freund <andres@anarazel.de>
Reviewed-By: Thomas Munro <thomas.munro@gmail.com>
Discussion: https://postgr.es/m/20220329191727.mzzwbl7udhpq7pmf@alap3.anarazel.de
Discussion: https://postgr.es/m/20220308205351.2xcn6k4x5yivcxyd@alap3.anarazel.de

src/backend/utils/activity/pgstat_archiver.c

@@ -21,12 +21,9 @@
 #include "utils/timestamp.h"
 
 
-/* ----------
- * pgstat_send_archiver() -
- *
- *	Tell the collector about the WAL file that we successfully
- *	archived or failed to archive.
- * ----------
+/*
+ * Tell the collector about the WAL file that we successfully
+ * archived or failed to archive.
  */
 void
 pgstat_send_archiver(const char *xlog, bool failed)

src/backend/utils/activity/pgstat_bgwriter.c

@@ -28,11 +28,8 @@
 PgStat_MsgBgWriter PendingBgWriterStats;
 
 
-/* ----------
- * pgstat_send_bgwriter() -
- *
- *		Send bgwriter statistics to the collector
- * ----------
+/*
+ * Send bgwriter statistics to the collector
  */
 void
 pgstat_send_bgwriter(void)

src/backend/utils/activity/pgstat_checkpointer.c

@@ -28,11 +28,8 @@
 PgStat_MsgCheckpointer PendingCheckpointerStats;
 
 
-/* ----------
- * pgstat_send_checkpointer() -
- *
- *		Send checkpointer statistics to the collector
- * ----------
+/*
+ * Send checkpointer statistics to the collector
  */
 void
 pgstat_send_checkpointer(void)

src/backend/utils/activity/pgstat_database.c

@@ -36,13 +36,10 @@ SessionEndType pgStatSessionEndCause = DISCONNECT_NORMAL;
 static PgStat_Counter pgLastSessionReportTime = 0;
 
 
-/* ----------
- * pgstat_drop_database() -
- *
- *	Tell the collector that we just dropped a database.
- *	(If the message gets lost, we will still clean the dead DB eventually
- *	via future invocations of pgstat_vacuum_stat().)
- * ----------
+/*
+ * Tell the collector that we just dropped a database.
+ * (If the message gets lost, we will still clean the dead DB eventually
+ * via future invocations of pgstat_vacuum_stat().)
  */
 void
 pgstat_drop_database(Oid databaseid)
@@ -57,11 +54,8 @@ pgstat_drop_database(Oid databaseid)
 	pgstat_send(&msg, sizeof(msg));
 }
 
-/* --------
- * pgstat_report_recovery_conflict() -
- *
- *	Tell the collector about a Hot Standby recovery conflict.
- * --------
+/*
+ * Tell the collector about a Hot Standby recovery conflict.
  */
 void
 pgstat_report_recovery_conflict(int reason)
@@ -77,11 +71,8 @@ pgstat_report_recovery_conflict(int reason)
 	pgstat_send(&msg, sizeof(msg));
 }
 
-/* --------
- * pgstat_report_deadlock() -
- *
- *	Tell the collector about a deadlock detected.
- * --------
+/*
+ * Tell the collector about a deadlock detected.
  */
 void
 pgstat_report_deadlock(void)
@@ -96,11 +87,8 @@ pgstat_report_deadlock(void)
 	pgstat_send(&msg, sizeof(msg));
 }
 
-/* --------
- * pgstat_report_checksum_failures_in_db() -
- *
- *	Tell the collector about one or more checksum failures.
- * --------
+/*
+ * Tell the collector about one or more checksum failures.
  */
 void
 pgstat_report_checksum_failures_in_db(Oid dboid, int failurecount)
@@ -118,11 +106,8 @@ pgstat_report_checksum_failures_in_db(Oid dboid, int failurecount)
 	pgstat_send(&msg, sizeof(msg));
 }
 
-/* --------
- * pgstat_report_checksum_failure() -
- *
- *	Tell the collector about a checksum failure.
- * --------
+/*
+ * Tell the collector about a checksum failure.
  */
 void
 pgstat_report_checksum_failure(void)
@@ -130,11 +115,8 @@ pgstat_report_checksum_failure(void)
 	pgstat_report_checksum_failures_in_db(MyDatabaseId, 1);
 }
 
-/* --------
- * pgstat_report_tempfile() -
- *
- *	Tell the collector about a temporary file.
- * --------
+/*
+ * Tell the collector about a temporary file.
  */
 void
 pgstat_report_tempfile(size_t filesize)
@@ -150,11 +132,8 @@ pgstat_report_tempfile(size_t filesize)
 	pgstat_send(&msg, sizeof(msg));
 }
 
-/* --------
- * pgstat_report_connect() -
- *
- *	Tell the collector about a new connection.
- * --------
+/*
+ * Tell the collector about a new connection.
  */
 void
 pgstat_report_connect(Oid dboid)
@@ -171,11 +150,8 @@ pgstat_report_connect(Oid dboid)
 	pgstat_send(&msg, sizeof(PgStat_MsgConnect));
 }
 
-/* --------
- * pgstat_report_disconnect() -
- *
- *	Tell the collector about a disconnect.
- * --------
+/*
+ * Tell the collector about a disconnect.
  */
 void
 pgstat_report_disconnect(Oid dboid)
@@ -262,15 +238,12 @@ pgstat_update_dbstats(PgStat_MsgTabstat *tsmsg, TimestampTz now)
 	}
 }
 
-/* --------
- * pgstat_should_report_connstats() -
- *
- *	We report session statistics only for normal backend processes.  Parallel
- *	workers run in parallel, so they don't contribute to session times, even
- *	though they use CPU time. Walsender processes could be considered here,
- *	but they have different session characteristics from normal backends (for
- *	example, they are always "active"), so they would skew session statistics.
- * ----------
+/*
+ * We report session statistics only for normal backend processes.  Parallel
+ * workers run in parallel, so they don't contribute to session times, even
+ * though they use CPU time. Walsender processes could be considered here,
+ * but they have different session characteristics from normal backends (for
+ * example, they are always "active"), so they would skew session statistics.
  */
 static bool
 pgstat_should_report_connstat(void)

src/backend/utils/activity/pgstat_function.c

@@ -206,8 +206,7 @@ pgstat_send_funcstats(void)
 }
 
 /*
- * find_funcstat_entry - find any existing PgStat_BackendFunctionEntry entry
- *		for specified function
+ * find any existing PgStat_BackendFunctionEntry entry for specified function
  *
  * If no entry, return NULL, don't create a new one
  */

src/backend/utils/activity/pgstat_relation.c

@@ -95,17 +95,14 @@ bool		have_relation_stats;
 static HTAB *pgStatTabHash = NULL;
 
 
-/* ----------
- * pgstat_relation_init() -
- *
- *	Initialize a relcache entry to count access statistics.
- *	Called whenever a relation is opened.
+/*
+ * Initialize a relcache entry to count access statistics.
+ * Called whenever a relation is opened.
  *
- *	We assume that a relcache entry's pgstat_info field is zeroed by
- *	relcache.c when the relcache entry is made; thereafter it is long-lived
- *	data.  We can avoid repeated searches of the TabStatus arrays when the
- *	same relation is touched repeatedly within a transaction.
- * ----------
+ * We assume that a relcache entry's pgstat_info field is zeroed by
+ * relcache.c when the relcache entry is made; thereafter it is long-lived
+ * data.  We can avoid repeated searches of the TabStatus arrays when the
+ * same relation is touched repeatedly within a transaction.
  */
 void
 pgstat_relation_init(Relation rel)
@@ -141,16 +138,13 @@ pgstat_relation_init(Relation rel)
 	rel->pgstat_info = get_tabstat_entry(rel_id, rel->rd_rel->relisshared);
 }
 
-/* ----------
- * pgstat_drop_relation() -
- *
- *	Tell the collector that we just dropped a relation.
- *	(If the message gets lost, we will still clean the dead entry eventually
- *	via future invocations of pgstat_vacuum_stat().)
+/*
+ * Tell the collector that we just dropped a relation.
+ * (If the message gets lost, we will still clean the dead entry eventually
+ * via future invocations of pgstat_vacuum_stat().)
  *
- *	Currently not used for lack of any good place to call it; we rely
- *	entirely on pgstat_vacuum_stat() to clean out stats for dead rels.
- * ----------
+ * Currently not used for lack of any good place to call it; we rely
+ * entirely on pgstat_vacuum_stat() to clean out stats for dead rels.
  */
 #ifdef NOT_USED
 void
@@ -173,13 +167,10 @@ pgstat_drop_relation(Oid relid)
 }
 #endif							/* NOT_USED */
 
-/* ----------
- * pgstat_report_autovac() -
- *
- *	Called from autovacuum.c to report startup of an autovacuum process.
- *	We are called before InitPostgres is done, so can't rely on MyDatabaseId;
- *	the db OID must be passed in, instead.
- * ----------
+/*
+ * Called from autovacuum.c to report startup of an autovacuum process.
+ * We are called before InitPostgres is done, so can't rely on MyDatabaseId;
+ * the db OID must be passed in, instead.
  */
 void
 pgstat_report_autovac(Oid dboid)
@@ -196,11 +187,8 @@ pgstat_report_autovac(Oid dboid)
 	pgstat_send(&msg, sizeof(msg));
 }
 
-/* ---------
- * pgstat_report_vacuum() -
- *
- *	Tell the collector about the table we just vacuumed.
- * ---------
+/*
+ * Tell the collector about the table we just vacuumed.
  */
 void
 pgstat_report_vacuum(Oid tableoid, bool shared,
@@ -221,14 +209,11 @@ pgstat_report_vacuum(Oid tableoid, bool shared,
 	pgstat_send(&msg, sizeof(msg));
 }
 
-/* --------
- * pgstat_report_analyze() -
- *
- *	Tell the collector about the table we just analyzed.
+/*
+ * Tell the collector about the table we just analyzed.
  *
  * Caller must provide new live- and dead-tuples estimates, as well as a
  * flag indicating whether to reset the changes_since_analyze counter.
- * --------
  */
 void
 pgstat_report_analyze(Relation rel,
@@ -281,7 +266,7 @@ pgstat_report_analyze(Relation rel,
 }
 
 /*
- * pgstat_count_heap_insert - count a tuple insertion of n tuples
+ * count a tuple insertion of n tuples
  */
 void
 pgstat_count_heap_insert(Relation rel, PgStat_Counter n)
@@ -296,7 +281,7 @@ pgstat_count_heap_insert(Relation rel, PgStat_Counter n)
 }
 
 /*
- * pgstat_count_heap_update - count a tuple update
+ * count a tuple update
  */
 void
 pgstat_count_heap_update(Relation rel, bool hot)
@@ -315,7 +300,7 @@ pgstat_count_heap_update(Relation rel, bool hot)
 }
 
 /*
- * pgstat_count_heap_delete - count a tuple deletion
+ * count a tuple deletion
  */
 void
 pgstat_count_heap_delete(Relation rel)
@@ -330,7 +315,7 @@ pgstat_count_heap_delete(Relation rel)
 }
 
 /*
- * pgstat_count_truncate - update tuple counters due to truncate
+ * update tuple counters due to truncate
  */
 void
 pgstat_count_truncate(Relation rel)
@@ -348,7 +333,7 @@ pgstat_count_truncate(Relation rel)
 }
 
 /*
- * pgstat_update_heap_dead_tuples - update dead-tuples count
+ * update dead-tuples count
  *
  * The semantics of this are that we are reporting the nontransactional
  * recovery of "delta" dead tuples; so t_delta_dead_tuples decreases
@@ -367,7 +352,7 @@ pgstat_update_heap_dead_tuples(Relation rel, int delta)
 }
 
 /*
- * find_tabstat_entry - find any existing PgStat_TableStatus entry for rel
+ * find any existing PgStat_TableStatus entry for rel
  *
  * If no entry, return NULL, don't create a new one
  *
@@ -772,7 +757,7 @@ pgstat_send_tabstat(PgStat_MsgTabstat *tsmsg, TimestampTz now)
 }
 
 /*
- * get_tabstat_entry - find or create a PgStat_TableStatus entry for rel
+ * find or create a PgStat_TableStatus entry for rel
  */
 static PgStat_TableStatus *
 get_tabstat_entry(Oid rel_id, bool isshared)
@@ -858,7 +843,7 @@ get_tabstat_entry(Oid rel_id, bool isshared)
 }
 
 /*
- * add_tabstat_xact_level - add a new (sub)transaction state record
+ * add a new (sub)transaction state record
  */
 static void
 add_tabstat_xact_level(PgStat_TableStatus *pgstat_info, int nest_level)
@@ -898,8 +883,6 @@ ensure_tabstat_xact_level(PgStat_TableStatus *pgstat_info)
 }
 
 /*
- * pgstat_truncdrop_save_counters
- *
  * Whenever a table is truncated/dropped, we save its i/u/d counters so that
  * they can be cleared, and if the (sub)xact that executed the truncate/drop
  * later aborts, the counters can be restored to the saved (pre-truncate/drop)
@@ -921,7 +904,7 @@ pgstat_truncdrop_save_counters(PgStat_TableXactStatus *trans, bool is_drop)
 }
 
 /*
- * pgstat_truncdrop_restore_counters - restore counters when a truncate aborts
+ * restore counters when a truncate aborts
  */
 static void
 pgstat_truncdrop_restore_counters(PgStat_TableXactStatus *trans)

src/backend/utils/activity/pgstat_replslot.c

@@ -22,15 +22,12 @@
 #include "utils/pgstat_internal.h"
 
 
-/* ----------
- * pgstat_reset_replslot_counter() -
+/*
+ * Tell the statistics collector to reset a single replication slot
+ * counter, or all replication slots counters (when name is null).
  *
- *	Tell the statistics collector to reset a single replication slot
- *	counter, or all replication slots counters (when name is null).
- *
- *	Permission checking for this function is managed through the normal
- *	GRANT system.
- * ----------
+ * Permission checking for this function is managed through the normal
+ * GRANT system.
  */
 void
 pgstat_reset_replslot_counter(const char *name)
@@ -53,11 +50,8 @@ pgstat_reset_replslot_counter(const char *name)
 	pgstat_send(&msg, sizeof(msg));
 }
 
-/* ----------
- * pgstat_report_replslot() -
- *
- *	Tell the collector about replication slot statistics.
- * ----------
+/*
+ * Tell the collector about replication slot statistics.
  */
 void
 pgstat_report_replslot(const PgStat_StatReplSlotEntry *repSlotStat)
@@ -82,11 +76,8 @@ pgstat_report_replslot(const PgStat_StatReplSlotEntry *repSlotStat)
 	pgstat_send(&msg, sizeof(PgStat_MsgReplSlot));
 }
 
-/* ----------
- * pgstat_report_replslot_create() -
- *
- *	Tell the collector about creating the replication slot.
- * ----------
+/*
+ * Tell the collector about creating the replication slot.
  */
 void
 pgstat_report_replslot_create(const char *slotname)
@@ -100,11 +91,8 @@ pgstat_report_replslot_create(const char *slotname)
 	pgstat_send(&msg, sizeof(PgStat_MsgReplSlot));
 }
 
-/* ----------
- * pgstat_report_replslot_drop() -
- *
- *	Tell the collector about dropping the replication slot.
- * ----------
+/*
+ * Tell the collector about dropping the replication slot.
  */
 void
 pgstat_report_replslot_drop(const char *slotname)

src/backend/utils/activity/pgstat_slru.c

@@ -32,15 +32,12 @@ static inline PgStat_MsgSLRU *slru_entry(int slru_idx);
 static PgStat_MsgSLRU SLRUStats[SLRU_NUM_ELEMENTS];
 
 
-/* ----------
- * pgstat_reset_slru_counter() -
- *
- *	Tell the statistics collector to reset a single SLRU counter, or all
- *	SLRU counters (when name is null).
+/*
+ * Tell the statistics collector to reset a single SLRU counter, or all
+ * SLRU counters (when name is null).
  *
- *	Permission checking for this function is managed through the normal
- *	GRANT system.
- * ----------
+ * Permission checking for this function is managed through the normal
+ * GRANT system.
  */
 void
 pgstat_reset_slru_counter(const char *name)
@@ -103,8 +100,6 @@ pgstat_count_slru_truncate(int slru_idx)
 }
 
 /*
- * pgstat_slru_name
- *
  * Returns SLRU name for an index. The index may be above SLRU_NUM_ELEMENTS,
  * in which case this returns NULL. This allows writing code that does not
  * know the number of entries in advance.
@@ -119,8 +114,6 @@ pgstat_slru_name(int slru_idx)
 }
 
 /*
- * pgstat_slru_index
- *
  * Determine index of entry for a SLRU with a given name. If there's no exact
  * match, returns index of the last "other" entry used for SLRUs defined in
  * external projects.
@@ -140,11 +133,8 @@ pgstat_slru_index(const char *name)
 	return (SLRU_NUM_ELEMENTS - 1);
 }
 
-/* ----------
- * pgstat_send_slru() -
- *
- *		Send SLRU statistics to the collector
- * ----------
+/*
+ * Send SLRU statistics to the collector
  */
 void
 pgstat_send_slru(void)
@@ -179,8 +169,6 @@ pgstat_send_slru(void)
 }
 
 /*
- * slru_entry
- *
  * Returns pointer to entry with counters for given SLRU (based on the name
  * stored in SlruCtl as lwlock tranche name).
  */

src/backend/utils/activity/pgstat_subscription.c

@@ -20,15 +20,12 @@
 #include "utils/pgstat_internal.h"
 
 
-/* ----------
- * pgstat_reset_subscription_counter() -
+/*
+ * Tell the statistics collector to reset a single subscription
+ * counter, or all subscription counters (when subid is InvalidOid).
  *
- *	Tell the statistics collector to reset a single subscription
- *	counter, or all subscription counters (when subid is InvalidOid).
- *
- *	Permission checking for this function is managed through the normal
- *	GRANT system.
- * ----------
+ * Permission checking for this function is managed through the normal
+ * GRANT system.
  */
 void
 pgstat_reset_subscription_counter(Oid subid)
@@ -44,11 +41,8 @@ pgstat_reset_subscription_counter(Oid subid)
 	pgstat_send(&msg, sizeof(msg));
 }
 
-/* ----------
- * pgstat_report_subscription_error() -
- *
- *	Tell the collector about the subscription error.
- * ----------
+/*
+ * Tell the collector about the subscription error.
  */
 void
 pgstat_report_subscription_error(Oid subid, bool is_apply_error)
@@ -61,11 +55,8 @@ pgstat_report_subscription_error(Oid subid, bool is_apply_error)
 	pgstat_send(&msg, sizeof(PgStat_MsgSubscriptionError));
 }
 
-/* ----------
- * pgstat_report_subscription_drop() -
- *
- *	Tell the collector about dropping the subscription.
- * ----------
+/*
+ * Tell the collector about dropping the subscription.
  */
 void
 pgstat_report_subscription_drop(Oid subid)

src/backend/utils/activity/pgstat_wal.c

@@ -38,14 +38,11 @@ PgStat_MsgWal WalStats;
 static WalUsage prevWalUsage;
 
 
-/* ----------
- * pgstat_send_wal() -
- *
- *	Send WAL statistics to the collector.
+/*
+ * Send WAL statistics to the collector.
  *
  * If 'force' is not set, WAL stats message is only sent if enough time has
  * passed since last one was sent to reach PGSTAT_STAT_INTERVAL.
- * ----------
  */
 void
 pgstat_send_wal(bool force)