Creating User-defined Clients
If you need a client to do something more exotic than send trace output to an ostream, you need to define your own trace client class. For example, you could send the trace data out over a socket or perhaps over a serial line for remote debugging. The example in this section simply adds a timestamp to each trace message before sending it to an ostream.
NOTE: Do not embed trace macros in the client’s trace event processing code. To prevent infinite recursion, the trace manager ignores any trace messages generated by a client.
Figure 32 shows the trace client classes. Like other Threads Module packages, the Execution Tracing package uses the handle-body idiom. For example, an RWTraceOstreamClient object is a handle to an RWTraceOstreamClientImp instance, which actually processes the trace messages. RWTraceOstreamClient and RWTraceOstreamClientImp together form a complete client.
Figure 32 – Architecture of RWTraceOstreamClient and its related classes
To create your own trace client, you must supply a new implementation derived from the body class RWTraceEventClientImp. If your client’s body class has any new public member functions (in addition to those inherited from WTraceEventClientImp), you also need to create a new handle class that forwards those calls to your body. The handle must be derived from RWTraceEventClient.
The RWTraceEventClientImp::doTrace() function, which actually processes the trace events, is declared pure-virtual, so a derived body class must provide an implementation of this function. If you do not create your own derived handle class, the body class must also supply a static make() function. The function constructs a body and returns a handle to it, similar to Example 51.
Example 51 – Providing a static make function for a derived body class
static RWTraceOstreamClient make(std::ostream& ostr = std::cerr) {
return new TimeStampClientImp(ostr);
}
NOTE: The returned handle's type is actually the parent class of your derived handle.
The above code is from buildspace\examples\threads\trace\example4.cpp, which shows how to create a client both ways, with or without a derived handle.
