The Execution Tracing package includes a singleton trace manager object, which receives trace events generated by the event generation macros. The trace manager then forwards these messages to the connected client for further processing.
When the first event generation macro is executed, it automatically instantiates the singleton trace manager, so there is almost no need for your programs to care about its existence. In fact, if you try to instantiate a trace manager object yourself, you get a compile error.
The trace manager maintains a circular buffer that accumulates trace events when no client is connected to the manager. For example, any trace events that are generated in global constructors before a client is connected go into the buffer.
The number of buffered events defaults to 100, but it can be reset with the environment variable RW_TRACE_BUFFER_SIZE. When buffer contains the maximum number of trace events, the oldest is removed to make room for the newest one.
When a client connects to the manager, any buffered messages are immediately forwarded to the client. To ensure that all trace events are passed through all the clients and filters you create, connect the filters and clients together first, then make the final connection to the manager. When the client is disconnected from the manager, buffering resumes.
The only time it is necessary for user code to interact with the manager directly is when it is required to stop tracing at runtime. To stop all tracing, use the static member function RWTraceManager::disconnectClient() to disconnect the client or filter. When the manager is disconnected, it begins buffering trace events, so none are lost until the buffer is full. When the client is connected again, the buffered messages are immediately forwarded to the client.
In addition to the RW_TRACE_BUFFER_SIZE environment variable, the trace manager also looks at the RW_TRACE_LEVEL environment variable. This is another method of filtering trace events at runtime. The environment variable can be set to one of these values: FATAL, ERROR, WARNING, INFO, TEST, DEBUG, ENTRY.
Before forwarding the trace event, the trace manager looks at this environment variable and does not forward any event that is less severe than the level specified. This variable defaults to ENTRY, thus letting all the (compiled-in) events through. See Section 6.10, "Controlling Trace Output," for a discussion of compile-time versus runtime filtering of trace events.
©Copyright 2000, Rogue Wave Software, Inc.
Contact Rogue Wave about documentation or support issues.