Tracing Facility

Classes
class	xmog_tracer
	An interface that provides a tracing facility for the runtime library. More...

Typedefs
typedef void(JNICALL *	XMOG_TRACE) (FILE *fpTrace, int traceLevel, const char *format, va_list args)
	A function type that can be used to trace to arbitrary file handles. More...

Enumerations
enum	xmog_trace_facility {   TraceNothing = 0, TraceJvm = 1, TraceClr = 1, TraceThread = 2,   TraceJni = 4, TraceRemote = 8, TraceCallbacks = 16, TraceAll = 31,   TraceEverything = 31 }
	Tracing facilities for the runtime.
enum	xmog_trace_level {   TraceDisabled = 0, TraceErrors = 1, TraceError = 1, TraceWarnings = 2,   TraceInfo = 3, TraceFinest = 4, TraceVerbose = 4, TraceUnconditional = 5 }
	Tracing levels for the runtime.

Functions
XMOG_DECLSPEC void JNICALL	traceOutputDebugString (FILE *fpTrace, int traceLevel, const char *format, va_list args)
	A tracing entry point that can be specified by name. More...
XMOG_DECLSPEC void JNICALL	traceEventLog (FILE *fpTrace, int traceLevel, const char *format, va_list args)
	A tracing entry point that can be specified by name. More...

Detailed Description

Introduction

Since version 3.0 the runtime library contains an enhanced tracing/logging facility. There are several xmog_trace_facility@endref s than can be controlled indepdendently. By default, the tracing level for all facilities is set to simply log errors to stderr.

You can change that behavior by supplying a filename or a custom trace method that will be called instead of the default method. The runtime library contains several alternate implementations of tracing methods that can for example write the output to the Windows event log or to a debugger window.

Specifying an output file

You can set the output file for both the default logging method and custom logging methods by calling the xmog_options::setTraceFile() method (usually via an xmog_jvm_loader instance) or by supplying the name of the file via one of the other configuration mechanisms.

Specifying a custom trace method

You can register any method that is of the XMOG_TRACE type as the tracing method. Presupplied tracing functions include:

• traceOutputDebugString()
• traceEventLog()

You can supply your own function by passing a function pointer to the xmog_options::setTraceMethod() function or by specifying a string'ized function pointer in the configuration. A string'ized function pointer is of the form:

[ <libraryname> ; ] <functionname>

If you just supply the functionname, the trace method will be looked for in the runtime library.

Typedef Documentation

XMOG_TRACE

typedef void(JNICALL * XMOG_TRACE) (FILE *fpTrace, int traceLevel, const char *format, va_list args)

A function type that can be used to trace to arbitrary file handles.

Parameters

fpTrace	a FILE pointer.
traceLevel	the tracing level for the message.
format	the format string as used by printf style methods.
args	a variable argument list.

Function Documentation

traceEventLog()

XMOG_DECLSPEC void JNICALL traceEventLog	(	FILE *	fpTrace,
		int	traceLevel,
		const char *	format,
		va_list	args
	)

A tracing entry point that can be specified by name.

This tracing method is really only useful on Windows where it ignores the file argument and prints the resulting trace message to the Windows event log.

On all other platforms, this method is implemented be printing to stderr.

Parameters

fpTrace	ignored.
traceLevel	the tracing level for the message.
format	the printf - style format string.
args	the variable argument list.

traceOutputDebugString()

XMOG_DECLSPEC void JNICALL traceOutputDebugString	(	FILE *	fpTrace,
		int	traceLevel,
		const char *	format,
		va_list	args
	)

A tracing entry point that can be specified by name.

This tracing method is really only useful on Windows where it ignores the file argument and prints the resulting trace message to the OutputDebugString method, which displays the messages within the debugger.

On all other platforms, this method is implemented be printing to stderr.

Parameters

fpTrace	ignored.
traceLevel	ignored.
format	the printf - style format string.
args	the variable argument list.