blob: f32fe1db3948241a4847701dec0fb6690d47333c [file] [log] [blame]
// © 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
*******************************************************************************
*
* Copyright (C) 2003-2009, International Business Machines
* Corporation and others. All Rights Reserved.
*
*******************************************************************************
* file name: utracimp.h
* encoding: UTF-8
* 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
/**
* 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_getLevel()>=(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); \
UPRV_BLOCK_MACRO_BEGIN { \
if(utrace_getLevel()>=UTRACE_INFO) { \
utrace_entry(fnNumber); \
utraceFnNumber |= UTRACE_TRACED_ENTRY; \
} \
} UPRV_BLOCK_MACRO_END
/**
* 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); \
UPRV_BLOCK_MACRO_BEGIN { \
if(utrace_getLevel()>=UTRACE_OPEN_CLOSE) { \
utrace_entry(fnNumber); \
utraceFnNumber |= UTRACE_TRACED_ENTRY; \
} \
} UPRV_BLOCK_MACRO_END
/**
* 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() UPRV_BLOCK_MACRO_BEGIN { \
if(utraceFnNumber & UTRACE_TRACED_ENTRY) { \
utrace_exit(utraceFnNumber & ~UTRACE_TRACED_ENTRY, UTRACE_EXITV_NONE); \
} \
} UPRV_BLOCK_MACRO_END
/**
* 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) UPRV_BLOCK_MACRO_BEGIN { \
if(utraceFnNumber & UTRACE_TRACED_ENTRY) { \
utrace_exit(utraceFnNumber & ~UTRACE_TRACED_ENTRY, UTRACE_EXITV_I32, val); \
} \
} UPRV_BLOCK_MACRO_END
#define UTRACE_EXIT_STATUS(status) UPRV_BLOCK_MACRO_BEGIN { \
if(utraceFnNumber & UTRACE_TRACED_ENTRY) { \
utrace_exit(utraceFnNumber & ~UTRACE_TRACED_ENTRY, UTRACE_EXITV_STATUS, status); \
} \
} UPRV_BLOCK_MACRO_END
#define UTRACE_EXIT_VALUE_STATUS(val, status) UPRV_BLOCK_MACRO_BEGIN { \
if(utraceFnNumber & UTRACE_TRACED_ENTRY) { \
utrace_exit(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (UTRACE_EXITV_I32 | UTRACE_EXITV_STATUS), val, status); \
} \
} UPRV_BLOCK_MACRO_END
#define UTRACE_EXIT_PTR_STATUS(ptr, status) UPRV_BLOCK_MACRO_BEGIN { \
if(utraceFnNumber & UTRACE_TRACED_ENTRY) { \
utrace_exit(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (UTRACE_EXITV_PTR | UTRACE_EXITV_STATUS), ptr, status); \
} \
} UPRV_BLOCK_MACRO_END
/**
* 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) UPRV_BLOCK_MACRO_BEGIN { \
if(UTRACE_LEVEL(level)) { \
utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt)); \
} \
} UPRV_BLOCK_MACRO_END
/**
* 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) UPRV_BLOCK_MACRO_BEGIN { \
if(UTRACE_LEVEL(level)) { \
utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY , (level), (fmt), (a)); \
} \
} UPRV_BLOCK_MACRO_END
/**
* 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) UPRV_BLOCK_MACRO_BEGIN { \
if(UTRACE_LEVEL(level)) { \
utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY , (level), (fmt), (a), (b)); \
} \
} UPRV_BLOCK_MACRO_END
/**
* 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) UPRV_BLOCK_MACRO_BEGIN { \
if(UTRACE_LEVEL(level)) { \
utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c)); \
} \
} UPRV_BLOCK_MACRO_END
/**
* 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) UPRV_BLOCK_MACRO_BEGIN { \
if(UTRACE_LEVEL(level)) { \
utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d)); \
} \
} UPRV_BLOCK_MACRO_END
/**
* 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) UPRV_BLOCK_MACRO_BEGIN { \
if(UTRACE_LEVEL(level)) { \
utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d), (e)); \
} \
} UPRV_BLOCK_MACRO_END
/**
* 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) UPRV_BLOCK_MACRO_BEGIN { \
if(UTRACE_LEVEL(level)) { \
utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d), (e), (f)); \
} \
} UPRV_BLOCK_MACRO_END
/**
* 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) UPRV_BLOCK_MACRO_BEGIN { \
if(UTRACE_LEVEL(level)) { \
utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d), (e), (f), (g)); \
} \
} UPRV_BLOCK_MACRO_END
/**
* 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) UPRV_BLOCK_MACRO_BEGIN { \
if(UTRACE_LEVEL(level)) { \
utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d), (e), (f), (g), (h)); \
} \
} UPRV_BLOCK_MACRO_END
/**
* 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) UPRV_BLOCK_MACRO_BEGIN { \
if(UTRACE_LEVEL(level)) { \
utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d), (e), (f), (g), (h), (i)); \
} \
} UPRV_BLOCK_MACRO_END
#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