Rename debug_invalidate_system_caches_always to debug_discard_caches.

tglsfdc · tglsfdc · commit d68a00391214 · 2021-07-13T15:01:01.000-04:00
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
diff --git a/contrib/postgres_fdw/expected/postgres_fdw.out b/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
 -- =============================================================================
diff --git a/contrib/postgres_fdw/sql/postgres_fdw.sql b/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
diff --git a/doc/src/sgml/config.sgml b/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
diff --git a/doc/src/sgml/ref/initdb.sgml b/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>
diff --git a/doc/src/sgml/regress.sgml b/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>
 
diff --git a/src/backend/utils/adt/lockfuncs.c b/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++)
diff --git a/src/backend/utils/cache/inval.c b/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();
diff --git a/src/backend/utils/cache/plancache.c b/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);
diff --git a/src/backend/utils/cache/relcache.c b/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
 
diff --git a/src/backend/utils/misc/guc.c b/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
 	},
 
diff --git a/src/bin/initdb/initdb.c b/src/bin/initdb/initdb.c
@@ -2266,8 +2266,8 @@ usage(const char *progname)
 	printf(_("  -X, --waldir=WALDIR       location for the write-ahead log directory\n"));
 	printf(_("      --wal-segsize=SIZE    size of WAL segments, in megabytes\n"));
 	printf(_("\nLess commonly used options:\n"));
-	printf(_("      --clobber-cache       use cache-clobbering debug option\n"));
 	printf(_("  -d, --debug               generate lots of debugging output\n"));
+	printf(_("      --discard-caches      set debug_discard_caches=1\n"));
 	printf(_("  -L DIRECTORY              where to find the input files\n"));
 	printf(_("  -n, --no-clean            do not clean up after errors\n"));
 	printf(_("  -N, --no-sync             do not wait for changes to be written safely to disk\n"));
@@ -2947,7 +2947,7 @@ main(int argc, char *argv[])
 		{"wal-segsize", required_argument, NULL, 12},
 		{"data-checksums", no_argument, NULL, 'k'},
 		{"allow-group-access", no_argument, NULL, 'g'},
-		{"clobber-cache", no_argument, NULL, 14},
+		{"discard-caches", no_argument, NULL, 14},
 		{NULL, 0, NULL, 0}
 	};
 
@@ -3092,7 +3092,7 @@ main(int argc, char *argv[])
 			case 14:
 				extra_options = psprintf("%s %s",
 										 extra_options,
-										 "-c debug_invalidate_system_caches_always=1");
+										 "-c debug_discard_caches=1");
 				break;
 			default:
 				/* getopt_long already emitted a complaint */
diff --git a/src/include/pg_config_manual.h b/src/include/pg_config_manual.h
@@ -322,36 +322,36 @@
 /* #define RANDOMIZE_ALLOCATED_MEMORY */
 
 /*
- * For cache invalidation debugging, define CLOBBER_CACHE_ENABLED to enable
- * use of the debug_invalidate_system_caches_always GUC to aggressively flush
- * syscache/relcache entries whenever it's possible to deliver invalidations.
- * See AcceptInvalidationMessages() in src/backend/utils/cache/inval.c for
+ * For cache-invalidation debugging, define DISCARD_CACHES_ENABLED to enable
+ * use of the debug_discard_caches GUC to aggressively flush syscache/relcache
+ * entries whenever it's possible to deliver invalidations.  See
+ * AcceptInvalidationMessages() in src/backend/utils/cache/inval.c for
  * details.
  *
  * USE_ASSERT_CHECKING builds default to enabling this.  It's possible to use
- * CLOBBER_CACHE_ENABLED without a cassert build and the implied
- * CLOBBER_FREED_MEMORY and MEMORY_CONTEXT_CHECKING options but it's unlikely
+ * DISCARD_CACHES_ENABLED without a cassert build and the implied
+ * CLOBBER_FREED_MEMORY and MEMORY_CONTEXT_CHECKING options, but it's unlikely
  * to be as effective at identifying problems.
  */
-/* #define CLOBBER_CACHE_ENABLED */
+/* #define DISCARD_CACHES_ENABLED */
 
-#if defined(USE_ASSERT_CHECKING) && !defined(CLOBBER_CACHE_ENABLED)
-#define CLOBBER_CACHE_ENABLED
+#if defined(USE_ASSERT_CHECKING) && !defined(DISCARD_CACHES_ENABLED)
+#define DISCARD_CACHES_ENABLED
 #endif
 
 /*
- * Backwards compatibility for the older compile-time-only cache clobber
+ * Backwards compatibility for the older compile-time-only clobber-cache
  * macros.
  */
