PTLib: PTrace Class Reference

List of all members.


Public Types
	Blocks = 1
	Include PTrace::Block constructs in output If this is bit is clear, all PTrace::Block output is inhibited regardless of the trace level.
	DateAndTime = 2
	Include date and time in all output.
	Timestamp = 4
	Include (millisecond) timestamp in all output.
	Thread = 8
	Include identifier for thread trace is made from in all output.
	TraceLevel = 16
	Include trace level in all output.
	FileAndLine = 32
	Include the file and line for the trace call in all output.
	ThreadAddress = 64
	Include thread object pointer address in all trace output.
	AppendToFile = 128
	Append to log file rather than resetting every time.
	GMTTime = 256
	Output timestamps in GMT time rather than local time.
	RotateDaily = 512
	If set, log file will be rotated daily.
	RotateHourly = 1024
	If set, log file will be rotated hourly.
	RotateMinutely = 2048
	If set, log file will be rotated every minute.
	RotateLogMask = RotateDaily + RotateHourly + RotateMinutely
	Mask for all the rotate bits.
	SystemLogStream = 32768
	SystemLog flag for tracing within a PServiceProcess application.
enum	Options { Blocks = 1, DateAndTime = 2, Timestamp = 4, Thread = 8, TraceLevel = 16, FileAndLine = 32, ThreadAddress = 64, AppendToFile = 128, GMTTime = 256, RotateDaily = 512, RotateHourly = 1024, RotateMinutely = 2048, RotateLogMask = RotateDaily + RotateHourly + RotateMinutely, SystemLogStream = 32768 }
	Options for trace output. More...
Static Public Member Functions
static void	Initialise (unsigned level, const char *filename=NULL, unsigned options=Timestamp\|Thread\|Blocks)
	Set the most common trace options.
static void	Initialise (unsigned level, const char filename, const char rolloverPattern, unsigned options=Timestamp\|Thread\|Blocks)
	Set the most common trace options.
static void	SetOptions (unsigned options)
	Set the trace options.
static void	ClearOptions (unsigned options)
	Clear the trace options.
static unsigned	GetOptions ()
	Get the current trace options.
static void	SetLevel (unsigned level)
	Set the trace level.
static unsigned	GetLevel ()
	Get the trace level.
static PBoolean	CanTrace (unsigned level)
	Determine if the level may cause trace output.
static void	SetStream (ostream *out)
	Set the stream to be used for trace output.
static ostream &	Begin (unsigned level, const char *fileName, int lineNum)
	Begin a trace output.
static ostream &	End (ostream &strm)
	End a trace output.
static void	Cleanup ()
	Cleanup the trace system for a specific thread When using thread local storage, this will delete the per-thread trace context.
Classes
class	Block
	Class to trace Execution blocks. More...

Detailed Description

This class does not require any instances and is only being used as a method of grouping functions together in a name space.

There are a number of macros for supporting tracing. These will all evaluate as empty in a "No Trace" build of the system:

Member Enumeration Documentation

enum PTrace::Options

Options for trace output.

Enumerator:

Blocks	Include PTrace::Block constructs in output If this is bit is clear, all PTrace::Block output is inhibited regardless of the trace level. If set, the PTrace::Block may occur provided the trace level is greater than zero.
DateAndTime	Include date and time in all output.
Timestamp	Include (millisecond) timestamp in all output.
Thread	Include identifier for thread trace is made from in all output.
TraceLevel	Include trace level in all output.
FileAndLine	Include the file and line for the trace call in all output.
ThreadAddress	Include thread object pointer address in all trace output.
AppendToFile	Append to log file rather than resetting every time.
GMTTime	Output timestamps in GMT time rather than local time.
RotateDaily	If set, log file will be rotated daily.
RotateHourly	If set, log file will be rotated hourly.
RotateMinutely	If set, log file will be rotated every minute.
RotateLogMask	Mask for all the rotate bits.
SystemLogStream	SystemLog flag for tracing within a PServiceProcess application. Must be set in conjection with `SetStream(new PSystemLog)`.

Member Function Documentation

static ostream& PTrace::Begin	(	unsigned	level,
		const char *	fileName,
		int	lineNum
	)			`[static]`

Begin a trace output.

