Rename debug_invalidate_system_caches_always to debug_discard_caches.

The name introduced by commit 4656e3d was agreed to be unreasonably
long.  To match this change, rename initdb's recently-added
--clobber-cache option to --discard-caches.

Discussion: https://postgr.es/m/1374320.1625430433@sss.pgh.pa.us

Author: tglsfdc

contrib/postgres_fdw/expected/postgres_fdw.out

@@ -9340,11 +9340,11 @@ WARNING:  there is no transaction in progress
 -- Change application_name of remote connection to special one
 -- so that we can easily terminate the connection later.
 ALTER SERVER loopback OPTIONS (application_name 'fdw_retry_check');
--- If debug_invalidate_system_caches_always is active, it results in
+-- If debug_discard_caches is active, it results in
 -- dropping remote connections after every transaction, making it
 -- impossible to test termination meaningfully.  So turn that off
 -- for this test.
-SET debug_invalidate_system_caches_always = 0;
+SET debug_discard_caches = 0;
 -- Make sure we have a remote connection.
 SELECT 1 FROM ft1 LIMIT 1;
  ?column? 
@@ -9386,7 +9386,7 @@ SELECT 1 FROM ft1 LIMIT 1;    -- should fail
 ERROR:  08006
 \set VERBOSITY default
 COMMIT;
-RESET debug_invalidate_system_caches_always;
+RESET debug_discard_caches;
 -- =============================================================================
 -- test connection invalidation cases and postgres_fdw_get_connections function
 -- =============================================================================

contrib/postgres_fdw/sql/postgres_fdw.sql

@@ -2831,11 +2831,11 @@ ROLLBACK;
 -- so that we can easily terminate the connection later.
 ALTER SERVER loopback OPTIONS (application_name 'fdw_retry_check');
 
--- If debug_invalidate_system_caches_always is active, it results in
+-- If debug_discard_caches is active, it results in
 -- dropping remote connections after every transaction, making it
 -- impossible to test termination meaningfully.  So turn that off
 -- for this test.
-SET debug_invalidate_system_caches_always = 0;
+SET debug_discard_caches = 0;
 
 -- Make sure we have a remote connection.
 SELECT 1 FROM ft1 LIMIT 1;
@@ -2861,7 +2861,7 @@ SELECT 1 FROM ft1 LIMIT 1;    -- should fail
 \set VERBOSITY default
 COMMIT;
 
-RESET debug_invalidate_system_caches_always;
+RESET debug_discard_caches;
 
 -- =============================================================================
 -- test connection invalidation cases and postgres_fdw_get_connections function

doc/src/sgml/config.sgml

@@ -10341,10 +10341,10 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
       </listitem>
      </varlistentry>
 
-     <varlistentry id="guc-debug-invalidate-system-caches-always" xreflabel="debug_invalidate_system_caches_always">
-      <term><varname>debug_invalidate_system_caches_always</varname> (<type>integer</type>)
+     <varlistentry id="guc-debug-discard-caches" xreflabel="debug_discard_caches">
+      <term><varname>debug_discard_caches</varname> (<type>integer</type>)
       <indexterm>
-       <primary><varname>debug_invalidate_system_caches_always</varname> configuration parameter</primary>
+       <primary><varname>debug_discard_caches</varname> configuration parameter</primary>
       </indexterm>
       </term>
       <listitem>
@@ -10369,7 +10369,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
 
        <para>
         This parameter is supported when
-        <symbol>CLOBBER_CACHE_ENABLED</symbol> was defined at compile time
+        <symbol>DISCARD_CACHES_ENABLED</symbol> was defined at compile time
         (which happens automatically when using the
         <application>configure</application> option
         <option>--enable-cassert</option>).  In production builds, its value

doc/src/sgml/ref/initdb.sgml

@@ -388,17 +388,6 @@ PostgreSQL documentation
     Other, less commonly used, options are also available:
 
     <variablelist>
-     <varlistentry>
-      <term><option>--clobber-cache</option></term>
-      <listitem>
-       <para>
-        Run the bootstrap backend with the
-        <literal>debug_invalidate_system_caches_always=1</literal> option.
-        This takes a very long time and is only of use for deep debugging.
-       </para>
-      </listitem>
-     </varlistentry>
-
      <varlistentry>
       <term><option>-d</option></term>
       <term><option>--debug</option></term>
@@ -413,6 +402,17 @@ PostgreSQL documentation
       </listitem>
      </varlistentry>
 
