PTLib Version 2.12.9

- Main Page
- Related Pages
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Classes | Public Types | Static Public Member Functions | List of all members
PTrace Class Reference

Class to encapsulate tracing functions. More...

`#include <object.h>`

## Classes
class | Block
| Class to trace Execution blocks. More...

## Public Types
enum | Options { Blocks = 0x0001, DateAndTime = 0x0002, Timestamp = 0x0004, Thread = 0x0008, TraceLevel = 0x0010, FileAndLine = 0x0020, ThreadAddress = 0x0040, AppendToFile = 0x0080, GMTTime = 0x0100, RotateDaily = 0x0200, RotateHourly = 0x0400, RotateMinutely = 0x0800, RotateLogMask = RotateDaily + RotateHourly + RotateMinutely, ObjectInstance = 0x1000, ContextIdentifier = 0x2000, SystemLogStream = 0x8000 }
| Options for trace output. More...

## Static Public Member Functions
static void | Initialise (const PArgList &args, unsigned options=Timestamp|Thread|Blocks, const char *traceLevel="trace", const char *outputFile="output", const char *traceOpts="trace-option", const char *traceRollover="trace-rollover")
| Set the most common trace options. More...
static void | Initialise (unsigned level, const char *filename=NULL, unsigned options=Timestamp|Thread|Blocks, const char *rolloverPattern=NULL)
| Set the most common trace options. More...
static void | Initialise (unsigned level, const char *filename, const char *rolloverPattern, unsigned options=Timestamp|Thread|Blocks)
static void | SetOptions (unsigned options)
| Set the trace options. More...
static void | ClearOptions (unsigned options)
| Clear the trace options. More...
static unsigned | GetOptions ()
| Get the current trace options. More...
static void | SetLevel (unsigned level)
| Set the trace level. More...
static unsigned | GetLevel ()
| Get the trace level. More...
static PBoolean | CanTrace (unsigned level)
| Determine if the level may cause trace output. More...
static void | SetStream (ostream *out)
| Set the stream to be used for trace output. More...
static ostream * | GetStream ()
| Get the stream being used for trace output. More...
static ostream & | Begin (unsigned level, const char *fileName, int lineNum, const PObject *instance=NULL, const char *module=NULL)
| Begin a trace output. More...
static ostream & | Begin (unsigned level, const char *fileName, int lineNum, const char *module, const PObject *instance, const char *defModule)
static ostream & | Begin (unsigned level, const char *fileName, int lineNum, const PObject *instance, const PObject *defInstance, const char *module)
static ostream & | End (ostream &strm)
| End a trace output. More...
static unsigned | GetNextContextIdentifier ()

## 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, as a numeric value, 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.
ObjectInstance | Include object instance in all trace output.
ContextIdentifier | Include context identifier in all trace output.
SystemLogStream | SystemLog flag for tracing within a PServiceProcess application. Setting this flag will automatically execute `#SetStream(new PSystemLog)`.

## Member Function Documentation

static ostream& PTrace::Begin | ( | unsigned | level,
|  | const char * | fileName,
|  | int | lineNum,
|  | const PObject * | instance = `NULL`,
|  | const char * | module = `NULL`
| ) |  |
| 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.
  instance | Instance for object logging occurred in
  module | Module or subsection string

static ostream& PTrace::Begin | ( | unsigned | level,
|  | const char * | fileName,
|  | int | lineNum,
|  | const char * | module,
|  | const PObject * | instance,
|  | const char * | defModule
| ) |  |
| inline static

Parameters

  level | Log level for output
  fileName | Filename of source file being traced
  lineNum | Line number of source file being traced.
  module | Module or subsection string
  instance | Instance for object logging occurred in

References Begin().

Referenced by Begin().

static ostream& PTrace::Begin | ( | unsigned | level,
|  | const char * | fileName,
|  | int | lineNum,
|  | const PObject * | instance,
|  | const PObject * | defInstance,
|  | const char * | module
| ) |  |
| inline static

Parameters

  level | Log level for output
  fileName | Filename of source file being traced
  lineNum | Line number of source file being traced.
  instance | Instance for object logging occurred in
  module | Module or subsection string

References Begin().

Referenced by Begin().

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::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::GetNextContextIdentifier | ( |  | ) |
| static

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 ostream* PTrace::GetStream | ( |  | ) |
| static

Get the stream being used for trace output.

static void PTrace::Initialise | ( | const PArgList & | args,
|  | unsigned | options = `Timestamp|Thread|Blocks`,
|  | const char * | traceLevel = `"trace"`,
|  | const char * | outputFile = `"output"`,
|  | const char * | traceOpts = `"trace-option"`,
|  | const char * | traceRollover = `"trace-rollover"`
| ) |  |
| static

Set the most common trace options.

This sets trace options based on command line arguments.

Parameters

  args | Command line arguments
  options | Default Options for tracing
  traceLevel | Argument option name for trace level
  outputFile | Argument option name for log output file
  traceOpts | Argument option name for trace options
  traceRollover | Argument option name for trace file roll over pattern

static void PTrace::Initialise | ( | unsigned | level,
|  | const char * | filename = `NULL`,
|  | unsigned | options = `Timestamp|Thread|Blocks`,
|  | const char * | rolloverPattern = `NULL`
| ) |  |
| 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)
"syslog,ident,priority,options,facility"
  Output to syslog (Unix variants only) The ident, priority, options & facility components are optional, so "syslog", "syslog,myappname", "syslog,myappname,3" are all acceptable. See PSystemLogToSyslog for their exact meaning.
"network,host:port,facility"
  Output to RFC3164 network log server. The server and facility components are optional. The default server would be "localhost" Also, the port is an optional field for the server component, defaulting to the RFC3164 standard value. So, "network,10.0.1.1" or "network,fred:1234" are acceptable. See PSystemLogToNetwork for more.

If `rolloverPattern` is not NULL it is used as the time format pattern appended to filename if the RotateLogMask bits are set. Default is "yyyy_MM_dd".

A trace output of the program name, version, OS abnd other information is written to the log immediately.

Parameters

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

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

References Initialise().

Referenced by Initialise().

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