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