OBT::Tracer

OBT::Tracer Class Reference

Tracer used to output messages. More...

#include <OBTTrace.h>

Collaboration diagram for OBT::Tracer:

Collaboration graph
[legend]

List of all members.

Public Member Functions

unsigned int registerId (const char *id)
 Registers a new id in the ones which will be traced.
void unregisterId (const char *id)
 Unregisters an id.
void traceAll (bool b=true)
 Sets the flag to trace all the messages.
void traceNone (bool b=true)
 Sets the flag to trace all the messages.
void setFile (const char *file=0)
 Activates the dump of the messages on a file.
void setOutput (TracerOutput *output, bool disable)
 Activates the output in an additional output.
void trace (const char *id, const char *fct, const char *file, const int line, const char *msg)
 Traces the message.
void trace (unsigned int id, const char *fct, const char *file, const int line, const char *msg)
 Traces the message.
bool test (const char *id)
 Test if the id is traced.
bool test (unsigned int id)
 Test if the id is traced.
 ~Tracer ()
 Destructor.

Protected Member Functions

 Tracer ()
 Private constructor.
void traceWithoutTest (const char *id, const char *fct, const char *file, const int line, const char *msg)
 Traces the message without test the id.
unsigned int getHashId (const std::string &id)
 Compute the hash id for a string id.

Protected Attributes

std::ofstream _fileOut
 The output file.
bool _traceAll
 The trace all flag.
bool _traceNone
 The trace none flag.
bool _disable
 The disable flag.
std::map< unsigned
int, std::string > 		_tracedIds
 The set of the traced ids.
TracerOutput * _output
 The object which outputs the message.

Friends

class Singleton< Tracer >
 The singleton is a friend.

Detailed Description

Tracer used to output messages.

This tracer singleton gives an easy way to create a log in your programs. In the log, only the registered ids are displayed.

Usage
To use the trace you must register the ids. To do that you can define a function like this: 
void initTracer( bool traceAll, const std::string& file )
{
  #if !defined NDEBUG
  OBT::Singleton< OBT::Tracer >::getInstance().traceAll( traceAll ) ; // To display all traces
  OBT::Singleton< OBT::Tracer >::getInstance().setFile( file ) ;      // To put the traces in the file

  // Other ids to register
  OBT::Singleton< OBT::Tracer >::getInstance().registerId( "MyWarning" ) ;
  ...
  #endif // !NDEBUG
}
And call it in the begining of your main function: 
int main( int argc, char* argv[] ) 
{ 
  initTracer( true, string() ) ; // All trace / No file
  ...
}
To display a message in the log 
TRACE( "MyWarning", "the message " << "is build " << "with a stream " << myData ) ;
The result with Windows will be (in visual studio format double click on the line will go to the right line in the file) 
[MyWarning] in "myObject::myFunction" of myFile.cpp@100
the message is build with a stream 365
The result with Linux will be (copy/paste the file name and line to go to the right line in the file with vim) 
[MyWarning] in "myFunction" of myFile.cpp +100 : the message is build with a stream 365

Ids
To increase performance, all the registered ids are stored in a map which is indexed by the hash code of the string. For better performances, it is better to use the hash code instead of the string, nevertheless bost work well.

To use unsigned int instead of string, the returned id gave by registerId must be stored to be use by the TRACE macro.

unsigned int MyWarning = OBT::Singleton< OBT::Tracer >::getInstance().registerId( "MyWarning" ) ;
then you can use 
TRACE( MyWarning, "the message " << "is build " << "with a stream " << myData ) ;
The performance is increased because the hash code don't need to be compute anymore.

Other commands
The traceNone takes precedence over traceAll.

trace and test methods are used by the macros, so you have not to use them directly.

Definition at line 138 of file OBTTrace.h.

Constructor & Destructor Documentation

Tracer::~Tracer (  ) 

Destructor.

Definition at line 39 of file OBTTrace.cpp.

References _fileOut, and _output.

00040 {
00041         delete _output ;
00042     if ( _fileOut.is_open() )
00043     {
00044       _fileOut.close() ;
00045     }
00046 
00047 }

Tracer::Tracer (  )  [protected]

Private constructor.

