icuSources/common/utracimp.h

   1 // © 2016 and later: Unicode, Inc. and others.
   2 // License & terms of use: http://www.unicode.org/copyright.html
   3 /*
   4 *******************************************************************************
   5 *
   6 *   Copyright (C) 2003-2009, International Business Machines
   7 *   Corporation and others.  All Rights Reserved.
   8 *
   9 *******************************************************************************
  10 *   file name:  utracimp.h
  11 *   encoding:   UTF-8
  12 *   tab size:   8 (not used)
  13 *   indentation:4
  14 *
  15 *   created on: 2003aug06
  16 *   created by: Markus W. Scherer
  17 *
  18 *   Internal header for ICU tracing/logging.
  19 *
  20 *
  21 *   Various notes:
  22 *   - using a trace level variable to only call trace functions
  23 *     when the level is sufficient
  24 *   - using the same variable for tracing on/off to never make a function
  25 *     call when off
  26 *   - the function number is put into a local variable by the entry macro
  27 *     and used implicitly to avoid copy&paste/typing mistakes by the developer
  28 *   - the application must call utrace_setFunctions() and pass in
  29 *     implementations for the trace functions
  30 *   - ICU trace macros call ICU functions that route through the function
  31 *     pointers if they have been set;
  32 *     this avoids an indirection at the call site
  33 *     (which would cost more code for another check and for the indirection)
  34 *
  35 *   ### TODO Issues:
  36 *   - Verify that va_list is portable among compilers for the same platform.
  37 *     va_list should be portable because printf() would fail otherwise!
  38 *   - Should enum values like UTraceLevel be passed into int32_t-type arguments,
  39 *     or should enum types be used?
  40 */
  41
  42 #ifndef __UTRACIMP_H__
  43 #define __UTRACIMP_H__
  44
  45 #include "unicode/utrace.h"
  46 #include <stdarg.h>
  47
  48 U_CDECL_BEGIN
  49
  50 /**
  51  *   Traced Function Exit return types.
  52  *   Flags indicating the number and types of varargs included in a call
  53  *   to a UTraceExit function.
  54  *   Bits 0-3:  The function return type.  First variable param.
  55  *   Bit    4:  Flag for presence of U_ErrorCode status param.
  56  *   @internal
  57  */
  58 typedef enum UTraceExitVal {
  59     /** The traced function returns no value  @internal */
  60     UTRACE_EXITV_NONE   = 0,
  61     /** The traced function returns an int32_t, or compatible, type.  @internal */
  62     UTRACE_EXITV_I32    = 1,
  63     /** The traced function returns a pointer  @internal */
  64     UTRACE_EXITV_PTR    = 2,
  65     /** The traced function returns a UBool  @internal */
  66     UTRACE_EXITV_BOOL   = 3,
  67     /** Mask to extract the return type values from a UTraceExitVal  @internal */
  68     UTRACE_EXITV_MASK   = 0xf,
  69     /** Bit indicating that the traced function includes a UErrorCode parameter  @internal */
  70     UTRACE_EXITV_STATUS = 0x10
  71 } UTraceExitVal;
  72
  73 /**
  74  * Trace function for the entry point of a function.
  75  * Do not use directly, use UTRACE_ENTRY instead.
  76  * @param fnNumber The UTraceFunctionNumber for the current function.
  77  * @internal
  78  */
  79 U_CAPI void U_EXPORT2
  80 utrace_entry(int32_t fnNumber);
  81
  82 /**
  83  * Trace function for each exit point of a function.
  84  * Do not use directly, use UTRACE_EXIT* instead.
  85  * @param fnNumber The UTraceFunctionNumber for the current function.
  86  * @param returnType The type of the value returned by the function.
  87  * @param errorCode The UErrorCode value at function exit. See UTRACE_EXIT.
  88  * @internal
  89  */
  90 U_CAPI void U_EXPORT2
  91 utrace_exit(int32_t fnNumber, int32_t returnType, ...);
  92
  93
  94 /**
  95  * Trace function used inside functions that have a UTRACE_ENTRY() statement.
  96  * Do not use directly, use UTRACE_DATAX() macros instead.
  97  *
  98  * @param utraceFnNumber The number of the current function, from the local
  99  *        variable of the same name.
 100  * @param level The trace level for this message.
 101  * @param fmt The trace format string.
 102  *
 103  * @internal
 104  */
 105 U_CAPI void U_EXPORT2
 106 utrace_data(int32_t utraceFnNumber, int32_t level, const char *fmt, ...);
 107
 108 U_CDECL_END
 109
 110 #if U_ENABLE_TRACING
 111
 112 /**
 113  * Boolean expression to see if ICU tracing is turned on
 114  * to at least the specified level.
 115  * @internal
 116  */
 117 #define UTRACE_LEVEL(level) (utrace_getLevel()>=(level))
 118
 119 /**
 120   *  Flag bit in utraceFnNumber, the local variable added to each function
 121   *  with tracing code to contains the function number.
 122   *
 123   *  Set the flag if the function's entry is traced, which will cause the
 124   *  function's exit to also be traced.  utraceFnNumber is uncoditionally
 125   *  set at entry, whether or not the entry is traced, so that it will
 126   *  always be available for error trace output.
 127   *  @internal
 128   */
 129 #define UTRACE_TRACED_ENTRY 0x80000000
 130
 131 /**
 132  * Trace statement for the entry point of a function.
 133  * Stores the function number in a local variable.
 134  * In C code, must be placed immediately after the last variable declaration.
 135  * Must be matched with UTRACE_EXIT() at all function exit points.
 136  *
 137  * Tracing should start with UTRACE_ENTRY after checking for
 138  * U_FAILURE at function entry, so that if a function returns immediately
 139  * because of a pre-existing error condition, it does not show up in the trace,
 140  * consistent with ICU's error handling model.
 141  *
 142  * @param fnNumber The UTraceFunctionNumber for the current function.
 143  * @internal
 144  */
 145 #define UTRACE_ENTRY(fnNumber) \
 146     int32_t utraceFnNumber=(fnNumber); \
 147     if(utrace_getLevel()>=UTRACE_INFO) { \
 148         utrace_entry(fnNumber); \
 149         utraceFnNumber |= UTRACE_TRACED_ENTRY; \
 150     }
 151
 152
 153 /**
 154  * Trace statement for the entry point of open and close functions.
 155  * Produces trace output at a less verbose setting than plain UTRACE_ENTRY
 156  * Stores the function number in a local variable.
 157  * In C code, must be placed immediately after the last variable declaration.
 158  * Must be matched with UTRACE_EXIT() at all function exit points.
 159  *
 160  * @param fnNumber The UTraceFunctionNumber for the current function.
 161  * @internal
 162  */
 163 #define UTRACE_ENTRY_OC(fnNumber) \
 164     int32_t utraceFnNumber=(fnNumber); \
 165     if(utrace_getLevel()>=UTRACE_OPEN_CLOSE) { \
 166         utrace_entry(fnNumber); \
 167         utraceFnNumber |= UTRACE_TRACED_ENTRY; \
 168     }
 169
 170 /**
 171  * Trace statement for each exit point of a function that has a UTRACE_ENTRY()
 172  * statement.
 173  *
 174  * @param errorCode The function's ICU UErrorCode value at function exit,
 175  *                  or U_ZERO_ERROR if the function does not use a UErrorCode.
 176  *                  0==U_ZERO_ERROR indicates success,
 177  *                  positive values an error (see u_errorName()),
 178  *                  negative values an informational status.
 179  *
 180  * @internal
 181  */
 182 #define UTRACE_EXIT() \
 183     {if(utraceFnNumber & UTRACE_TRACED_ENTRY) { \
 184         utrace_exit(utraceFnNumber & ~UTRACE_TRACED_ENTRY, UTRACE_EXITV_NONE); \
 185     }}
 186
 187 /**
 188  * Trace statement for each exit point of a function that has a UTRACE_ENTRY()
 189  * statement, and that returns a value.
 190  *
 191  * @param val       The function's return value, int32_t or comatible type.
 192  *
 193  * @internal
 194  */
 195 #define UTRACE_EXIT_VALUE(val) \
 196     {if(utraceFnNumber & UTRACE_TRACED_ENTRY) { \
 197         utrace_exit(utraceFnNumber & ~UTRACE_TRACED_ENTRY, UTRACE_EXITV_I32, val); \
 198     }}
 199
 200 #define UTRACE_EXIT_STATUS(status) \
 201     {if(utraceFnNumber & UTRACE_TRACED_ENTRY) { \
 202         utrace_exit(utraceFnNumber & ~UTRACE_TRACED_ENTRY, UTRACE_EXITV_STATUS, status); \
 203     }}
 204
 205 #define UTRACE_EXIT_VALUE_STATUS(val, status) \
 206     {if(utraceFnNumber & UTRACE_TRACED_ENTRY) { \
 207         utrace_exit(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (UTRACE_EXITV_I32 | UTRACE_EXITV_STATUS), val, status); \
 208     }}
 209
 210 #define UTRACE_EXIT_PTR_STATUS(ptr, status) \
 211     {if(utraceFnNumber & UTRACE_TRACED_ENTRY) { \
 212         utrace_exit(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (UTRACE_EXITV_PTR | UTRACE_EXITV_STATUS), ptr, status); \
 213     }}
 214
 215 /**
 216  * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
 217  * Takes no data arguments.
 218  * The number of arguments for this macro must match the number of inserts
 219  * in the format string. Vector inserts count as two arguments.
 220  * Calls utrace_data() if the level is high enough.
 221  * @internal
 222  */
 223 #define UTRACE_DATA0(level, fmt) \
 224     if(UTRACE_LEVEL(level)) { \
 225         utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt)); \
 226     }
 227
 228 /**
 229  * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
 230  * Takes one data argument.
 231  * The number of arguments for this macro must match the number of inserts
 232  * in the format string. Vector inserts count as two arguments.
 233  * Calls utrace_data() if the level is high enough.
 234  * @internal
 235  */
 236 #define UTRACE_DATA1(level, fmt, a) \
 237     if(UTRACE_LEVEL(level)) { \
 238         utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY , (level), (fmt), (a)); \
 239     }
 240
 241 /**
 242  * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
 243  * Takes two data arguments.
 244  * The number of arguments for this macro must match the number of inserts
 245  * in the format string. Vector inserts count as two arguments.
 246  * Calls utrace_data() if the level is high enough.
 247  * @internal
 248  */
 249 #define UTRACE_DATA2(level, fmt, a, b) \
 250     if(UTRACE_LEVEL(level)) { \
 251         utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY , (level), (fmt), (a), (b)); \
 252     }
 253
 254 /**
 255  * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
 256  * Takes three data arguments.
 257  * The number of arguments for this macro must match the number of inserts
 258  * in the format string. Vector inserts count as two arguments.
 259  * Calls utrace_data() if the level is high enough.
 260  * @internal
 261  */
 262 #define UTRACE_DATA3(level, fmt, a, b, c) \
 263     if(UTRACE_LEVEL(level)) { \
 264         utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c)); \
 265     }
 266
 267 /**
 268  * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
 269  * Takes four data arguments.
 270  * The number of arguments for this macro must match the number of inserts
 271  * in the format string. Vector inserts count as two arguments.
 272  * Calls utrace_data() if the level is high enough.
 273  * @internal
 274  */
 275 #define UTRACE_DATA4(level, fmt, a, b, c, d) \
 276     if(UTRACE_LEVEL(level)) { \
 277         utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d)); \
 278     }
 279
 280 /**
 281  * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
 282  * Takes five data arguments.
 283  * The number of arguments for this macro must match the number of inserts
 284  * in the format string. Vector inserts count as two arguments.
 285  * Calls utrace_data() if the level is high enough.
 286  * @internal
 287  */
 288 #define UTRACE_DATA5(level, fmt, a, b, c, d, e) \
 289     if(UTRACE_LEVEL(level)) { \
 290         utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d), (e)); \
 291     }
 292
 293 /**
 294  * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
 295  * Takes six data arguments.
 296  * The number of arguments for this macro must match the number of inserts
 297  * in the format string. Vector inserts count as two arguments.
 298  * Calls utrace_data() if the level is high enough.
 299  * @internal
 300  */
 301 #define UTRACE_DATA6(level, fmt, a, b, c, d, e, f) \
 302     if(UTRACE_LEVEL(level)) { \
 303         utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d), (e), (f)); \
 304     }
 305
 306 /**
 307  * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
 308  * Takes seven data arguments.
 309  * The number of arguments for this macro must match the number of inserts
 310  * in the format string. Vector inserts count as two arguments.
 311  * Calls utrace_data() if the level is high enough.
 312  * @internal
 313  */
 314 #define UTRACE_DATA7(level, fmt, a, b, c, d, e, f, g) \
 315     if(UTRACE_LEVEL(level)) { \
 316         utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d), (e), (f), (g)); \
 317     }
 318
 319 /**
 320  * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
 321  * Takes eight data arguments.
 322  * The number of arguments for this macro must match the number of inserts
 323  * in the format string. Vector inserts count as two arguments.
 324  * Calls utrace_data() if the level is high enough.
 325  * @internal
 326  */
 327 #define UTRACE_DATA8(level, fmt, a, b, c, d, e, f, g, h) \
 328     if(UTRACE_LEVEL(level)) { \
 329         utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d), (e), (f), (g), (h)); \
 330     }
 331
 332 /**
 333  * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
 334  * Takes nine data arguments.
 335  * The number of arguments for this macro must match the number of inserts
 336  * in the format string. Vector inserts count as two arguments.
 337  * Calls utrace_data() if the level is high enough.
 338  * @internal
 339  */
 340 #define UTRACE_DATA9(level, fmt, a, b, c, d, e, f, g, h, i) \
 341     if(UTRACE_LEVEL(level)) { \
 342         utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d), (e), (f), (g), (h), (i)); \
 343     }
 344
 345 #else
 346
 347 /*
 348  * When tracing is disabled, the following macros become empty
 349  */
 350
 351 #define UTRACE_LEVEL(level) 0
 352 #define UTRACE_ENTRY(fnNumber)
 353 #define UTRACE_ENTRY_OC(fnNumber)
 354 #define UTRACE_EXIT()
 355 #define UTRACE_EXIT_VALUE(val)
 356 #define UTRACE_EXIT_STATUS(status)
 357 #define UTRACE_EXIT_VALUE_STATUS(val, status)
 358 #define UTRACE_EXIT_PTR_STATUS(ptr, status)
 359 #define UTRACE_DATA0(level, fmt)
 360 #define UTRACE_DATA1(level, fmt, a)
 361 #define UTRACE_DATA2(level, fmt, a, b)
 362 #define UTRACE_DATA3(level, fmt, a, b, c)
 363 #define UTRACE_DATA4(level, fmt, a, b, c, d)
 364 #define UTRACE_DATA5(level, fmt, a, b, c, d, e)
 365 #define UTRACE_DATA6(level, fmt, a, b, c, d, e, f)
 366 #define UTRACE_DATA7(level, fmt, a, b, c, d, e, f, g)
 367 #define UTRACE_DATA8(level, fmt, a, b, c, d, e, f, g, h)
 368 #define UTRACE_DATA9(level, fmt, a, b, c, d, e, f, g, h, i)
 369
 370 #endif
 371
 372 #endif