LogDispatch - debug module

• Download source files - 40.8 Kb
• Download demo project - 586 Kb

Introduction

Can you imagine the programming process without the possibility of debugging program code at run-time? It is obvious that such programming may exist, but programming without debugging possibility is too complicated when we are working on big and complex projects. In addition to standard approaches of debugging program code such as an output window on Visual Studio IDE or the macros of asserts, I propose a not new method for debugging your code: to output your debugging data to an application which is separated from Visual Studio IDE and the project you are currently working on.

Features

What�s so good about it and should I use it?

• It�s a separated module which allows you to trace and debug the release version of your project.
• It is a fully controlled module with a command set which enables you to control your debugging process: closing tracing windows (also known as trace channel), saving the entry of the trace window to the file, and etc. Full control set is described below.
• This module supports several (number of trace channels is unlimited) strategies of trace channels. Detailed description about trace channels is described below.
• You can easily modify this module to meet your needs.

Behavior

Launch the application of trace messages catcher (next: trace catcher) before you start working with this module. Tracing data, sent to the trace catcher application, will be saved if the catcher application was inactive or was terminated during the trace operations. All the data which have been saved during the critical situations, as described above, will be kept and popped-out to trace catcher application when it starts again. There�s a possibility to start the trace catcher application with the creation of the trace module, and terminate it when the trace module is being destructed.

As I mentioned, this trace module allows you to put your trace data to several output windows in trace catcher application (next: trace channels). Trace channel is a simple window which helps to visualize your tracing data by the trace catcher application. In order to add your trace data to a certain trace channel, you must describe it as follows:

_Log.setSectionName( "channel_#1" );
_Log.dump( "%s", "My trace data" );

or

_Log.dumpToSection( "channel_#1", "%s", "My trace data" );

If you send your trace data to the new trace channel which is not created in the trace catcher application, new trace channel will be created automatically.

In addition to sending your trace data to the catcher, there�s a possibility to manipulate the trace catcher application with commands help. Commands are divided into two parts: global commands, and commands which depend to the trace channel.

Global commands affecting whole trace catcher application:

• closeRoot � close the trace catcher application;
• onTop.ON � enable always on top state for the catcher application;
• onTop.OFF � disable always on top state for the catcher application.

Example:

_Log.sendCmd( "closeRoot" );
_Log.sendCmd( "onTop.ON");

Commands affecting certain trace channels:

• clear - deleting the entry of given trace channel;
• close - closing the given trace channel;
• save <path to output stream> - saving the entry of the given trace channel to output stream described by you.

Example:

_Log.sendCmd( "Channel_1", "clear" );
_Log.sendCmd( "Channel_2", "save c:\\channel2.log" );
_Log.sendCmd( "close" ); /** close the current output window (section) */

How to use-it

In order to fully use this trace module, you have to do only two steps:

• First step: you must copy [LogDispatch.dir] directory from the unzipped source file (LogDispatch_src.zip) to your project directory.
• Second step: you must include the header of this module in your project modules were you want to use-it.

An example:

#include "path_by_you\LogDispathc.dir\LogDispath.h"</pre>

<ClogDispatch> methods

To call all this messages described below, you must use variable names as follows: [_Log]. The trace object is created once during the project life-time (using singleton pattern).

Let's say, calling the dump message will be described like that:

_Log.dump( "System time is %d %d %5.5f ", 15, 10, 08.555121 );

Tracing operations:

• dump � formatted trace data (sprintf format) are sent to catcher application. The tracing data will be placed to the section named as the result of calling method "setSectionName" before that, or if the method "setSectionName" wasn�t called, tracing data will be placed to the default section named as "output@default".
• dumpToSection � the principle is the same as dump message. The difference is that this message will place your data to the channel by name which you described in this message.
• setSectionName � set the working (active) channel name.

Configuration command:

• getCmdPrefix � sets the prefix of the command.
• setCmdPrefix � returns the prefix of the command.
• sendCmd � sends your message to the receiver application.
• setCloseOnExit � enables/disables the possibility to send the message to the catcher application on exit.
• setCloseCMDOnExit � sets the command of the catcher application which will be send when the trace module will be destroyed.

Additional operations of the module configuration:

• setClassNameOfCatcher � set the class name of the catcher application. That class name will be used in search of the catcher application where the tracing data will be sent.
• runCatcher � executing the catcher application from the described path.

Conclusion

This trace module and the strategy we are using on it is very flexible, and is an effective trace tool for debugging big projects. In my opinion, this tool will be a very effective strategy to trace release versions of the projects where all debugging data are removed. Very easy and comfortable to use it :].