+     <varlistentry>
+      <term><option>--discard-caches</option></term>
+      <listitem>
+       <para>
+        Run the bootstrap backend with the
+        <literal>debug_discard_caches=1</literal> option.
+        This takes a very long time and is only of use for deep debugging.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry>
       <term><option>-L <replaceable class="parameter">directory</replaceable></option></term>
       <listitem>

doc/src/sgml/regress.sgml

@@ -373,7 +373,7 @@ make check EXTRA_REGRESS_OPTS="--temp-config=test_postgresql.conf"
    <para>
     This can be useful to enable additional logging, adjust resource limits,
     or enable extra run-time checks such as <xref
-    linkend="guc-debug-invalidate-system-caches-always"/>.
+    linkend="guc-debug-discard-caches"/>.
    </para>
   </sect2>
 

src/backend/utils/adt/lockfuncs.c

@@ -636,10 +636,10 @@ pg_isolation_test_session_is_blocked(PG_FUNCTION_ARGS)
 	 * Check if any of these are in the list of interesting PIDs, that being
 	 * the sessions that the isolation tester is running.  We don't use
 	 * "arrayoverlaps" here, because it would lead to cache lookups and one of
-	 * our goals is to run quickly with debug_invalidate_system_caches_always
-	 * > 0.  We expect blocking_pids to be usually empty and otherwise a very
-	 * small number in isolation tester cases, so make that the outer loop of
-	 * a naive search for a match.
+	 * our goals is to run quickly with debug_discard_caches > 0.  We expect
+	 * blocking_pids to be usually empty and otherwise a very small number in
+	 * isolation tester cases, so make that the outer loop of a naive search
+	 * for a match.
 	 */
 	for (i = 0; i < num_blocking_pids; i++)
 		for (j = 0; j < num_interesting_pids; j++)

src/backend/utils/cache/inval.c

@@ -182,7 +182,7 @@ static int	numSharedInvalidMessagesArray;
 static int	maxSharedInvalidMessagesArray;
 
 /* GUC storage */
-int			debug_invalidate_system_caches_always = 0;
+int			debug_discard_caches = 0;
 
 /*
  * Dynamically-registered callback functions.  Current implementation
@@ -690,36 +690,36 @@ AcceptInvalidationMessages(void)
 	ReceiveSharedInvalidMessages(LocalExecuteInvalidationMessage,
 								 InvalidateSystemCaches);
 
-	/*
+	/*----------
 	 * Test code to force cache flushes anytime a flush could happen.
 	 *
 	 * This helps detect intermittent faults caused by code that reads a cache
 	 * entry and then performs an action that could invalidate the entry, but
 	 * rarely actually does so.  This can spot issues that would otherwise
 	 * only arise with badly timed concurrent DDL, for example.
 	 *
-	 * The default debug_invalidate_system_caches_always = 0 does no forced
-	 * cache flushes.
+	 * The default debug_discard_caches = 0 does no forced cache flushes.
 	 *
 	 * If used with CLOBBER_FREED_MEMORY,
-	 * debug_invalidate_system_caches_always = 1 (CLOBBER_CACHE_ALWAYS)
+	 * debug_discard_caches = 1 (formerly known as CLOBBER_CACHE_ALWAYS)
 	 * provides a fairly thorough test that the system contains no cache-flush
 	 * hazards.  However, it also makes the system unbelievably slow --- the
 	 * regression tests take about 100 times longer than normal.
 	 *
 	 * If you're a glutton for punishment, try
-	 * debug_invalidate_system_caches_always = 3 (CLOBBER_CACHE_RECURSIVELY).
+	 * debug_discard_caches = 3 (formerly known as CLOBBER_CACHE_RECURSIVELY).
 	 * This slows things by at least a factor of 10000, so I wouldn't suggest
 	 * trying to run the entire regression tests that way.  It's useful to try
 	 * a few simple tests, to make sure that cache reload isn't subject to
 	 * internal cache-flush hazards, but after you've done a few thousand
 	 * recursive reloads it's unlikely you'll learn more.
+	 *----------
 	 */
