From 0614b1e8272c550753ee199bb4db17231ee7ae51 Mon Sep 17 00:00:00 2001 From: Yves Orton Date: Mon, 10 Feb 2025 08:01:01 +0100 Subject: [PATCH] perl.h - rename PERL_DEB() to a more intuitive name This patch renames PERL_DEB() to PERL_IF_DEBUGGING() and renames PERL_DEB2() to PERL_IF_DEBUGGING_ELSE(). It also documents them, along with PERL_DEBUG() and DEBUG_r() and friends. I have switched the existing PERL_DEB() or PERL_DEB2() calls to use the new names, but kept aliases for the old names just in case they are used out in the wild (eg CPAN). Thanks to mauke for the name suggestions! --- perl.h | 94 ++++++++++++++++++++++++++++++++++++++++++++++++--- util.c | 2 +- win32/win32.c | 4 +-- 3 files changed, 92 insertions(+), 8 deletions(-) diff --git a/perl.h b/perl.h index ec8f9a379b27..25c19a492cd6 100644 --- a/perl.h +++ b/perl.h @@ -4922,8 +4922,8 @@ Gid_t getegid (void); # define DEBUG_Lv_TEST DEBUG_Lv_TEST_ # define DEBUG_yv_TEST DEBUG_yv_TEST_ -# define PERL_DEB(a) a -# define PERL_DEB2(a,b) a +# define PERL_IF_DEBUGGING(a) a +# define PERL_IF_DEBUGGING_ELSE(a,b) a # define PERL_DEBUG(a) if (PL_debug) a # define DEBUG_p(a) if (DEBUG_p_TEST) a # define DEBUG_s(a) if (DEBUG_s_TEST) a @@ -5051,8 +5051,8 @@ Gid_t getegid (void); # define DEBUG_Lv_TEST (0) # define DEBUG_yv_TEST (0) -# define PERL_DEB(a) -# define PERL_DEB2(a,b) b +# define PERL_IF_DEBUGGING(a) +# define PERL_IF_DEBUGGING_ELSE(a,b) b # define PERL_DEBUG(a) # define DEBUG_p(a) # define DEBUG_s(a) @@ -5088,6 +5088,90 @@ Gid_t getegid (void); #endif /* DEBUGGING */ +/* +=for apidoc_section $debugging +=for apidoc mu||PERL_IF_DEBUGGING|code + +A macro which is executed only when DEBUGGING is enabled. +Functionally identical to + + #ifdef DEBUGGING + code + #endif + +but prettier. This macro is useful for declaring variables that are +only used on DEBUGGING builds. Note that what this macro does is +determined at compile time, if you want a run time equivalent then +use C instead. + +=for apidoc mu||PERL_IF_DEBUGGING_ELSE|code_debugging|code_nondebugging + +A macro way of expressing different code that should be compiled +depending on whether DEBUGGING is enabled. Functionally identical +to + + #ifdef DEBUGGING + code_debugging + #else + code_nondebugging + #end + +but prettier. + +=for apidoc mu||PERL_DEBUG|code +A macro way of expressing code that will only be executed when the run +time internal variable PL_debug is non-zero. + +=for apidoc mu||DEBUG_A|code +=for apidoc_item mu||DEBUG_B|code +=for apidoc_item mu||DEBUG_C|code +=for apidoc_item mu||DEBUG_c|code +=for apidoc_item mu||DEBUG_D|code +=for apidoc_item mu||DEBUG_f|code +=for apidoc_item mu||DEBUG_i|code +=for apidoc_item mu||DEBUG_L|code +=for apidoc_item mu||DEBUG_l|code +=for apidoc_item mu||DEBUG_Lv|code +=for apidoc_item mu||DEBUG_m|code +=for apidoc_item mu||DEBUG_o|code +=for apidoc_item mu||DEBUG_P|code +=for apidoc_item mu||DEBUG_p|code +=for apidoc_item mu||DEBUG_Pv|code +=for apidoc_item mu||DEBUG_q|code +=for apidoc_item mu||DEBUG_R|code +=for apidoc_item mu||DEBUG_r|code +=for apidoc_item mu||DEBUG_S|code +=for apidoc_item mu||DEBUG_s|code +=for apidoc_item mu||DEBUG_T|code +=for apidoc_item mu||DEBUG_t|code +=for apidoc_item mu||DEBUG_U|code +=for apidoc_item mu||DEBUG_u|code +=for apidoc_item mu||DEBUG_Uv|code +=for apidoc_item mu||DEBUG_V|code +=for apidoc_item mu||DEBUG_X|code +=for apidoc_item mu||DEBUG_x|code +=for apidoc_item mu||DEBUG_Xv|code +=for apidoc_item mu||DEBUG_y|code +=for apidoc_item mu||DEBUG_yv|code + +These are debugging macros similar to PERL_DEBUG() but which test +which flags in PL_debug have been set. Each letter corresponds to +a mode exposed by the -D option to perl. These macros only execute +when DEBUGGING is enabled, and when the appropriate debug mode +has been enabled on the command line. + +See L for details on the meaning of the different +switches. + +=cut +*/ + +/* these are for backwards compatibility, just in case anything out + * in the wild (eg CPAN) is using them. */ +#define PERL_DEB(a) PERL_IF_DEBUGGING(a) +#define PERL_DEB2(a,b) PERL_IF_DEBUGGING_ELSE(a,b) + + #define DEBUG_SCOPE(where) \ DEBUG_l( \ Perl_deb(aTHX_ "%s scope %ld (savestack=%ld) at %s:%d\n", \ @@ -5097,7 +5181,7 @@ Gid_t getegid (void); /* Keep the old croak based assert for those who want it, and as a fallback if the platform is so heretically non-ANSI that it can't assert. */ -#define Perl_assert(what) PERL_DEB2( \ +#define Perl_assert(what) PERL_IF_DEBUGGING_ELSE( \ ((what) ? ((void) 0) : \ (Perl_croak_nocontext("Assertion %s failed: file \"" __FILE__ \ "\", line %d", STRINGIFY(what), __LINE__), \ diff --git a/util.c b/util.c index fa946b4153c2..82fb572e524d 100644 --- a/util.c +++ b/util.c @@ -257,7 +257,7 @@ Perl_safesysrealloc(Malloc_t where,MEM_SIZE size) } else { dSAVE_ERRNO; - PERL_DEB(UV was_where = PTR2UV(where)); /* used in diags below */ + PERL_IF_DEBUGGING(UV was_where = PTR2UV(where)); /* used in diags below */ #ifdef USE_MDH where = (Malloc_t)((char*)where-PERL_MEMORY_DEBUG_HEADER_SIZE); if (size + PERL_MEMORY_DEBUG_HEADER_SIZE < size) diff --git a/win32/win32.c b/win32/win32.c index 0f54fc61344f..46653a466c2d 100644 --- a/win32/win32.c +++ b/win32/win32.c @@ -3493,7 +3493,7 @@ win32_tmpfd_mode(int mode) if (fh != INVALID_HANDLE_VALUE) { int fd = win32_open_osfhandle((intptr_t)fh, mode); if (fd >= 0) { - PERL_DEB(dTHX;) + PERL_IF_DEBUGGING(dTHX;) DEBUG_p(PerlIO_printf(Perl_debug_log, "Created tmpfile=%s\n",filename)); return fd; @@ -4194,7 +4194,7 @@ win32_chmod(const char *path, int mode) static char * create_command_line(char *cname, STRLEN clen, const char * const *args) { - PERL_DEB(dTHX;) + PERL_IF_DEBUGGING(dTHX;) int index; char *cmd, *ptr; const char *arg;