# PTrace Class Reference

Class to encapsulate tracing functions. More...

`#include <object.h>`

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

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.

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

- PTRACE()
- PTRACE_IF()
- PTRACE_PARAM()
- PTRACE_BLOCK()
- PTRACE_LINE()

## 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.

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

- object.h