Definition at line 26 of file OBTTrace.cpp.

00027 : 
00028 _traceAll( false ),
00029 _traceNone( false ),
00030 _disable( false ),
00031 _tracedIds(),
00032 _output( 0 )
00033 {
00034 }

Member Function Documentation

unsigned int Tracer::registerId ( const char *  id  ) 

Registers a new id in the ones which will be traced.

Parameters:
[in] id The new id.
Returns:
0 if id was already registered and the reference integer id if id was inserted

Definition at line 105 of file OBTTrace.cpp.

References _tracedIds, and getHashId().

00106 { 
00107   int intId = getHashId( id ) ;
00108   bool isNewId = _tracedIds[ intId ] != id ;
00109         // inserts the new id or update the values
00110   _tracedIds[ intId ] = id ;
00111 
00112   return isNewId ? intId : 0 ;
00113 }

void Tracer::unregisterId ( const char *  id  ) 

Unregisters an id.

Parameters:
[in] id The id to remove.

Definition at line 118 of file OBTTrace.cpp.

References _tracedIds, and getHashId().

00119 { 
00120   int intId = getHashId( id ) ;
00121   _tracedIds.erase( intId ) ;
00122 }

void Tracer::traceAll ( bool  b = true  ) 

Sets the flag to trace all the messages.

Parameters:
[in] b The value of the flag. True is the default
traceAll is inefficient if traceNone is called.

Definition at line 142 of file OBTTrace.cpp.

References _traceAll.

00143 { 
00144         // sets the flag
00145         _traceAll = b ; 
00146 }

void Tracer::traceNone ( bool  b = true  ) 

Sets the flag to trace all the messages.

Parameters:
[in] b The value of the flag. True is the default

Definition at line 151 of file OBTTrace.cpp.

References _traceNone.

00152 { 
00153         // sets the flag
00154   _traceNone = b ;
00155 }

void Tracer::setFile ( const char *  file = 0  ) 

Activates the dump of the messages on a file.

Parameters:
[in] file The name of the file, if empty no file will be created, it is the default.
Close the previous file if necessary.

Definition at line 161 of file OBTTrace.cpp.

References _fileOut.

00162 {
00163         if( file )
00164         {
00165                 // First close the previous file
00166                 if ( _fileOut.is_open() )
00167                 {
00168                         _fileOut.close() ;
00169                 }
00170 
00171                 // Open the new one
00172                 _fileOut.open( file, ios_base::trunc ) ;
00173         }
00174 }

void Tracer::setOutput ( TracerOutput *  output,
bool  disable 
)

Activates the output in an additional output.

Parameters:
[in] output The additional output.
[in] disable To disable the std::cerr output during the validity of tha additional output. If output is null automatically set disable to false.
Destroy the previous output if necessary. Be carreful, Ogre visualisation creates its own output, it can destroy yours.

Definition at line 180 of file OBTTrace.cpp.

References _disable, and _output.

00181 {
00182         // First delete the previous output
00183         delete _output ;
00184         // set the new one
00185         _output = output ;
00186         // set the disable flag
00187         _disable = disable && output ; // if(output == null) then enable the cerr output even if disable is true
00188 }

void OBT::Tracer::trace ( const char *  id,
const char *  fct,
const char *  file,
const int  line,
const char *  msg 
) [inline]

Traces the message.

Parameters:
[in] id The id of the trace.
[in] file The name of the current code file.
[in] line The number of the current line.
[in] txt The message.
You should not use this method, instead you should use the following macros:

Definition at line 197 of file OBTTrace.h.

