ot
class Tracer  (abstract)

Traditionally, C++ applications use a pre-processor macro-based approach to tracing. The implementations are sometimes inefficient and often restricted to debug builds of the program.

OpenTop takes a different approach. The Tracer class provides an abstract interface for raising trace events and for controlling which events should be recorded. We do provide an example implementation in the form of the TraceHelper class, but applications are free to implement their own Tracer class which offers the desired level of performance and functionality. For example, the TraceHelper class writes trace events to a file, but it would be possible for other implementations to write to a memory buffer, to a console or both. One important feature of OpenTop tracing is that it is available in both the debug and release builds of the library.

The Tracer class is both a class module, containing static methods to raise and control the output of trace events, as well as an abstract base class which must be derived from when creating a concrete implementation.

The static tracing methods are called from many OpenTop service routines when performing significant tasks such as creating network connections, opening files or starting and stopping threads. These static methods, in turn, call virtual member functions which must be implemented by a concrete Tracer class.

Finally, the OpenTop tracing service is extensible, allowing application code to be traced as well as OpenTop system calls.

Activate

static void Activate(short nSection,
                     short nLevel)

Informs the registered Tracer that events for the specified section with a level less than or equal to nLevel should be processed. This passes the request to the registered Tracer object's virtual doActivate() method.

A concrete Tracer implementation may maintain a table of section names together with the level of tracing that has been requested for each one. For example, it may record that the user wants all network access to be logged, but only exceptions from other sections of the library.

Note that the Tracer must be both activated and enabled before any trace events will be processed.

Parameters:

nSection - the identifier of the section of code that raises events. OpenTop trace events use a member from the Tracer::Sections enumeration, user trace events can use an assigned number starting with Tracer::User.
nLevel - a short integer indicating the level to which trace events should be processed. The higher the number, the more tracing that will be produced.

See also:

Enable()

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

doActivate

protected virtual void doActivate(short nSection,
                                  short nLevel)=0

Virtual function called in response to Activate(). Concrete implementations are expected to maintain a table representing the sections of code which have had tracing enabled, and the level of tracing to be performed for each section.

Parameters:

nSection - the identifier of the section of code that raises events. OpenTop trace events use a member from the Tracer::Sections enumeration, user trace events can use an assigned number starting with Tracer::User.
nLevel - a short integer indicating the level to which trace events should be processed for the specified section.

See also:

Activate()

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

doTrace

protected virtual void doTrace(short nSection,
                               short nLevel,
                               const CharType* message,
                               size_t len)=0

Virtual function called in response to Trace().

Parameters:

nSection - the identifier of the section of code that's raising the event. OpenTop trace events use a member from the Tracer::Sections enumeration, user trace events can use an assigned number starting with Tracer::User.
nLevel - a short integer indicating the relative importance of the trace event. The value should be between Tracer::Highest and Tracer::Min. The Tracer implementation can use this value when deciding how to process an event. In general, a lower number indicates a more severe condition which is more likely to be processed.
message - a string describing the trace event.
len - the length of the message.

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

doTraceBytes

protected virtual void doTraceBytes(short nSection,
                                    short nLevel,
                                    const String& message,
                                    const Byte* bytes,
                                    size_t len)=0

Virtual function called in response to Trace().

Parameters:

nSection - the identifier of the section of code that's raising the event. OpenTop trace events use a member from the Tracer::Sections enumeration, user trace events can use an assigned number starting with Tracer::User.
nLevel - a short integer indicating the relative importance of the trace event. The value should be between Tracer::Highest and Tracer::Min. The Tracer implementation can use this value when deciding how to process an event. In general, a lower number indicates a more severe condition which is more likely to be processed.
message - a string describing the trace event.
bytes - a pointer to an array of bytes representing the detail of the event
len - the length of the byte array

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

Enable

static void Enable(bool bEnable)

Enables or disables tracing. This acts as a simple on/off switch for tracing. Unless tracing has been enabled, the doTrace() method is never called.

Enable() has no effect on the activation options in effect, so it is possible to specify which sections of code should be traced, but not actually have tracing enabled. This makes it easy to enable and disable tracing at various points within an application without having to deal with the individual activation options each time.

Parameters:

bEnable - true to enable tracing; false to disable tracing

See also:

Activate() , IsEnabled()

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

GetSectionName

static const CharType* GetSectionName(short nSection)

Translates a numeric section identifier into a null-terminated CharType string. The returned string will be used when formatting trace output for display.

If nSection is within the OpenTop assigned range, a pre-determined section name is returned. Otherwise the request is delegated to the registered Tracer object (if any).

Parameters:

nSection - the identifier of the section.

Returns:

a null-terminated CharType array or 0 if the section is not recognized.

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

