Mps sort out baroque check macros (mainly config.h and check.h)

See job001248.  Should be source-only change.  Details:

  CheckNONE,SHALLOW,DEEP -->> CheckLevelMINIMAL,SHALLOW,DEEP
  [PROD_]CHECK_DEFAULT -->> [PROD_]CHECKLEVEL_INITIAL
  CHECK[_NONE] -->> AVER_AND_CHECK[_NONE]

And add some comments.

Copied from Perforce
 Change: 161210
 ServerID: perforce.ravenbrook.com

5 files changed, 59 insertions, 42 deletions

diff --git a/mps/code/check.h b/mps/code/check.h
index 6fbc609a0cf..f5681e0bb71 100644
--- a/mps/code/check.h
+++ b/mps/code/check.h
@@ -32,9 +32,12 @@
 extern unsigned CheckLevel;
 
 enum {
-  CheckNONE = 0,
-  CheckSHALLOW = 1,
-  CheckDEEP = 2
+  CheckLevelMINIMAL = 0,  /* local sig check only */
+  CheckLevelSHALLOW = 1,  /* local invariants, */
+                          /* and adjacent (up, down) sig checks */
+  CheckLevelDEEP = 2      /* local invariants, */
+                          /* and adjacent up sig checks */
+                          /* and recursive down full type checks */
 };
 
 