If the trace stream output is used outside of the provided macros, it should be noted that a mutex is obtained on the call to Begin() which will prevent any other threads from using the trace stream until the End() function is called.

So a typical usage would be:


    ostream & s = PTrace::Begin(3, __FILE__, __LINE__);
    s << "hello";
    if (want_there)
      s << " there";
    s << '!' << PTrace::End;

Parameters:

level	Log level for output
fileName	Filename of source file being traced
lineNum	Line number of source file being traced.

static PBoolean PTrace::CanTrace ( unsigned level ) [static]

Determine if the level may cause trace output.

This checks against the current global trace level set by SetLevel() for if the trace output may be emitted. This is used by the PTRACE() macro.

Parameters:

level

Trace level to check

static void PTrace::Cleanup ( ) [static]

Cleanup the trace system for a specific thread When using thread local storage, this will delete the per-thread trace context.

static void PTrace::ClearOptions ( unsigned options ) [static]

Clear the trace options.

The PTRACE(), PTRACE_BLOCK() and PTRACE_LINE() macros output trace text that may contain assorted values. These are defined by the Options enum.

Note this function AND's the complement of the bits included in the options parameter.

Parameters:

options

Option bits to turn off

static ostream& PTrace::End ( ostream & strm ) [static]

End a trace output.

If the trace stream output is used outside of the provided macros, the End() function must be used at the end of the section of trace output. A mutex is obtained on the call to Begin() which will prevent any other threads from using the trace stream until the End(). The End() is used in a similar manner to std::endl or std::flush.

So a typical usage would be:


    ostream & s = PTrace::Begin();
    s << "hello";
    if (want_there)
      s << " there";
    s << '!' << PTrace::End;

Parameters:

strm

Trace output stream being completed

static unsigned PTrace::GetLevel ( ) [static]

Get the trace level.

The PTRACE() macro checks to see if its level is equal to or lower then the level set by this function. If so then the trace text is output to the trace stream.

static unsigned PTrace::GetOptions ( ) [static]

Get the current trace options.

The PTRACE(), PTRACE_BLOCK() and PTRACE_LINE() macros output trace text that may contain assorted values. These are defined by the Options enum.

static void PTrace::Initialise	(	unsigned	level,
		const char *	filename,
		const char *	rolloverPattern,
		unsigned	options = `Timestamp\|Thread\|Blocks`
	)			`[static]`

Set the most common trace options.

If filename is not NULL then a PTextFile is created and attached the trace output stream. This object is never closed or deleted until the termination of the program.

If rolloverPatterm is not NULL it is used as the time format patterm appended to filename if the RotateDaily is set. Default is "yyyy_MM_dd".

A trace output of the program name version and OS is written as well.

Parameters:

level	Level for tracing
filename	Filename for log output
rolloverPattern	Pattern for rolling over trace files
options	Options for tracing

static void PTrace::Initialise	(	unsigned	level,
		const char *	filename = `NULL`,
		unsigned	options = `Timestamp\|Thread\|Blocks`
	)			`[static]`

Set the most common trace options.

If filename is not NULL then a PTextFile is created and attached the trace output stream. This object is never closed or deleted until the termination of the program.

There are several special values for filename:

"stderr": Output to standard error
"stdout": Output to standard output
"DEBUGSTREAM": Output to debugger (Windows only)

A trace output of the program name version and OS is written as well.

Parameters:

level	Level for tracing
filename	Filename for log output
options	Options for tracing

static void PTrace::SetLevel ( unsigned level ) [static]

Set the trace level.

The PTRACE() macro checks to see if its level is equal to or lower then the level set by this function. If so then the trace text is output to the trace stream.

Parameters:

level

New level for tracing

static void PTrace::SetOptions ( unsigned options ) [static]

Set the trace options.

The PTRACE(), PTRACE_BLOCK() and PTRACE_LINE() macros output trace text that may contain assorted values. These are defined by the Options enum.

Note this function OR's the bits included in the options parameter.

Parameters:

options

New option bits for tracing

static void PTrace::SetStream ( ostream * out ) [static]

Set the stream to be used for trace output.

This stream is used for all trace output using the various trace functions and macros.

Parameters:

out

New output stream from trace.

PTrace Class Reference

Public Types

Static Public Member Functions

Classes

Detailed Description

Member Enumeration Documentation

Member Function Documentation