next_inactive up previous


Logger: Programming Guide
DocumentId:GradSOft-PR-09.08.2000-v1.2.0

Introduction

Logger is a C++ component, which allow easy add loggin abilities to you application and organize event-depended call of user functions.

This document is an unformal description of package, for full specification, please, see API reference. (www.gradsoft.kiev.ua/common/ToolBox/Logger/API/index.html).

General description

Using of Logger must be follow next pattern:

Compile time settings

It is possible to enable or disable output to logger streams in compile time by setting next preprocessor symbols to values true of false:

Run time settings

Also exists next run-time Logger settings:

Example

which illustrate Logger use is follow:

#define LOG_DEBUG_ENABLE true

#include <GradSoft/Logger.h>

void debug_callback(const char* msg)
{
 cerr << "debug_callback:" << msg << endl;
}

int main(int argc, char** argv)
{
 try {
  GradSoft::Logger logger("file.log");
  logget.setCallback(GradSoft::Debug,debug_callback);
 
  logger.debugs() << "debug output 1 for " << argv[0] << endl; 
 }catch(Logger::IOException){
   cerr << "can't open log file" << endl;
   return 1;
 }

 return 0;
}

Using Logger in multithreaded applications

You can use Logger in muiltithreaded applications: all Logger methods are thread-safe. But during using of logger output streams via operator<< exists potential problem of interference of messages from different streams. For preventing this we reserve mutex for each logger stream and define class - lock guard of this mutex which is lock mutex on creation and unlock on destruction.

So, we reccomend use next code fragment as codding pattern:

 {
  Logger::DebugLocker guard(logger.debugs());
  Logger.debugs() << "print " << "what " << "you " << "want" << endl;
 }

Now more formal definition and naming scheme for locking classes:

For each event type Xxx class Logger::XxxLocker is defined. The methods of Logger::XxxLocker are:

In case, when appropriative debug stream is disabled, lock class is reduces to empty class with empty operations.

Programming Environment Conventions

  1. You standart C++ library must support string type.
  2. Few autoconf-derived macroporocessor variables are defined in file LoggerConfig.h (or LoggerConfingNT.h for Windows) which is generated during Logger installation. before inclusion of file Logger or Logger.h Potentially names of this macroses can potentially conflict with autoconf names of other packages or you main program. To prevent this, we reccomend use #ifdef quards for you autoconf macroses:
    #ifdef HAVE_Xxx  
    #undef HAVE_Xxx  
    #endif
    
  3. Using Logger on Windows NT, you must:
    1. to define WIN32 macro before inclusion of Logger.h header file;
    2. to use iostream, fstream, etc. standard headers instead iostream.h, fstream.h, etc. ones.

Changes

03.01.2002
- updated in accordance with GradC++ToolBox 1.4.0
03.07.2001
- changed example: removed using of deprecated header GradSoft/Logger
02.06.2001
- changed programming environment and added sections about 1.2.0 features.
18.02.2001
- review, added formal document attributes.
09.08.2000
- initial revision.


next_inactive up previous
GradSoft