-#if !defined(CLOBBER_CACHE_ENABLED) && (defined(CLOBBER_CACHE_ALWAYS) || defined(CLOBBER_CACHE_RECURSIVELY))
-#define CLOBBER_CACHE_ENABLED
+#if !defined(DISCARD_CACHES_ENABLED) && (defined(CLOBBER_CACHE_ALWAYS) || defined(CLOBBER_CACHE_RECURSIVELY))
+#define DISCARD_CACHES_ENABLED
 #endif
 
 /*
  * Recover memory used for relcache entries when invalidated.  See
  * RelationBuildDescr() in src/backend/utils/cache/relcache.c.
  *
- * This is active automatically for clobber cache builds when clobbering is
+ * This is active automatically for clobber-cache builds when clobbering is
  * active, but can be overridden here by explicitly defining
  * RECOVER_RELATION_BUILD_MEMORY.  Define to 1 to always free relation cache
  * memory even when clobber is off, or to 0 to never free relation cache
diff --git a/src/include/utils/inval.h b/src/include/utils/inval.h
@@ -18,7 +18,7 @@
 #include "storage/relfilenode.h"
 #include "utils/relcache.h"
 
-extern PGDLLIMPORT int debug_invalidate_system_caches_always;
+extern PGDLLIMPORT int debug_discard_caches;
 
 typedef void (*SyscacheCallbackFunction) (Datum arg, int cacheid, uint32 hashvalue);
 typedef void (*RelcacheCallbackFunction) (Datum arg, Oid relid);
diff --git a/src/pl/plpgsql/src/expected/plpgsql_cache.out b/src/pl/plpgsql/src/expected/plpgsql_cache.out
@@ -3,10 +3,10 @@
 --
 -- These tests logically belong in plpgsql_record.sql, and perhaps someday
 -- can be merged back into it.  For now, however, their results are different
--- depending on debug_invalidate_system_caches_always, so we must have two
--- expected-output files to cover both cases.  To minimize the maintenance
--- effort resulting from that, this file should contain only tests that
--- do have different results under debug_invalidate_system_caches_always.
+-- depending on debug_discard_caches, so we must have two expected-output
+-- files to cover both cases.  To minimize the maintenance effort resulting
+-- from that, this file should contain only tests that do have different
+-- results under debug_discard_caches.
 --
 -- check behavior with changes of a named rowtype
 create table c_mutable(f1 int, f2 text);
@@ -21,7 +21,7 @@ select c_sillyaddone(42);
 alter table c_mutable drop column f1;
 alter table c_mutable add column f1 float8;
 -- currently, this fails due to cached plan for "r.f1 + 1" expression
--- (but if debug_invalidate_system_caches_always is on, it will succeed)
+-- (but if debug_discard_caches is on, it will succeed)
 select c_sillyaddone(42);
 ERROR:  type of parameter 4 (double precision) does not match that when preparing the plan (integer)
 CONTEXT:  PL/pgSQL function c_sillyaddone(integer) line 1 at RETURN
@@ -52,7 +52,7 @@ select show_result_type('select 1 as a');
 (1 row)
 
 -- currently this fails due to cached plan for pg_typeof expression
--- (but if debug_invalidate_system_caches_always is on, it will succeed)
+-- (but if debug_discard_caches is on, it will succeed)
 select show_result_type('select 2.0 as a');
 ERROR:  type of parameter 5 (numeric) does not match that when preparing the plan (integer)
 CONTEXT:  SQL statement "select pg_typeof(r.a)"
diff --git a/src/pl/plpgsql/src/expected/plpgsql_cache_1.out b/src/pl/plpgsql/src/expected/plpgsql_cache_1.out
diff --git a/src/pl/plpgsql/src/expected/plpgsql_record.out b/src/pl/plpgsql/src/expected/plpgsql_record.out
diff --git a/src/pl/plpgsql/src/sql/plpgsql_cache.sql b/src/pl/plpgsql/src/sql/plpgsql_cache.sql
diff --git a/src/pl/plpgsql/src/sql/plpgsql_record.sql b/src/pl/plpgsql/src/sql/plpgsql_record.sql
diff --git a/src/test/isolation/specs/deadlock-soft-2.spec b/src/test/isolation/specs/deadlock-soft-2.spec