00197                                 { if ( test( id ) )     { traceWithoutTest( id, fct, file, line, msg ) ; } }
00200   void trace(   unsigned int id, 
00201               const char* fct,

void OBT::Tracer::trace ( unsigned int  id,
const char *  fct,
const char *  file,
const int  line,
const char *  msg 
) [inline]

Traces the message.

Definition at line 204 of file OBTTrace.h.

00204                                 { if ( test( id ) )     { traceWithoutTest( _tracedIds[ id ].c_str(), fct, file, line, msg ) ; } }

bool Tracer::test ( const char *  id  ) 

Test if the id is traced.

Parameters:
[in] id The id of the trace which will be done.
You should not use this method. It is used by the macros to know if the message must be displayed.

Definition at line 52 of file OBTTrace.cpp.

References _traceAll, _tracedIds, _traceNone, and getHashId().

00053 {
00054         return !_traceNone && ( _traceAll || _tracedIds.find( getHashId( id ) ) != _tracedIds.end() ) ;
00055 }

bool Tracer::test ( unsigned int  id  ) 

Test if the id is traced.

Definition at line 60 of file OBTTrace.cpp.

References _traceAll, _tracedIds, and _traceNone.

00061 {
00062         return !_traceNone && ( _traceAll || _tracedIds.find( id ) != _tracedIds.end() ) ;
00063 }

void Tracer::traceWithoutTest ( const char *  id,
const char *  fct,
const char *  file,
const int  line,
const char *  msg 
) [protected]

Traces the message without test the id.

Definition at line 68 of file OBTTrace.cpp.

References _disable, _fileOut, _output, and OBT::TracerOutput::trace().

00073 {
00074         // must be traced
00075         ostringstream stream ;
00076 #ifdef _MSC_VER
00077   // The debug message is set for the visual studio format
00078         stream << "[" << id << "] in \"" << fct << "\" of " <<  file << "@" << line << endl <<  msg << endl ;
00079 #else
00080   // The debug message is set for the vim format
00081         stream << "[" << id << "] in \"" << fct << "\" of " <<  file << " +" << line << " : " <<msg << endl ;
00082 #endif
00083         // Traces the message on cerr
00084         if( !_disable )
00085         {
00086                 cerr << stream.str() << endl ;
00087         }
00088 
00089         // Traces the message on the file, if it is defined 
00090         if( _fileOut.is_open() )
00091         {
00092                 _fileOut << stream.str() << endl ;
00093                 _fileOut.flush() ;
00094         }
00095 
00096         if( _output )
00097         {
00098                 _output->trace( id, fct, file, line, msg ) ;
00099         }
00100 }

unsigned int Tracer::getHashId ( const std::string &  id  )  [protected]

Compute the hash id for a string id.

Parameters:
[in] id The id of the trace.
Returns:
the hash integer id.

Definition at line 127 of file OBTTrace.cpp.

Referenced by registerId(), test(), and unregisterId().

00128 {
00129   unsigned int a = 64187 ;
00130   unsigned int b = 378533 ;
00131   unsigned int hashId = 0 ;
00132   for( std::size_t i = 0; i < id.length() ; i++ )
00133   {
00134     hashId = hashId * a + id[i] ;
00135     a = a * b;
00136   }
00137   return hashId ;
00138 }

Friends And Related Function Documentation

friend class Singleton< Tracer > [friend]

The singleton is a friend.

Definition at line 141 of file OBTTrace.h.

Member Data Documentation

std::ofstream OBT::Tracer::_fileOut [protected]

The output file.

Defined by traceOnFile.

Definition at line 228 of file OBTTrace.h.

Referenced by setFile(), traceWithoutTest(), and ~Tracer().

bool OBT::Tracer::_traceAll [protected]

The trace all flag.

Defined by traceAll.

Definition at line 232 of file OBTTrace.h.

Referenced by test(), and traceAll().

bool OBT::Tracer::_traceNone [protected]

The trace none flag.

Defined by traceNone.

Definition at line 235 of file OBTTrace.h.

Referenced by test(), and traceNone().

bool OBT::Tracer::_disable [protected]

The disable flag.

Use to disable the std::cerr output when a _output is set.

Definition at line 239 of file OBTTrace.h.

Referenced by setOutput(), and traceWithoutTest().

std::map< unsigned int, std::string > OBT::Tracer::_tracedIds [protected]

The set of the traced ids.

Feed by traceAll.

Definition at line 243 of file OBTTrace.h.

Referenced by registerId(), test(), and unregisterId().

TracerOutput* OBT::Tracer::_output [protected]

The object which outputs the message.

Set by .

Definition at line 247 of file OBTTrace.h.

Referenced by setOutput(), traceWithoutTest(), and ~Tracer().

Generated on Wed Oct 1 11:34:22 2008 for OBT by  doxygen 1.5.3