1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/common/utracimp.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,384 @@
1.4 +/*
1.5 +*******************************************************************************
1.6 +*
1.7 +* Copyright (C) 2003-2009, International Business Machines
1.8 +* Corporation and others. All Rights Reserved.
1.9 +*
1.10 +*******************************************************************************
1.11 +* file name: utracimp.h
1.12 +* encoding: US-ASCII
1.13 +* tab size: 8 (not used)
1.14 +* indentation:4
1.15 +*
1.16 +* created on: 2003aug06
1.17 +* created by: Markus W. Scherer
1.18 +*
1.19 +* Internal header for ICU tracing/logging.
1.20 +*
1.21 +*
1.22 +* Various notes:
1.23 +* - using a trace level variable to only call trace functions
1.24 +* when the level is sufficient
1.25 +* - using the same variable for tracing on/off to never make a function
1.26 +* call when off
1.27 +* - the function number is put into a local variable by the entry macro
1.28 +* and used implicitly to avoid copy&paste/typing mistakes by the developer
1.29 +* - the application must call utrace_setFunctions() and pass in
1.30 +* implementations for the trace functions
1.31 +* - ICU trace macros call ICU functions that route through the function
1.32 +* pointers if they have been set;
1.33 +* this avoids an indirection at the call site
1.34 +* (which would cost more code for another check and for the indirection)
1.35 +*
1.36 +* ### TODO Issues:
1.37 +* - Verify that va_list is portable among compilers for the same platform.
1.38 +* va_list should be portable because printf() would fail otherwise!
1.39 +* - Should enum values like UTraceLevel be passed into int32_t-type arguments,
1.40 +* or should enum types be used?
1.41 +*/
1.42 +
1.43 +#ifndef __UTRACIMP_H__
1.44 +#define __UTRACIMP_H__
1.45 +
1.46 +#include "unicode/utrace.h"
1.47 +#include <stdarg.h>
1.48 +
1.49 +U_CDECL_BEGIN
1.50 +
1.51 +/**
1.52 + * \var utrace_level
1.53 + * Trace level variable. Negative for "off".
1.54 + * Use only via UTRACE_ macros.
1.55 + * @internal
1.56 + */
1.57 +#ifdef UTRACE_IMPL
1.58 +U_EXPORT int32_t
1.59 +#else
1.60 +U_CFUNC U_COMMON_API int32_t
1.61 +#endif
1.62 +utrace_level;
1.63 +
1.64 +
1.65 +/**
1.66 + * Traced Function Exit return types.
1.67 + * Flags indicating the number and types of varargs included in a call
1.68 + * to a UTraceExit function.
1.69 + * Bits 0-3: The function return type. First variable param.
1.70 + * Bit 4: Flag for presence of U_ErrorCode status param.
1.71 + * @internal
1.72 + */
1.73 +typedef enum UTraceExitVal {
1.74 + /** The traced function returns no value @internal */
1.75 + UTRACE_EXITV_NONE = 0,
1.76 + /** The traced function returns an int32_t, or compatible, type. @internal */
1.77 + UTRACE_EXITV_I32 = 1,
1.78 + /** The traced function returns a pointer @internal */
1.79 + UTRACE_EXITV_PTR = 2,
1.80 + /** The traced function returns a UBool @internal */
1.81 + UTRACE_EXITV_BOOL = 3,
1.82 + /** Mask to extract the return type values from a UTraceExitVal @internal */
1.83 + UTRACE_EXITV_MASK = 0xf,
1.84 + /** Bit indicating that the traced function includes a UErrorCode parameter @internal */
1.85 + UTRACE_EXITV_STATUS = 0x10
1.86 +} UTraceExitVal;
1.87 +
1.88 +/**
1.89 + * Trace function for the entry point of a function.
1.90 + * Do not use directly, use UTRACE_ENTRY instead.
1.91 + * @param fnNumber The UTraceFunctionNumber for the current function.
1.92 + * @internal
1.93 + */
1.94 +U_CAPI void U_EXPORT2
1.95 +utrace_entry(int32_t fnNumber);
1.96 +
1.97 +/**
1.98 + * Trace function for each exit point of a function.
1.99 + * Do not use directly, use UTRACE_EXIT* instead.
1.100 + * @param fnNumber The UTraceFunctionNumber for the current function.
1.101 + * @param returnType The type of the value returned by the function.
1.102 + * @param errorCode The UErrorCode value at function exit. See UTRACE_EXIT.
1.103 + * @internal
1.104 + */
1.105 +U_CAPI void U_EXPORT2
1.106 +utrace_exit(int32_t fnNumber, int32_t returnType, ...);
1.107 +
1.108 +
1.109 +/**
1.110 + * Trace function used inside functions that have a UTRACE_ENTRY() statement.
1.111 + * Do not use directly, use UTRACE_DATAX() macros instead.
1.112 + *
1.113 + * @param utraceFnNumber The number of the current function, from the local
1.114 + * variable of the same name.
1.115 + * @param level The trace level for this message.
1.116 + * @param fmt The trace format string.
1.117 + *
1.118 + * @internal
1.119 + */
1.120 +U_CAPI void U_EXPORT2
1.121 +utrace_data(int32_t utraceFnNumber, int32_t level, const char *fmt, ...);
1.122 +
1.123 +U_CDECL_END
1.124 +
1.125 +#if U_ENABLE_TRACING
1.126 +
1.127 +/**
1.128 + * Boolean expression to see if ICU tracing is turned on
1.129 + * to at least the specified level.
1.130 + * @internal
1.131 + */
1.132 +#define UTRACE_LEVEL(level) (utrace_getLevel()>=(level))
1.133 +
1.134 +/**
1.135 + * Flag bit in utraceFnNumber, the local variable added to each function
1.136 + * with tracing code to contains the function number.
1.137 + *
1.138 + * Set the flag if the function's entry is traced, which will cause the
1.139 + * function's exit to also be traced. utraceFnNumber is uncoditionally
1.140 + * set at entry, whether or not the entry is traced, so that it will
1.141 + * always be available for error trace output.
1.142 + * @internal
1.143 + */
1.144 +#define UTRACE_TRACED_ENTRY 0x80000000
1.145 +
1.146 +/**
1.147 + * Trace statement for the entry point of a function.
1.148 + * Stores the function number in a local variable.
1.149 + * In C code, must be placed immediately after the last variable declaration.
1.150 + * Must be matched with UTRACE_EXIT() at all function exit points.
1.151 + *
1.152 + * Tracing should start with UTRACE_ENTRY after checking for
1.153 + * U_FAILURE at function entry, so that if a function returns immediately
1.154 + * because of a pre-existing error condition, it does not show up in the trace,
1.155 + * consistent with ICU's error handling model.
1.156 + *
1.157 + * @param fnNumber The UTraceFunctionNumber for the current function.
1.158 + * @internal
1.159 + */
1.160 +#define UTRACE_ENTRY(fnNumber) \
1.161 + int32_t utraceFnNumber=(fnNumber); \
1.162 + if(utrace_getLevel()>=UTRACE_INFO) { \
1.163 + utrace_entry(fnNumber); \
1.164 + utraceFnNumber |= UTRACE_TRACED_ENTRY; \
1.165 + }
1.166 +
1.167 +
1.168 +/**
1.169 + * Trace statement for the entry point of open and close functions.
1.170 + * Produces trace output at a less verbose setting than plain UTRACE_ENTRY
1.171 + * Stores the function number in a local variable.
1.172 + * In C code, must be placed immediately after the last variable declaration.
1.173 + * Must be matched with UTRACE_EXIT() at all function exit points.
1.174 + *
1.175 + * @param fnNumber The UTraceFunctionNumber for the current function.
1.176 + * @internal
1.177 + */
1.178 +#define UTRACE_ENTRY_OC(fnNumber) \
1.179 + int32_t utraceFnNumber=(fnNumber); \
1.180 + if(utrace_getLevel()>=UTRACE_OPEN_CLOSE) { \
1.181 + utrace_entry(fnNumber); \
1.182 + utraceFnNumber |= UTRACE_TRACED_ENTRY; \
1.183 + }
1.184 +
1.185 +/**
1.186 + * Trace statement for each exit point of a function that has a UTRACE_ENTRY()
1.187 + * statement.
1.188 + *
1.189 + * @param errorCode The function's ICU UErrorCode value at function exit,
1.190 + * or U_ZERO_ERROR if the function does not use a UErrorCode.
1.191 + * 0==U_ZERO_ERROR indicates success,
1.192 + * positive values an error (see u_errorName()),
1.193 + * negative values an informational status.
1.194 + *
1.195 + * @internal
1.196 + */
1.197 +#define UTRACE_EXIT() \
1.198 + {if(utraceFnNumber & UTRACE_TRACED_ENTRY) { \
1.199 + utrace_exit(utraceFnNumber & ~UTRACE_TRACED_ENTRY, UTRACE_EXITV_NONE); \
1.200 + }}
1.201 +
1.202 +/**
1.203 + * Trace statement for each exit point of a function that has a UTRACE_ENTRY()
1.204 + * statement, and that returns a value.
1.205 + *
1.206 + * @param val The function's return value, int32_t or comatible type.
1.207 + *
1.208 + * @internal
1.209 + */
1.210 +#define UTRACE_EXIT_VALUE(val) \
1.211 + {if(utraceFnNumber & UTRACE_TRACED_ENTRY) { \
1.212 + utrace_exit(utraceFnNumber & ~UTRACE_TRACED_ENTRY, UTRACE_EXITV_I32, val); \
1.213 + }}
1.214 +
1.215 +#define UTRACE_EXIT_STATUS(status) \
1.216 + {if(utraceFnNumber & UTRACE_TRACED_ENTRY) { \
1.217 + utrace_exit(utraceFnNumber & ~UTRACE_TRACED_ENTRY, UTRACE_EXITV_STATUS, status); \
1.218 + }}
1.219 +
1.220 +#define UTRACE_EXIT_VALUE_STATUS(val, status) \
1.221 + {if(utraceFnNumber & UTRACE_TRACED_ENTRY) { \
1.222 + utrace_exit(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (UTRACE_EXITV_I32 | UTRACE_EXITV_STATUS), val, status); \
1.223 + }}
1.224 +
1.225 +#define UTRACE_EXIT_PTR_STATUS(ptr, status) \
1.226 + {if(utraceFnNumber & UTRACE_TRACED_ENTRY) { \
1.227 + utrace_exit(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (UTRACE_EXITV_PTR | UTRACE_EXITV_STATUS), ptr, status); \
1.228 + }}
1.229 +
1.230 +/**
1.231 + * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
1.232 + * Takes no data arguments.
1.233 + * The number of arguments for this macro must match the number of inserts
1.234 + * in the format string. Vector inserts count as two arguments.
1.235 + * Calls utrace_data() if the level is high enough.
1.236 + * @internal
1.237 + */
1.238 +#define UTRACE_DATA0(level, fmt) \
1.239 + if(UTRACE_LEVEL(level)) { \
1.240 + utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt)); \
1.241 + }
1.242 +
1.243 +/**
1.244 + * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
1.245 + * Takes one data argument.
1.246 + * The number of arguments for this macro must match the number of inserts
1.247 + * in the format string. Vector inserts count as two arguments.
1.248 + * Calls utrace_data() if the level is high enough.
1.249 + * @internal
1.250 + */
1.251 +#define UTRACE_DATA1(level, fmt, a) \
1.252 + if(UTRACE_LEVEL(level)) { \
1.253 + utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY , (level), (fmt), (a)); \
1.254 + }
1.255 +
1.256 +/**
1.257 + * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
1.258 + * Takes two data arguments.
1.259 + * The number of arguments for this macro must match the number of inserts
1.260 + * in the format string. Vector inserts count as two arguments.
1.261 + * Calls utrace_data() if the level is high enough.
1.262 + * @internal
1.263 + */
1.264 +#define UTRACE_DATA2(level, fmt, a, b) \
1.265 + if(UTRACE_LEVEL(level)) { \
1.266 + utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY , (level), (fmt), (a), (b)); \
1.267 + }
1.268 +
1.269 +/**
1.270 + * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
1.271 + * Takes three data arguments.
1.272 + * The number of arguments for this macro must match the number of inserts
1.273 + * in the format string. Vector inserts count as two arguments.
1.274 + * Calls utrace_data() if the level is high enough.
1.275 + * @internal
1.276 + */
1.277 +#define UTRACE_DATA3(level, fmt, a, b, c) \
1.278 + if(UTRACE_LEVEL(level)) { \
1.279 + utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c)); \
1.280 + }
1.281 +
1.282 +/**
1.283 + * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
1.284 + * Takes four data arguments.
1.285 + * The number of arguments for this macro must match the number of inserts
1.286 + * in the format string. Vector inserts count as two arguments.
1.287 + * Calls utrace_data() if the level is high enough.
1.288 + * @internal
1.289 + */
1.290 +#define UTRACE_DATA4(level, fmt, a, b, c, d) \
1.291 + if(UTRACE_LEVEL(level)) { \
1.292 + utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d)); \
1.293 + }
1.294 +
1.295 +/**
1.296 + * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
1.297 + * Takes five data arguments.
1.298 + * The number of arguments for this macro must match the number of inserts
1.299 + * in the format string. Vector inserts count as two arguments.
1.300 + * Calls utrace_data() if the level is high enough.
1.301 + * @internal
1.302 + */
1.303 +#define UTRACE_DATA5(level, fmt, a, b, c, d, e) \
1.304 + if(UTRACE_LEVEL(level)) { \
1.305 + utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d), (e)); \
1.306 + }
1.307 +
1.308 +/**
1.309 + * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
1.310 + * Takes six data arguments.
1.311 + * The number of arguments for this macro must match the number of inserts
1.312 + * in the format string. Vector inserts count as two arguments.
1.313 + * Calls utrace_data() if the level is high enough.
1.314 + * @internal
1.315 + */
1.316 +#define UTRACE_DATA6(level, fmt, a, b, c, d, e, f) \
1.317 + if(UTRACE_LEVEL(level)) { \
1.318 + utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d), (e), (f)); \
1.319 + }
1.320 +
1.321 +/**
1.322 + * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
1.323 + * Takes seven data arguments.
1.324 + * The number of arguments for this macro must match the number of inserts
1.325 + * in the format string. Vector inserts count as two arguments.
1.326 + * Calls utrace_data() if the level is high enough.
1.327 + * @internal
1.328 + */
1.329 +#define UTRACE_DATA7(level, fmt, a, b, c, d, e, f, g) \
1.330 + if(UTRACE_LEVEL(level)) { \
1.331 + utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d), (e), (f), (g)); \
1.332 + }
1.333 +
1.334 +/**
1.335 + * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
1.336 + * Takes eight data arguments.
1.337 + * The number of arguments for this macro must match the number of inserts
1.338 + * in the format string. Vector inserts count as two arguments.
1.339 + * Calls utrace_data() if the level is high enough.
1.340 + * @internal
1.341 + */
1.342 +#define UTRACE_DATA8(level, fmt, a, b, c, d, e, f, g, h) \
1.343 + if(UTRACE_LEVEL(level)) { \
1.344 + utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d), (e), (f), (g), (h)); \
1.345 + }
1.346 +
1.347 +/**
1.348 + * Trace statement used inside functions that have a UTRACE_ENTRY() statement.
1.349 + * Takes nine data arguments.
1.350 + * The number of arguments for this macro must match the number of inserts
1.351 + * in the format string. Vector inserts count as two arguments.
1.352 + * Calls utrace_data() if the level is high enough.
1.353 + * @internal
1.354 + */
1.355 +#define UTRACE_DATA9(level, fmt, a, b, c, d, e, f, g, h, i) \
1.356 + if(UTRACE_LEVEL(level)) { \
1.357 + utrace_data(utraceFnNumber & ~UTRACE_TRACED_ENTRY, (level), (fmt), (a), (b), (c), (d), (e), (f), (g), (h), (i)); \
1.358 + }
1.359 +
1.360 +#else
1.361 +
1.362 +/*
1.363 + * When tracing is disabled, the following macros become empty
1.364 + */
1.365 +
1.366 +#define UTRACE_LEVEL(level) 0
1.367 +#define UTRACE_ENTRY(fnNumber)
1.368 +#define UTRACE_ENTRY_OC(fnNumber)
1.369 +#define UTRACE_EXIT()
1.370 +#define UTRACE_EXIT_VALUE(val)
1.371 +#define UTRACE_EXIT_STATUS(status)
1.372 +#define UTRACE_EXIT_VALUE_STATUS(val, status)
1.373 +#define UTRACE_EXIT_PTR_STATUS(ptr, status)
1.374 +#define UTRACE_DATA0(level, fmt)
1.375 +#define UTRACE_DATA1(level, fmt, a)
1.376 +#define UTRACE_DATA2(level, fmt, a, b)
1.377 +#define UTRACE_DATA3(level, fmt, a, b, c)
1.378 +#define UTRACE_DATA4(level, fmt, a, b, c, d)
1.379 +#define UTRACE_DATA5(level, fmt, a, b, c, d, e)
1.380 +#define UTRACE_DATA6(level, fmt, a, b, c, d, e, f)
1.381 +#define UTRACE_DATA7(level, fmt, a, b, c, d, e, f, g)
1.382 +#define UTRACE_DATA8(level, fmt, a, b, c, d, e, f, g, h)
1.383 +#define UTRACE_DATA9(level, fmt, a, b, c, d, e, f, g, h, i)
1.384 +
1.385 +#endif
1.386 +
1.387 +#endif
