PTrace Class Reference

#include <object.h>

List of all members.

Classes

class  Block

Public Types

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)
static void Initialise (unsigned level, const char *filename, const char *rolloverPattern, unsigned options=Timestamp|Thread|Blocks)
static void SetOptions (unsigned options)
static void ClearOptions (unsigned options)
static unsigned GetOptions ()
static void SetLevel (unsigned level)
static unsigned GetLevel ()
static PBoolean CanTrace (unsigned level)
static void SetStream (ostream *out)
static ostream & Begin (unsigned level, const char *fileName, int lineNum)
static ostream & End (ostream &strm)
static void Cleanup ()

Detailed Description

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


Member Enumeration Documentation

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

RotateHourly 
RotateMinutely 
RotateLogMask 
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 PBeginTrace which will prevent any other threads from using the trace stream until the PEndTrace 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 PSetTraceLevel 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 New level for trace
static ostream& PTrace::End ( ostream &  strm  )  [static]

End a trace output. If the trace stream output is used outside of the provided macros, the PEndTrace function must be used at the end of the section of trace output. A mutex is obtained on the call to PBeginTrace which will prevent any other threads from using the trace stream until the PEndTrace. The PEndTrace is used in a similar manner to #endl or #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: yyyy_MM_dd

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

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.

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

Referenced by PTraceLevelSetStartup< level, options >::OnStartup().

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 trace
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 level for trace
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.

The documentation for this class was generated from the following file:

Generated on Sun Sep 6 02:12:27 2009 for PTLib by  doxygen 1.6.1