-#ifdef CLOBBER_CACHE_ENABLED
+#ifdef DISCARD_CACHES_ENABLED
 	{
 		static int	recursion_depth = 0;
 
-		if (recursion_depth < debug_invalidate_system_caches_always)
+		if (recursion_depth < debug_discard_caches)
 		{
 			recursion_depth++;
 			InvalidateSystemCaches();

src/backend/utils/cache/plancache.c

@@ -897,9 +897,8 @@ BuildCachedPlan(CachedPlanSource *plansource, List *qlist,
 	 * rejected a generic plan, it's possible to reach here with is_valid
 	 * false due to an invalidation while making the generic plan.  In theory
 	 * the invalidation must be a false positive, perhaps a consequence of an
-	 * sinval reset event or the debug_invalidate_system_caches_always code.
-	 * But for safety, let's treat it as real and redo the
-	 * RevalidateCachedQuery call.
+	 * sinval reset event or the debug_discard_caches code.  But for safety,
+	 * let's treat it as real and redo the RevalidateCachedQuery call.
 	 */
 	if (!plansource->is_valid)
 		qlist = RevalidateCachedQuery(plansource, queryEnv);

src/backend/utils/cache/relcache.c

@@ -97,7 +97,7 @@
 #define MAYBE_RECOVER_RELATION_BUILD_MEMORY 1
 #else
 #define RECOVER_RELATION_BUILD_MEMORY 0
-#ifdef CLOBBER_CACHE_ENABLED
+#ifdef DISCARD_CACHES_ENABLED
 #define MAYBE_RECOVER_RELATION_BUILD_MEMORY 1
 #endif
 #endif
@@ -1011,10 +1011,10 @@ RelationBuildDesc(Oid targetRelId, bool insertIt)
 	 * data, reasoning that the caller's context is at worst of transaction
 	 * scope, and relcache loads shouldn't happen so often that it's essential
 	 * to recover transient data before end of statement/transaction.  However
-	 * that's definitely not true in clobber-cache test builds, and perhaps
-	 * it's not true in other cases.
+	 * that's definitely not true when debug_discard_caches is active, and
+	 * perhaps it's not true in other cases.
 	 *
-	 * When cache clobbering is enabled or when forced to by
+	 * When debug_discard_caches is active or when forced to by
 	 * RECOVER_RELATION_BUILD_MEMORY=1, arrange to allocate the junk in a
 	 * temporary context that we'll free before returning.  Make it a child of
 	 * caller's context so that it will get cleaned up appropriately if we
@@ -1024,7 +1024,7 @@ RelationBuildDesc(Oid targetRelId, bool insertIt)
 	MemoryContext tmpcxt = NULL;
 	MemoryContext oldcxt = NULL;
 
-	if (RECOVER_RELATION_BUILD_MEMORY || debug_invalidate_system_caches_always > 0)
+	if (RECOVER_RELATION_BUILD_MEMORY || debug_discard_caches > 0)
 	{
 		tmpcxt = AllocSetContextCreate(CurrentMemoryContext,
 									   "RelationBuildDesc workspace",
@@ -1627,11 +1627,10 @@ LookupOpclassInfo(Oid operatorClassOid,
 	 * otherwise.  However it can be helpful for detecting bugs in the cache
 	 * loading logic itself, such as reliance on a non-nailed index.  Given
 	 * the limited use-case and the fact that this adds a great deal of
-	 * expense, we enable it only for high values of
-	 * debug_invalidate_system_caches_always.
+	 * expense, we enable it only for high values of debug_discard_caches.
 	 */
-#ifdef CLOBBER_CACHE_ENABLED
-	if (debug_invalidate_system_caches_always > 2)
+#ifdef DISCARD_CACHES_ENABLED
+	if (debug_discard_caches > 2)
 		opcentry->valid = false;
 #endif
 

src/backend/utils/misc/guc.c

@@ -3513,13 +3513,13 @@ static struct config_int ConfigureNamesInt[] =
 	},
 
 	{
-		{"debug_invalidate_system_caches_always", PGC_SUSET, DEVELOPER_OPTIONS,
-			gettext_noop("Aggressively invalidate system caches for debugging purposes."),
+		{"debug_discard_caches", PGC_SUSET, DEVELOPER_OPTIONS,
+			gettext_noop("Aggressively flush system caches for debugging purposes."),
 			NULL,
 			GUC_NOT_IN_SAMPLE
 		},
-		&debug_invalidate_system_caches_always,
-#ifdef CLOBBER_CACHE_ENABLED
+		&debug_discard_caches,
+#ifdef DISCARD_CACHES_ENABLED
 		/* Set default based on older compile-time-only cache clobber macros */
 #if defined(CLOBBER_CACHE_RECURSIVELY)
 		3,
@@ -3529,9 +3529,9 @@ static struct config_int ConfigureNamesInt[] =
 		0,
 #endif
 		0, 5,
-#else							/* not CLOBBER_CACHE_ENABLED */
+#else							/* not DISCARD_CACHES_ENABLED */
 		0, 0, 0,
-#endif							/* not CLOBBER_CACHE_ENABLED */
+#endif							/* not DISCARD_CACHES_ENABLED */
 		NULL, NULL, NULL
 	},