sl@0: /*
sl@0: *******************************************************************************
sl@0: *
sl@0: * Copyright (C) 2003-2004, International Business Machines
sl@0: * Corporation and others. All Rights Reserved.
sl@0: *
sl@0: *******************************************************************************
sl@0: * file name: utracimp.h
sl@0: * encoding: US-ASCII
sl@0: * tab size: 8 (not used)
sl@0: * indentation:4
sl@0: *
sl@0: * created on: 2003aug06
sl@0: * created by: Markus W. Scherer
sl@0: *
sl@0: * Internal header for ICU tracing/logging.
sl@0: *
sl@0: *
sl@0: * Various notes:
sl@0: * - using a trace level variable to only call trace functions
sl@0: * when the level is sufficient
sl@0: * - using the same variable for tracing on/off to never make a function
sl@0: * call when off
sl@0: * - the function number is put into a local variable by the entry macro
sl@0: * and used implicitly to avoid copy&paste/typing mistakes by the developer
sl@0: * - the application must call utrace_setFunctions() and pass in
sl@0: * implementations for the trace functions
sl@0: * - ICU trace macros call ICU functions that route through the function
sl@0: * pointers if they have been set;
sl@0: * this avoids an indirection at the call site
sl@0: * (which would cost more code for another check and for the indirection)
sl@0: *
sl@0: * ### TODO Issues:
sl@0: * - Verify that va_list is portable among compilers for the same platform.
sl@0: * va_list should be portable because printf() would fail otherwise!
sl@0: * - Should enum values like UTraceLevel be passed into int32_t-type arguments,
sl@0: * or should enum types be used?
sl@0: */
sl@0:
sl@0: #ifndef __UTRACIMP_H__
sl@0: #define __UTRACIMP_H__
sl@0:
sl@0: #include "unicode/utrace.h"
sl@0: #include <stdarg.h>
sl@0:
sl@0: U_CDECL_BEGIN
sl@0:
sl@0: /**
sl@0: * \var utrace_level
sl@0: * Trace level variable. Negative for "off".
sl@0: * Use only via UTRACE_ macros.
sl@0: * @internal
sl@0: */
sl@0: #ifdef UTRACE_IMPL
sl@0: U_EXPORT int32_t
sl@0: #else
sl@0: U_CFUNC U_COMMON_API int32_t
sl@0: #endif
sl@0: utrace_level;
sl@0:
sl@0:
sl@0: /**
sl@0: * Traced Function Exit return types.
sl@0: * Flags indicating the number and types of varargs included in a call
sl@0: * to a UTraceExit function.
sl@0: * Bits 0-3: The function return type. First variable param.
sl@0: * Bit 4: Flag for presence of U_ErrorCode status param.
sl@0: * @internal
sl@0: */
sl@0: typedef enum UTraceExitVal {
sl@0: /** The traced function returns no value @internal */
sl@0: UTRACE_EXITV_NONE = 0,
sl@0: /** The traced function returns an int32_t, or compatible, type. @internal */
sl@0: UTRACE_EXITV_I32 = 1,
sl@0: /** The traced function returns a pointer @internal */
sl@0: UTRACE_EXITV_PTR = 2,
sl@0: /** The traced function returns a UBool @internal */
sl@0: UTRACE_EXITV_BOOL = 3,
sl@0: /** Mask to extract the return type values from a UTraceExitVal @internal */
sl@0: UTRACE_EXITV_MASK = 0xf,
sl@0: /** Bit indicating that the traced function includes a UErrorCode parameter @internal */
sl@0: UTRACE_EXITV_STATUS = 0x10
sl@0: } UTraceExitVal;
sl@0:
sl@0: /**
sl@0: * Trace function for the entry point of a function.
sl@0: * Do not use directly, use UTRACE_ENTRY instead.
sl@0: * @param fnNumber The UTraceFunctionNumber for the current function.
sl@0: * @internal
sl@0: */
sl@0: U_CAPI void U_EXPORT2
sl@0: utrace_entry(int32_t fnNumber);
sl@0:
sl@0: /**
sl@0: * Trace function for each exit point of a function.
sl@0: * Do not use directly, use UTRACE_EXIT* instead.
sl@0: * @param fnNumber The UTraceFunctionNumber for the current function.
sl@0: * @param returnType The type of the value returned by the function.
sl@0: * @param errorCode The UErrorCode value at function exit. See UTRACE_EXIT.
sl@0: * @internal
sl@0: */
sl@0: U_CAPI void U_EXPORT2
sl@0: utrace_exit(int32_t fnNumber, int32_t returnType, ...);
sl@0:
sl@0:
sl@0: /**
sl@0: * Trace function used inside functions that have a UTRACE_ENTRY() statement.
sl@0: * Do not use directly, use UTRACE_DATAX() macros instead.
sl@0: *
sl@0: * @param utraceFnNumber The number of the current function, from the local
sl@0: * variable of the same name.
sl@0: * @param level The trace level for this message.
sl@0: * @param fmt The trace format string.
sl@0: *
sl@0: * @internal
sl@0: */
sl@0: U_CAPI void U_EXPORT2
sl@0: utrace_data(int32_t utraceFnNumber, int32_t level, const char *fmt, ...);
sl@0:
sl@0: U_CDECL_END
sl@0:
sl@0: #if U_ENABLE_TRACING
sl@0:
sl@0: /**
sl@0: * Boolean expression to see if ICU tracing is turned on
sl@0: * to at least the specified level.
sl@0: * @internal
sl@0: */
sl@0: #define UTRACE_LEVEL(level) (utrace_level>=(level))
sl@0:
sl@0: /**
sl@0: * Flag bit in utraceFnNumber, the local variable added to each function
sl@0: * with tracing code to contains the function number.
sl@0: *
sl@0: * Set the flag if the function's entry is traced, which will cause the
sl@0: * function's exit to also be traced. utraceFnNumber is uncoditionally
sl@0: * set at entry, whether or not the entry is traced, so that it will
sl@0: * always be available for error trace output.
sl@0: * @internal
sl@0: */
sl@0: #define UTRACE_TRACED_ENTRY 0x80000000
sl@0:
sl@0: /**
sl@0: * Trace statement for the entry point of a function.
sl@0: * Stores the function number in a local variable.
sl@0: * In C code, must be placed immediately after the last variable declaration.
sl@0: * Must be matched with UTRACE_EXIT() at all function exit points.
sl@0: *
sl@0: * Tracing should start with UTRACE_ENTRY after checking for
sl@0: * U_FAILURE at function entry, so that if a function returns immediately
sl@0: * because of a pre-existing error condition, it does not show up in the trace,
sl@0: * consistent with ICU's error handling model.
sl@0: *
sl@0: * @param fnNumber The UTraceFunctionNumber for the current function.
sl@0: * @internal
sl@0: */
sl@0: #define UTRACE_ENTRY(fnNumber) \
sl@0: int32_t utraceFnNumber=(fnNumber); \
sl@0: if(utrace_level>=UTRACE_INFO) { \
sl@0: utrace_entry(fnNumber); \
sl@0: utraceFnNumber |= UTRACE_TRACED_ENTRY; \
sl@0: }
sl@0:
sl@0:
sl@0: /**
sl@0: * Trace statement for the entry point of open and close functions.
sl@0: * Produces trace output at a less verbose setting than plain UTRACE_ENTRY
sl@0: * Stores the function number in a local variable.
sl@0: * In C code, must be placed immediately after the last variable declaration.
sl@0: * Must be matched with UTRACE_EXIT() at all function exit points.
sl@0: *
sl@0: * @param fnNumber The UTraceFunctionNumber for the current function.
sl@0: * @internal
sl@0: */
sl@0: #define UTRACE_ENTRY_OC(fnNumber) \
sl@0: int32_t utraceFnNumber=(fnNumber); \
sl@0: if(utrace_level>=UTRACE_OPEN_CLOSE) { \
sl@0: utrace_entry(fnNumber); \
sl@0: utraceFnNumber |= UTRACE_TRACED_ENTRY; \
sl@0: }
sl@0:
sl@0: /**
sl@0: * Trace statement for each exit point of a function that has a UTRACE_ENTRY()
sl@0: * statement.
sl@0: *
sl@0: * @param errorCode The function's ICU UErrorCode value at function exit,
sl@0: * or U_ZERO_ERROR if the function does not use a UErrorCode.
sl@0: * 0==U_ZERO_ERROR indicates success,
sl@0: * positive values an error (see u_errorName()),
sl@0: * negative values an informational status.
sl@0: *
sl@0: * @internal
sl@0: */
sl@0: #define UTRACE_EXIT() \
sl@0: {if(utraceFnNumber & UTRACE_TRACED_ENTRY) { \
sl@0: utrace_exit(utraceFnNumber & ~UTRACE_TRACED_ENTRY, UTRACE_EXITV_NONE); \
sl@0: }}
sl@0:
sl@0: /**
sl@0: * Trace statement for each exit point of a function that has a UTRACE_ENTRY()
sl@0: * statement, and that returns a value.
sl@0: *
sl@0: * @param val The function's return value, int32_t or comatible type.
sl@0: *
sl@0: * @internal
sl@0: */
sl@0: #define UTRACE_EXIT_VALUE(val) \
sl@0: {if(utraceFnNumber & UTRACE_TRACED_ENTRY) { \
sl@0: utrace_exit(utraceFnNumber & ~UTRACE_TRACED_ENTRY, UTRACE_EXITV_I32, val); \
sl@0: }}
sl@0:
sl@0: #define UTRACE_EXIT_STATUS(status) \
sl@0: {if(utraceFnNumber & UTRACE_TRACED_ENTRY) { \
sl@0: utrace_exit(utraceFnNumber & ~UTRACE_TRACED_ENTRY, UTRACE_EXITV_STATUS, status); \
sl@0: }}
sl@0:
sl@0: #define UTRACE_EXIT_VALUE_STATUS(val, status) \
sl@0: {if(utraceFnNumber & UTRACE_TRACED_ENTRY) { \
sl@0: utrace_exit(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (UTRACE_EXITV_I32 | UTRACE_EXITV_STATUS), val, status); \
sl@0: }}
sl@0:
sl@0: #define UTRACE_EXIT_PTR_STATUS(ptr, status) \
sl@0: {if(utraceFnNumber & UTRACE_TRACED_ENTRY) { \
sl@0: utrace_exit(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (UTRACE_EXITV_PTR | UTRACE_EXITV_STATUS), ptr, status); \
sl@0: }}
sl@0:
sl@0: /**
sl@0: * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
sl@0: * Takes no data arguments.
sl@0: * The number of arguments for this macro must match the number of inserts
sl@0: * in the format string. Vector inserts count as two arguments.
sl@0: * Calls utrace_data() if the level is high enough.
sl@0: * @internal
sl@0: */
sl@0: #define UTRACE_DATA0(level, fmt) \
sl@0: if(UTRACE_LEVEL(level)) { \
sl@0: utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt)); \
sl@0: }
sl@0:
sl@0: /**
sl@0: * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
sl@0: * Takes one data argument.
sl@0: * The number of arguments for this macro must match the number of inserts
sl@0: * in the format string. Vector inserts count as two arguments.
sl@0: * Calls utrace_data() if the level is high enough.
sl@0: * @internal
sl@0: */
sl@0: #define UTRACE_DATA1(level, fmt, a) \
sl@0: if(UTRACE_LEVEL(level)) { \
sl@0: utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY , (level), (fmt), (a)); \
sl@0: }
sl@0:
sl@0: /**
sl@0: * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
sl@0: * Takes two data arguments.
sl@0: * The number of arguments for this macro must match the number of inserts
sl@0: * in the format string. Vector inserts count as two arguments.
sl@0: * Calls utrace_data() if the level is high enough.
sl@0: * @internal
sl@0: */
sl@0: #define UTRACE_DATA2(level, fmt, a, b) \
sl@0: if(UTRACE_LEVEL(level)) { \
sl@0: utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY , (level), (fmt), (a), (b)); \
sl@0: }
sl@0:
sl@0: /**
sl@0: * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
sl@0: * Takes three data arguments.
sl@0: * The number of arguments for this macro must match the number of inserts
sl@0: * in the format string. Vector inserts count as two arguments.
sl@0: * Calls utrace_data() if the level is high enough.
sl@0: * @internal
sl@0: */
sl@0: #define UTRACE_DATA3(level, fmt, a, b, c) \
sl@0: if(UTRACE_LEVEL(level)) { \
sl@0: utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c)); \
sl@0: }
sl@0:
sl@0: /**
sl@0: * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
sl@0: * Takes four data arguments.
sl@0: * The number of arguments for this macro must match the number of inserts
sl@0: * in the format string. Vector inserts count as two arguments.
sl@0: * Calls utrace_data() if the level is high enough.
sl@0: * @internal
sl@0: */
sl@0: #define UTRACE_DATA4(level, fmt, a, b, c, d) \
sl@0: if(UTRACE_LEVEL(level)) { \
sl@0: utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d)); \
sl@0: }
sl@0:
sl@0: /**
sl@0: * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
sl@0: * Takes five data arguments.
sl@0: * The number of arguments for this macro must match the number of inserts
sl@0: * in the format string. Vector inserts count as two arguments.
sl@0: * Calls utrace_data() if the level is high enough.
sl@0: * @internal
sl@0: */
sl@0: #define UTRACE_DATA5(level, fmt, a, b, c, d, e) \
sl@0: if(UTRACE_LEVEL(level)) { \
sl@0: utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d), (e)); \
sl@0: }
sl@0:
sl@0: /**
sl@0: * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
sl@0: * Takes six data arguments.
sl@0: * The number of arguments for this macro must match the number of inserts
sl@0: * in the format string. Vector inserts count as two arguments.
sl@0: * Calls utrace_data() if the level is high enough.
sl@0: * @internal
sl@0: */
sl@0: #define UTRACE_DATA6(level, fmt, a, b, c, d, e, f) \
sl@0: if(UTRACE_LEVEL(level)) { \
sl@0: utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d), (e), (f)); \
sl@0: }
sl@0:
sl@0: /**
sl@0: * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
sl@0: * Takes seven data arguments.
sl@0: * The number of arguments for this macro must match the number of inserts
sl@0: * in the format string. Vector inserts count as two arguments.
sl@0: * Calls utrace_data() if the level is high enough.
sl@0: * @internal
sl@0: */
sl@0: #define UTRACE_DATA7(level, fmt, a, b, c, d, e, f, g) \
sl@0: if(UTRACE_LEVEL(level)) { \
sl@0: utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d), (e), (f), (g)); \
sl@0: }
sl@0:
sl@0: /**
sl@0: * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
sl@0: * Takes eight data arguments.
sl@0: * The number of arguments for this macro must match the number of inserts
sl@0: * in the format string. Vector inserts count as two arguments.
sl@0: * Calls utrace_data() if the level is high enough.
sl@0: * @internal
sl@0: */
sl@0: #define UTRACE_DATA8(level, fmt, a, b, c, d, e, f, g, h) \
sl@0: if(UTRACE_LEVEL(level)) { \
sl@0: utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d), (e), (f), (g), (h)); \
sl@0: }
sl@0:
sl@0: /**
sl@0: * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
sl@0: * Takes nine data arguments.
sl@0: * The number of arguments for this macro must match the number of inserts
sl@0: * in the format string. Vector inserts count as two arguments.
sl@0: * Calls utrace_data() if the level is high enough.
sl@0: * @internal
sl@0: */
sl@0: #define UTRACE_DATA9(level, fmt, a, b, c, d, e, f, g, h, i) \
sl@0: if(UTRACE_LEVEL(level)) { \
sl@0: utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d), (e), (f), (g), (h), (i)); \
sl@0: }
sl@0:
sl@0: #else
sl@0:
sl@0: /*
sl@0: * When tracing is disabled, the following macros become empty
sl@0: */
sl@0:
sl@0: #define UTRACE_LEVEL(level) 0
sl@0: #define UTRACE_ENTRY(fnNumber)
sl@0: #define UTRACE_ENTRY_OC(fnNumber)
sl@0: #define UTRACE_EXIT()
sl@0: #define UTRACE_EXIT_VALUE(val)
sl@0: #define UTRACE_EXIT_STATUS(status)
sl@0: #define UTRACE_EXIT_VALUE_STATUS(val, status)
sl@0: #define UTRACE_EXIT_PTR_STATUS(ptr, status)
sl@0: #define UTRACE_DATA0(level, fmt)
sl@0: #define UTRACE_DATA1(level, fmt, a)
sl@0: #define UTRACE_DATA2(level, fmt, a, b)
sl@0: #define UTRACE_DATA3(level, fmt, a, b, c)
sl@0: #define UTRACE_DATA4(level, fmt, a, b, c, d)
sl@0: #define UTRACE_DATA5(level, fmt, a, b, c, d, e)
sl@0: #define UTRACE_DATA6(level, fmt, a, b, c, d, e, f)
sl@0: #define UTRACE_DATA7(level, fmt, a, b, c, d, e, f, g)
sl@0: #define UTRACE_DATA8(level, fmt, a, b, c, d, e, f, g, h)
sl@0: #define UTRACE_DATA9(level, fmt, a, b, c, d, e, f, g, h, i)
sl@0:
sl@0: #endif
sl@0:
sl@0: #endif