1 /*

     2 *******************************************************************************

     3 *

     4 *   Copyright (C) 2003-2004, International Business Machines

     5 *   Corporation and others.  All Rights Reserved.

     6 *

     7 *******************************************************************************

     8 *   file name:  utracimp.h

     9 *   encoding:   US-ASCII

    10 *   tab size:   8 (not used)

    11 *   indentation:4

    12 *

    13 *   created on: 2003aug06

    14 *   created by: Markus W. Scherer

    15 *

    16 *   Internal header for ICU tracing/logging.

    17 *

    18 *

    19 *   Various notes:

    20 *   - using a trace level variable to only call trace functions

    21 *     when the level is sufficient

    22 *   - using the same variable for tracing on/off to never make a function

    23 *     call when off

    24 *   - the function number is put into a local variable by the entry macro

    25 *     and used implicitly to avoid copy&paste/typing mistakes by the developer

    26 *   - the application must call utrace_setFunctions() and pass in

    27 *     implementations for the trace functions

    28 *   - ICU trace macros call ICU functions that route through the function

    29 *     pointers if they have been set;

    30 *     this avoids an indirection at the call site

    31 *     (which would cost more code for another check and for the indirection)

    32 *

    33 *   ### TODO Issues:

    34 *   - Verify that va_list is portable among compilers for the same platform.

    35 *     va_list should be portable because printf() would fail otherwise!

    36 *   - Should enum values like UTraceLevel be passed into int32_t-type arguments,

    37 *     or should enum types be used?

    38 */

    39 

    40 #ifndef __UTRACIMP_H__

    41 #define __UTRACIMP_H__

    42 

    43 #include "unicode/utrace.h"

    44 #include <stdarg.h>

    45 

    46 U_CDECL_BEGIN

    47 

    48 /**

    49  * \var utrace_level

    50  * Trace level variable. Negative for "off".

    51  * Use only via UTRACE_ macros.

    52  * @internal

    53  */

    54 #ifdef UTRACE_IMPL

    55 U_EXPORT int32_t

    56 #else

    57 U_CFUNC U_COMMON_API int32_t

    58 #endif

    59 utrace_level;

    60 

    61 

    62 /** 

    63  *   Traced Function Exit return types.  

    64  *   Flags indicating the number and types of varargs included in a call

    65  *   to a UTraceExit function.

    66  *   Bits 0-3:  The function return type.  First variable param.

    67  *   Bit    4:  Flag for presence of U_ErrorCode status param.

    68  *   @internal

    69  */

    70 typedef enum UTraceExitVal {

    71     /** The traced function returns no value  @internal */

    72     UTRACE_EXITV_NONE   = 0,

    73     /** The traced function returns an int32_t, or compatible, type.  @internal */

    74     UTRACE_EXITV_I32    = 1,

    75     /** The traced function returns a pointer  @internal */

    76     UTRACE_EXITV_PTR    = 2,

    77     /** The traced function returns a UBool  @internal */

    78     UTRACE_EXITV_BOOL   = 3,

    79     /** Mask to extract the return type values from a UTraceExitVal  @internal */

    80     UTRACE_EXITV_MASK   = 0xf,

    81     /** Bit indicating that the traced function includes a UErrorCode parameter  @internal */

    82     UTRACE_EXITV_STATUS = 0x10

    83 } UTraceExitVal;

    84 

    85 /**

    86  * Trace function for the entry point of a function.

    87  * Do not use directly, use UTRACE_ENTRY instead.

    88  * @param fnNumber The UTraceFunctionNumber for the current function.

    89  * @internal

    90  */

    91 U_CAPI void U_EXPORT2

    92 utrace_entry(int32_t fnNumber);

    93 

    94 /**

    95  * Trace function for each exit point of a function.

    96  * Do not use directly, use UTRACE_EXIT* instead.

    97  * @param fnNumber The UTraceFunctionNumber for the current function.

    98  * @param returnType The type of the value returned by the function.

    99  * @param errorCode The UErrorCode value at function exit. See UTRACE_EXIT.

   100  * @internal

   101  */

   102 U_CAPI void U_EXPORT2

   103 utrace_exit(int32_t fnNumber, int32_t returnType, ...);

   104 

   105 

   106 /**

   107  * Trace function used inside functions that have a UTRACE_ENTRY() statement.

   108  * Do not use directly, use UTRACE_DATAX() macros instead.

   109  *

   110  * @param utraceFnNumber The number of the current function, from the local

   111  *        variable of the same name.

   112  * @param level The trace level for this message.

   113  * @param fmt The trace format string.

   114  *

   115  * @internal

   116  */

   117 U_CAPI void U_EXPORT2

   118 utrace_data(int32_t utraceFnNumber, int32_t level, const char *fmt, ...);

   119 

   120 U_CDECL_END

   121 

   122 #if U_ENABLE_TRACING

   123 

   124 /**

   125  * Boolean expression to see if ICU tracing is turned on

   126  * to at least the specified level.

   127  * @internal

   128  */

   129 #define UTRACE_LEVEL(level) (utrace_level>=(level))

   130 

   131 /**

   132   *  Flag bit in utraceFnNumber, the local variable added to each function 

   133   *  with tracing code to contains the function number.

   134   *

   135   *  Set the flag if the function's entry is traced, which will cause the

   136   *  function's exit to also be traced.  utraceFnNumber is uncoditionally 

   137   *  set at entry, whether or not the entry is traced, so that it will

   138   *  always be available for error trace output.

   139   *  @internal

   140   */            

   141 #define UTRACE_TRACED_ENTRY 0x80000000

   142 

   143 /**

   144  * Trace statement for the entry point of a function.

   145  * Stores the function number in a local variable.

   146  * In C code, must be placed immediately after the last variable declaration.

   147  * Must be matched with UTRACE_EXIT() at all function exit points.

   148  *

   149  * Tracing should start with UTRACE_ENTRY after checking for

   150  * U_FAILURE at function entry, so that if a function returns immediately

   151  * because of a pre-existing error condition, it does not show up in the trace,

   152  * consistent with ICU's error handling model.

   153  *

   154  * @param fnNumber The UTraceFunctionNumber for the current function.

   155  * @internal

   156  */

   157 #define UTRACE_ENTRY(fnNumber) \

   158     int32_t utraceFnNumber=(fnNumber); \

   159     if(utrace_level>=UTRACE_INFO) { \

   160         utrace_entry(fnNumber); \

   161         utraceFnNumber |= UTRACE_TRACED_ENTRY; \

   162     }

   163 

   164 

   165 /**

   166  * Trace statement for the entry point of open and close functions.

   167  * Produces trace output at a less verbose setting than plain UTRACE_ENTRY

   168  * Stores the function number in a local variable.

   169  * In C code, must be placed immediately after the last variable declaration.

   170  * Must be matched with UTRACE_EXIT() at all function exit points.

   171  *

   172  * @param fnNumber The UTraceFunctionNumber for the current function.

   173  * @internal

   174  */

   175 #define UTRACE_ENTRY_OC(fnNumber) \

   176     int32_t utraceFnNumber=(fnNumber); \

   177     if(utrace_level>=UTRACE_OPEN_CLOSE) { \

   178         utrace_entry(fnNumber); \

   179         utraceFnNumber |= UTRACE_TRACED_ENTRY; \

   180     }

   181 

   182 /**

   183  * Trace statement for each exit point of a function that has a UTRACE_ENTRY()

   184  * statement.

   185  *

   186  * @param errorCode The function's ICU UErrorCode value at function exit,

   187  *                  or U_ZERO_ERROR if the function does not use a UErrorCode.

   188  *                  0==U_ZERO_ERROR indicates success,

   189  *                  positive values an error (see u_errorName()),

   190  *                  negative values an informational status.

   191  *

   192  * @internal

   193  */

   194 #define UTRACE_EXIT() \

   195     {if(utraceFnNumber & UTRACE_TRACED_ENTRY) { \

   196         utrace_exit(utraceFnNumber & ~UTRACE_TRACED_ENTRY, UTRACE_EXITV_NONE); \

   197     }}

   198 

   199 /**

   200  * Trace statement for each exit point of a function that has a UTRACE_ENTRY()

   201  * statement, and that returns a value.

   202  *

   203  * @param val       The function's return value, int32_t or comatible type.

   204  *

   205  * @internal 

   206  */

   207 #define UTRACE_EXIT_VALUE(val) \

   208     {if(utraceFnNumber & UTRACE_TRACED_ENTRY) { \

   209         utrace_exit(utraceFnNumber & ~UTRACE_TRACED_ENTRY, UTRACE_EXITV_I32, val); \

   210     }}

   211 

   212 #define UTRACE_EXIT_STATUS(status) \

   213     {if(utraceFnNumber & UTRACE_TRACED_ENTRY) { \

   214         utrace_exit(utraceFnNumber & ~UTRACE_TRACED_ENTRY, UTRACE_EXITV_STATUS, status); \

   215     }}

   216 

   217 #define UTRACE_EXIT_VALUE_STATUS(val, status) \

   218     {if(utraceFnNumber & UTRACE_TRACED_ENTRY) { \

   219         utrace_exit(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (UTRACE_EXITV_I32 | UTRACE_EXITV_STATUS), val, status); \

   220     }}

   221 

   222 #define UTRACE_EXIT_PTR_STATUS(ptr, status) \

   223     {if(utraceFnNumber & UTRACE_TRACED_ENTRY) { \

   224         utrace_exit(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (UTRACE_EXITV_PTR | UTRACE_EXITV_STATUS), ptr, status); \

   225     }}

   226 

   227 /**

   228  * Trace statement used inside functions that have a UTRACE_ENTRY() statement.

   229  * Takes no data arguments.

   230  * The number of arguments for this macro must match the number of inserts

   231  * in the format string. Vector inserts count as two arguments.

   232  * Calls utrace_data() if the level is high enough.

   233  * @internal

   234  */

   235 #define UTRACE_DATA0(level, fmt) \

   236     if(UTRACE_LEVEL(level)) { \

   237         utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt)); \

   238     }

   239 

   240 /**

   241  * Trace statement used inside functions that have a UTRACE_ENTRY() statement.

   242  * Takes one data argument.

   243  * The number of arguments for this macro must match the number of inserts

   244  * in the format string. Vector inserts count as two arguments.

   245  * Calls utrace_data() if the level is high enough.

   246  * @internal

   247  */

   248 #define UTRACE_DATA1(level, fmt, a) \

   249     if(UTRACE_LEVEL(level)) { \

   250         utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY , (level), (fmt), (a)); \

   251     }

   252 

   253 /**

   254  * Trace statement used inside functions that have a UTRACE_ENTRY() statement.

   255  * Takes two data arguments.

   256  * The number of arguments for this macro must match the number of inserts

   257  * in the format string. Vector inserts count as two arguments.

   258  * Calls utrace_data() if the level is high enough.

   259  * @internal

   260  */

   261 #define UTRACE_DATA2(level, fmt, a, b) \

   262     if(UTRACE_LEVEL(level)) { \

   263         utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY , (level), (fmt), (a), (b)); \

   264     }

   265 

   266 /**

   267  * Trace statement used inside functions that have a UTRACE_ENTRY() statement.

   268  * Takes three data arguments.

   269  * The number of arguments for this macro must match the number of inserts

   270  * in the format string. Vector inserts count as two arguments.

   271  * Calls utrace_data() if the level is high enough.

   272  * @internal

   273  */

   274 #define UTRACE_DATA3(level, fmt, a, b, c) \

   275     if(UTRACE_LEVEL(level)) { \

   276         utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c)); \

   277     }

   278 

   279 /**

   280  * Trace statement used inside functions that have a UTRACE_ENTRY() statement.

   281  * Takes four data arguments.

   282  * The number of arguments for this macro must match the number of inserts

   283  * in the format string. Vector inserts count as two arguments.

   284  * Calls utrace_data() if the level is high enough.

   285  * @internal

   286  */

   287 #define UTRACE_DATA4(level, fmt, a, b, c, d) \

   288     if(UTRACE_LEVEL(level)) { \

   289         utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d)); \

   290     }

   291 

   292 /**

   293  * Trace statement used inside functions that have a UTRACE_ENTRY() statement.

   294  * Takes five data arguments.

   295  * The number of arguments for this macro must match the number of inserts

   296  * in the format string. Vector inserts count as two arguments.

   297  * Calls utrace_data() if the level is high enough.

   298  * @internal

   299  */

   300 #define UTRACE_DATA5(level, fmt, a, b, c, d, e) \

   301     if(UTRACE_LEVEL(level)) { \

   302         utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d), (e)); \

   303     }

   304 

   305 /**

   306  * Trace statement used inside functions that have a UTRACE_ENTRY() statement.

   307  * Takes six data arguments.

   308  * The number of arguments for this macro must match the number of inserts

   309  * in the format string. Vector inserts count as two arguments.

   310  * Calls utrace_data() if the level is high enough.

   311  * @internal

   312  */

   313 #define UTRACE_DATA6(level, fmt, a, b, c, d, e, f) \

   314     if(UTRACE_LEVEL(level)) { \

   315         utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d), (e), (f)); \

   316     }

   317 

   318 /**

   319  * Trace statement used inside functions that have a UTRACE_ENTRY() statement.

   320  * Takes seven data arguments.

   321  * The number of arguments for this macro must match the number of inserts

   322  * in the format string. Vector inserts count as two arguments.

   323  * Calls utrace_data() if the level is high enough.

   324  * @internal

   325  */

   326 #define UTRACE_DATA7(level, fmt, a, b, c, d, e, f, g) \

   327     if(UTRACE_LEVEL(level)) { \

   328         utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d), (e), (f), (g)); \

   329     }

   330 

   331 /**

   332  * Trace statement used inside functions that have a UTRACE_ENTRY() statement.

   333  * Takes eight data arguments.

   334  * The number of arguments for this macro must match the number of inserts

   335  * in the format string. Vector inserts count as two arguments.

   336  * Calls utrace_data() if the level is high enough.

   337  * @internal

   338  */

   339 #define UTRACE_DATA8(level, fmt, a, b, c, d, e, f, g, h) \

   340     if(UTRACE_LEVEL(level)) { \

   341         utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d), (e), (f), (g), (h)); \

   342     }

   343 

   344 /**

   345  * Trace statement used inside functions that have a UTRACE_ENTRY() statement.

   346  * Takes nine data arguments.

   347  * The number of arguments for this macro must match the number of inserts

   348  * in the format string. Vector inserts count as two arguments.

   349  * Calls utrace_data() if the level is high enough.

   350  * @internal

   351  */

   352 #define UTRACE_DATA9(level, fmt, a, b, c, d, e, f, g, h, i) \

   353     if(UTRACE_LEVEL(level)) { \

   354         utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d), (e), (f), (g), (h), (i)); \

   355     }

   356 

   357 #else

   358 

   359 /*

   360  * When tracing is disabled, the following macros become empty

   361  */

   362 

   363 #define UTRACE_LEVEL(level) 0

   364 #define UTRACE_ENTRY(fnNumber)

   365 #define UTRACE_ENTRY_OC(fnNumber)

   366 #define UTRACE_EXIT()

   367 #define UTRACE_EXIT_VALUE(val)

   368 #define UTRACE_EXIT_STATUS(status)

   369 #define UTRACE_EXIT_VALUE_STATUS(val, status)

   370 #define UTRACE_EXIT_PTR_STATUS(ptr, status)

   371 #define UTRACE_DATA0(level, fmt)

   372 #define UTRACE_DATA1(level, fmt, a)

   373 #define UTRACE_DATA2(level, fmt, a, b)

   374 #define UTRACE_DATA3(level, fmt, a, b, c)

   375 #define UTRACE_DATA4(level, fmt, a, b, c, d)

   376 #define UTRACE_DATA5(level, fmt, a, b, c, d, e)

   377 #define UTRACE_DATA6(level, fmt, a, b, c, d, e, f)

   378 #define UTRACE_DATA7(level, fmt, a, b, c, d, e, f, g)

   379 #define UTRACE_DATA8(level, fmt, a, b, c, d, e, f, g, h)

   380 #define UTRACE_DATA9(level, fmt, a, b, c, d, e, f, g, h, i)

   381 

   382 #endif

   383 

   384 #endif