@@ -43,25 +46,25 @@ enum {
  * AVER and AVERT are used to assert conditions in the code.
  */
 
-#if defined(CHECK_NONE)
+#if defined(AVER_AND_CHECK_NONE)
 
 #define AVER(cond)                  DISCARD(cond)
 #define AVERT(type, val)            DISCARD(type ## Check(val))
 #define AVER_CRITICAL(cond)         DISCARD(cond)
 #define AVERT_CRITICAL(type, val)   DISCARD(type ## Check(val))
 
-#elif defined(CHECK)
+#elif defined(AVER_AND_CHECK)
 
 #define AVER(cond)                  ASSERT(cond, #cond)
 #define AVERT(type, val)            ASSERT(type ## Check(val), \
                                            "TypeCheck " #type ": " #val)
 #define AVER_CRITICAL(cond) \
   BEGIN \
-    if (CheckLevel != CheckNONE) ASSERT(cond, #cond); \
+    if (CheckLevel != CheckLevelMINIMAL) ASSERT(cond, #cond); \
   END
 #define AVERT_CRITICAL(type, val) \
   BEGIN \
-    if (CheckLevel != CheckNONE) \
+    if (CheckLevel != CheckLevelMINIMAL) \
       ASSERT(type ## Check(val), "TypeCheck " #type ": " #val); \
   END
 
@@ -82,8 +85,9 @@ enum {
 
 
 /* NOTREACHED -- control should never reach this statement */
+/* This is a sort of AVER; it is equivalent to AVER(FALSE). */
 
-#if defined(CHECK)
+#if defined(AVER_AND_CHECK)
 
 #define NOTREACHED \
   BEGIN \
@@ -101,12 +105,15 @@ enum {
  *
  * Must be thread safe.  See <design/interface-c/#thread-safety>
  * and <design/interface-c/#check.space>.
+ *
+ * @@@@ This is a test, not a CHECK macro -- it does not assert.
+ * It should be renamed MATCHSIG.  RHSK 2006-12-13.
  */
 
 #define CHECKT(type, val)       ((val) != NULL && (val)->sig == type ## Sig)
 
 
-#if defined(CHECK_NONE)
+#if defined(AVER_AND_CHECK_NONE)
 
 
 #define CHECKS(type, val) DISCARD(CHECKT(type, val))
@@ -121,6 +128,7 @@ enum {
 
 
 /* CHECKS -- Check Signature */
+/* (if CheckLevel == CheckLevelMINIMAL, this is all we check) */
 
 #define CHECKS(type, val)       ASSERT(CHECKT(type, val), \
                                        "SigCheck " #type ": " #val)
@@ -134,11 +142,11 @@ enum {
 #define CHECKL(cond) \
   BEGIN \
     switch(CheckLevel) { \
-    case CheckNONE: \
+    case CheckLevelMINIMAL: \
       NOOP; \
       break; \
-    case CheckSHALLOW: \
-    case CheckDEEP: \
+    case CheckLevelSHALLOW: \
+    case CheckLevelDEEP: \
       ASSERT(cond, #cond); \
       break; \
     } \
@@ -150,14 +158,14 @@ enum {
 #define CHECKD(type, val) \
   BEGIN \
     switch(CheckLevel) { \
-    case CheckNONE: \
+    case CheckLevelMINIMAL: \
       NOOP; \
       break; \
-    case CheckSHALLOW: \
+    case CheckLevelSHALLOW: \
       ASSERT(CHECKT(type, val), \
              "SigCheck " #type ": " #val); \
       break; \
-    case CheckDEEP: \
+    case CheckLevelDEEP: \
       ASSERT(type ## Check(val), \
              "TypeCheck " #type ": " #val); \
       break; \
@@ -170,14 +178,14 @@ enum {
 #define CHECKD_NOSIG(type, val) \
   BEGIN \
     switch(CheckLevel) { \
-    case CheckNONE: \
+    case CheckLevelMINIMAL: \
       NOOP; \
       break; \
-    case CheckSHALLOW: \
+    case CheckLevelSHALLOW: \
       ASSERT((val) != NULL, \
              "NullCheck " #type ": " #val); \
       break; \
-    case CheckDEEP: \
+    case CheckLevelDEEP: \
       ASSERT(type ## Check(val), \
              "TypeCheck " #type ": " #val); \
       break; \
@@ -190,11 +198,11 @@ enum {
 #define CHECKU(type, val) \
   BEGIN \
     switch(CheckLevel) { \
-    case CheckNONE: \
+    case CheckLevelMINIMAL: \
       NOOP; \
       break; \
-    case CheckSHALLOW: \
-    case CheckDEEP: \
+    case CheckLevelSHALLOW: \
+    case CheckLevelDEEP: \
       ASSERT(CHECKT(type, val), \
              "SigCheck " #type ": " #val); \
       break; \
@@ -207,11 +215,11 @@ enum {
 #define CHECKU_NOSIG(type, val) \
   BEGIN \
     switch(CheckLevel) { \
-    case CheckNONE: \
+    case CheckLevelMINIMAL: \
       NOOP; \
       break; \
-    case CheckSHALLOW: \
-    case CheckDEEP: \
+    case CheckLevelSHALLOW: \
+    case CheckLevelDEEP: \
       ASSERT((val) != NULL, \
              "NullCheck " #type ": " #val); \
       break; \
@@ -230,11 +238,16 @@ enum {
  * in knowing that <code/mps.h> matches the MPM.  See also
  * mail.richard.1996-08-07.09-49.  [This paragraph is intended to
  * satisfy rule.impl.trick.]
+ *
+ * @@@@ These are tests, not CHECK macros -- they do not assert.
+ * They should be renamed MATCHTYPE etc.  RHSK 2006-12-13.
  */
 
+/* compile-time check */
 #define CHECKLVALUE(lv1, lv2) \
   ((void)sizeof((lv1) = (lv2)), (void)sizeof((lv2) = (lv1)), TRUE)
 
+/* aims to test whether t1 and t2 are assignment-compatible */
 #define CHECKTYPE(t1, t2) \
   (sizeof(t1) == sizeof(t2) && \
    CHECKLVALUE(*((t1 *)0), *((t2 *)0)))
diff --git a/mps/code/config.h b/mps/code/config.h
index 971b2da8fe0..64f83b66c75 100644
--- a/mps/code/config.h
+++ b/mps/code/config.h
@@ -31,7 +31,7 @@
 
 #if defined(CONFIG_VAR_HI) || defined(CONFIG_VAR_HE) /* Hot varieties */
 #define CONFIG_DEBUG
-#define CHECK_DEFAULT CheckNONE
+#define CHECKLEVEL_INITIAL CheckLevelMINIMAL
 #elif defined(CONFIG_VAR_CI) || defined(CONFIG_VAR_CE) /* Cool varieties */
 #define CONFIG_DEBUG
 #define CONFIG_ASSERT
@@ -42,21 +42,23 @@
 #elif defined(CONFIG_VAR_II)    /* Ice, Internal; variety.ii */
 #define CONFIG_LOG
 #define CONFIG_DEBUG
-#define CHECK_DEFAULT CheckNONE
+#define CHECKLEVEL_INITIAL CheckLevelMINIMAL
 /* also CONFIG_VAR_WI and CONFIG_VAR_WE, for which all switches are off. */
 #endif
 
 
 #if defined(CONFIG_ASSERT)
-#define CHECK
+/* AVER, AVERT, NOTREACHED, CHECKx */
+#define AVER_AND_CHECK
 #define MPS_ASSERT_STRING "asserted"
 #else
-#define CHECK_NONE
+#define AVER_AND_CHECK_NONE
 #define MPS_ASSERT_STRING "nonasserted"
 #endif
 
 
 #if defined(CONFIG_LOG)
+/* TELEMETRY = LOG = EVENTs */
 #define EVENT
 #define MPS_LOG_STRING "logging"
 #else
@@ -66,6 +68,8 @@
 
 
 #if defined(CONFIG_DEBUG)
+/* DEBUG = DIAGNOSTICS = STATISTICs = METERs */
+/* WARNING: this changes the size and fields of MPS structs */
 #define DIAGNOSTICS
 #define MPS_DEBUG_STRING "debug"
 #else
@@ -125,7 +129,7 @@
  * are suddenly unused, etc.  We aren't interested in these
  */
 
-#if defined(CHECK_NONE)
+#if defined(AVER_AND_CHECK_NONE)
 
 /* "unreferenced formal parameter" */
 #pragma warning(disable: 4100)
@@ -133,7 +137,7 @@
 /* "unreferenced local function has been removed" */
 #pragma warning(disable: 4505)
 
-#endif /* CHECK_NONE */
+#endif /* AVER_AND_CHECK_NONE */
 
 #endif /* MPS_BUILD_MV */
 
@@ -267,7 +271,7 @@
 #define THREAD_SINGLE
 #define PROTECTION_NONE
 #define DONGLE_NONE
-#define PROD_CHECK_DEFAULT CheckNONE /* CheckSHALLOW is too slow for SW */
+#define PROD_CHECKLEVEL_INITIAL CheckLevelMINIMAL /* CheckLevelSHALLOW is too slow for SW */
 
 #elif defined(CONFIG_PROD_DYLAN)
 #define MPS_PROD_STRING         "dylan"
@@ -276,7 +280,7 @@
 #define THREAD_MULTI
 #define PROTECTION
 #define DONGLE_NONE
-#define PROD_CHECK_DEFAULT CheckSHALLOW
+#define PROD_CHECKLEVEL_INITIAL CheckLevelSHALLOW
 
 #elif defined(CONFIG_PROD_MPS)
 #define MPS_PROD_STRING         "mps"
@@ -285,7 +289,7 @@
 #define THREAD_MULTI
 #define PROTECTION
 #define DONGLE_NONE
-#define PROD_CHECK_DEFAULT CheckSHALLOW
+#define PROD_CHECKLEVEL_INITIAL CheckLevelSHALLOW
 
 #else
 #error "No target product configured."
@@ -299,11 +303,11 @@
  */
 #define ARENA_SIZE              ((Size)1<<30)
 
-/* if CHECK_DEFAULT hasn't been defined already (e.g. by a variety, or
+/* if CHECKLEVEL_INITIAL hasn't been defined already (e.g. by a variety, or
  * in a makefile), take the value from the product. */
 
-#ifndef CHECK_DEFAULT
-#define CHECK_DEFAULT PROD_CHECK_DEFAULT
+#ifndef CHECKLEVEL_INITIAL
+#define CHECKLEVEL_INITIAL PROD_CHECKLEVEL_INITIAL
 #endif
 
 
diff --git a/mps/code/mpm.c b/mps/code/mpm.c
index 247cbd05a56..3ce1aefe7ce 100644
--- a/mps/code/mpm.c
+++ b/mps/code/mpm.c
@@ -18,7 +18,7 @@
 SRCID(mpm, "$Id$");
 
 
-#if defined(CHECK)
+#if defined(AVER_AND_CHECK)
 
 
 /* CheckLevel -- Control check level 
@@ -26,7 +26,7 @@ SRCID(mpm, "$Id$");
  * This controls the behaviour of Check methods (see impl.h.check).
  */
 
-unsigned CheckLevel = CHECK_DEFAULT;
+unsigned CheckLevel = CHECKLEVEL_INITIAL;
 
 
 /* MPMCheck -- test MPM assumptions */
@@ -123,7 +123,7 @@ Bool AlignCheck(Align align)
 }
 
 
-#endif /* defined(CHECK) */
+#endif /* defined(AVER_AND_CHECK) */
 
 
 /* WordIsAligned -- test whether a word is aligned */
diff --git a/mps/code/splay.c b/mps/code/splay.c
index 388353b0849..7979af342c4 100644
--- a/mps/code/splay.c
+++ b/mps/code/splay.c
@@ -763,7 +763,7 @@ static Res SplayNodeDescribe(SplayNode node, mps_lib_FILE *stream,
                              SplayNodeDescribeMethod nodeDescribe) {
   Res res;
 
-#if defined(CHECK)
+#if defined(AVER_AND_CHECK)
   if (!SplayNodeCheck(node)) return ResFAIL;
   /* stream and nodeDescribe checked by SplayTreeDescribe */
 #endif
@@ -1005,7 +1005,7 @@ Res SplayTreeDescribe(SplayTree tree, mps_lib_FILE *stream,
                       SplayNodeDescribeMethod nodeDescribe) {
   Res res;
 
-#if defined(CHECK)
+#if defined(AVER_AND_CHECK)
   if (!SplayTreeCheck(tree)) return ResFAIL;
   if (stream == NULL) return ResFAIL;
   if (!FUNCHECK(nodeDescribe)) return ResFAIL;
diff --git a/mps/code/testlib.h b/mps/code/testlib.h
index 415aaaa8ded..94161adb58d 100644
--- a/mps/code/testlib.h
+++ b/mps/code/testlib.h
@@ -61,7 +61,7 @@
  * are suddenly unused, etc.  We aren't interested in these.
  */
 
-#if defined(CHECK_NONE)
+#if defined(AVER_AND_CHECK_NONE)
 
 /* "unreferenced formal parameter" */
 #pragma warning(disable: 4100)