GetSectionNumber

static short GetSectionNumber(const String& section)

Translates a section name into a numeric identifier. if section is a OpenTop assigned name, a pre-determined section identifier is returned. Otherwise the request is delegated to the registered Tracer object (if any).

Parameters:

section - the name of the section.

Returns:

a numeric section identifier or -1 if the section is not recognized.

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

getUserSectionName

protected virtual const CharType* getUserSectionName(short nSection)

Returns the name of the code section with the supplied identifier. If an application makes use of tracing in sections of user code, an identifier must be selected starting with the value Tracer::User. A concrete Tracer implementation should be registered which will translate between the section identifier and its name.

For optimum tracing efficiency, a CharType pointer is returned instead of a String. The puts a requirement on concrete implementations to ensure that the returned pointer references a valid memory location which is constant. Furthermore, regard should be given to the fact that this method may be called concurrently from multiple threads, therefore it would not be appropriate to allocate a single static buffer and update its contents with the results from each call.

Parameters:

nSection - the section identifier for the user code section.

Returns:

a pointer to a static CharType array or null. The caller does not receive ownership of the returned array pointer and must not attempt to free it.

See also:

getUserSectionNumber()

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

getUserSectionNumber

protected virtual short getUserSectionNumber(const String& section)

Returns the name of the code section with the supplied identifier or -1 if the identifier is not recognized. If an application makes use of tracing in sections of user code, an identifier must be selected starting with the value Tracer::User. A Concrete implementation of Tracer should be registered which will translate between the section identifier and its name.

Parameters:

section - the name of the user code section.

See also:

getUserSectionName()

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

IsEnabled

static bool IsEnabled()

Tests whether tracing has been enabled.

Returns:

true if tracing has been enabled; false otherwise

See also:

Enable()

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

SetTracer

static void SetTracer(Tracer* pTracer)

Sets the system Tracer object. There is only one Tracer object active at any point in time, use this method to register an instance of a Tracer object as the active Tracer.

To ensure that the passed object exists for as long as the application needs it, the Tracer object is registered with the system's ObjectManager which holds a (counted) reference to it until system termination.

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

Trace

static void Trace(short nSection,
                  short nLevel,
                  const String& message)

Raises a trace event. If tracing has been enabled and a concrete Tracer class has been registered, its doTrace() method is called with the parameters passed. The concrete implementation of Tracer which has been registered is responsible for processing the event.

Parameters:

nSection - the identifier of the section of code that's raising the event. OpenTop trace events use a member from the Tracer::Sections enumeration, user trace events can use an assigned number starting with Tracer::User.
nLevel - a short integer indicating the relative importance of the trace event. The value should be between Tracer::Highest and Tracer::Min. The Tracer implementation can use this value when deciding how to process an event. In general, a lower number indicates a more severe condition which is more likely to be processed.
message - a string describing the trace event

See also:

SetTracer() , doTrace()

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

Trace

static void Trace(short nSection,
                  short nLevel,
                  const CharType* message,
                  size_t len)

Raises a trace event. If tracing has been enabled and a concrete Tracer class has been registered, its doTrace() method is called with the parameters passed. The concrete implementation of Tracer which has been registered is responsible for processing the event.

Parameters:

nSection - the identifier of the section of code that's raising the event. OpenTop trace events use a member from the Tracer::Sections enumeration, user trace events can use an assigned number starting with Tracer::User.
nLevel - a short integer indicating the relative importance of the trace event. The value should be between Tracer::Highest and Tracer::Min. The Tracer implementation can use this value when deciding how to process an event. In general, a lower number indicates a more severe condition which is more likely to be processed.
message - a string describing the trace event
len - the length of the message string

See also:

SetTracer() , doTrace()

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.

TraceBytes

static void TraceBytes(short nSection,
                       short nLevel,
                       const String& message,
                       const Byte* bytes,
                       size_t len)

Raises a trace event. If tracing has been enabled and a concrete Tracer class has been registered, its doTrace() method is called with the parameters passed. The concrete implementation of Tracer which has been registered is responsible for processing the event.

Parameters:

nSection - the identifier of the section of code that's raising the event. OpenTop trace events use a member from the Tracer::Sections enumeration, user trace events can use an assigned number starting with Tracer::User.
nLevel - a short integer indicating the relative importance of the trace event. The value should be between Tracer::Highest and Tracer::Min. The Tracer implementation can use this value when deciding how to process an event. In general, a lower number indicates a more severe condition which is more likely to be processed.
message - a string describing the trace event.
bytes - a pointer to an array of bytes representing the detail of the event
len - the length of the byte array

See also:

SetTracer() , doTrace()

Multi-threaded considerations:

Can safely be called from multiple concurrent threads.