1.2.1   Macros defined in debug and release modes

INFOS_COMPILATION

The C++ macro INFOS_COMPILATION writes on the trace buffer pool informations about the compiling process:

• the name of the compiler : g++, KCC, CC, pgCC;
• the date and the time of the compiling processing process.

This macro INFOS_COMPILATION does not have any argument. Moreover, it is defined in both compiling mode : _DEBUG_ and _RELEASE_.

Example:

#include "utilities.h"
int main(int argc , char **argv) 
{ 
  INFOS_COMPILATION;
  ...
}
INFOS(str)

INFOS

In both compiling mode _DEBUG_ and _RELEASE_, The C++ macro INFOS writes on the trace buffer pool the string which has been passed in argument by the user.

Example:

#include "utilities.h"
int main(int argc , char **argv)
{ 
  ... 
  INFOS("NORMAL END OF THE PROCESS"); 
  return 0; 
}

displays:

main.cxx [5] : NORMAL END OF THE PROCESS

INTERRUPTION(str)

In both compiling mode _DEBUG_ and _RELEASE_, The C++ macro INTERRUPTION writes on the trace buffer pool the string, with a special ABORT type. When the thread in charge of collecting messages finds this message, it terminates the application, after message treatment.

IMMEDIATE_ABORT(str)

In both compiling mode _DEBUG_ and _RELEASE_, The C++ macro IMMEDIATE_ABORT writes the message str immediately on standard error and exits the application. Remaining messages not treated by the message collector thread are lost.

1.2.2   Macros defined only in debug mode

MESSAGE(str)

In _DEBUG_ compiling mode only, the C++ macro MESSAGE writes on the trace buffer pool the string which has been passed in argument by the user. In _RELEASE_ compiling mode, this macro is blank.

Example:

#include "utilities.h" 
#include <string> 

using namespace std; 

int main(int argc , char **argv) 
{ 
  ... 
  const char *str = "Salome";
  MESSAGE(str);
  ... const string st; 
  st = "Aster"; 
  MESSAGE(c_str(st+" and CASTEM")); 
  return 0;
}

displays:

- Trace main.cxx [8] : Salome
- Trace main.cxx [12] : Aster and CASTEM

BEGIN_OF(func_name)

In _DEBUG_ compiling mode, The C++ macro BEGIN_OF appends the string "Begin of " to the one passed in argument by the user and displays the result on the trace buffer pool. In _RELEASE_ compiling mode, this macro is blank.

Example:

#include "utilities.h" 
int main(int argc , char **argv) 
{ 
  BEGIN_OF(argv[0]);
  return 0;
}

displays:

- Trace main.cxx [3] : Begin of a.out

END_OF(func_name)

In _DEBUG_ compiling mode, The C++ macro END_OF appends the string "Normal end of " to the one passed in argument by the user and displays the result on the trace buffer pool. In _RELEASE_ compiling mode, this macro is blank.

Example:

#include "utilities.h" 
int main(int argc , char **argv) 
{ 
  END_OF(argv[0]);
  return 0; 
}

displays:

- Trace main.cxx [4] : Normal end of a.out

SCRUTE(var)

In _DEBUG_ compiling mode, The C++ macro SCRUTE displays its argument which is an application variable followed by the value of the variable. In _RELEASE_ compiling mode, this macro is blank.

Example:

#include "utilities.h"
int main(int argc , char **argv) 
{ 
  const int i=999;
  if( i > 0 ) SCRUTE(i) ; i=i+1;
  return 0;
}

displays:

- Trace main.cxx [5] : i=999

ASSERT(condition)

In _DEBUG_ compiling mode only, The C++ macro ASSERT checks the expression passed in argument to be not NULL. If it is NULL the condition is written with the macro INTERRUPTION (see above). The process exits after trace of this last message. In _RELEASE_ compiling mode, this macro is blank. N.B. : if ASSERT is already defined, this macro is ignored.

Example:

#include "utilities.h" 
... 
const char *ptrS = fonc();
ASSERT(ptrS!=NULL); 
cout << strlen(ptrS); 
float table[10];
int k;
... 
ASSERT(k<10);
cout << table[k];

2.1.1   definition

The class SALOME_Exception provides a generic method to send a message, with optional source file name and line number. This class is intended to serve as a base class for all kinds of exceptions SALOME code. All the exceptions derived from SALOME_Exception could be handled in a single catch, in which the message associated to the exception is displayed, or sent to a log file.

The class SALOME_Exception inherits its behavior from the STL class exception.

2.1.2   usage

The header SALOME/src/utils/utils_SALOME_Exception.hxx must be included in the C++ source, when raised or trapped:

#include "utils_SALOME_Exception.hxx"

The SALOME_Exception constructor is:

SALOME_Exception( const char *text,
                  const char *fileName=0, 
                  const unsigned int lineNumber=0 );

The exception is raised like this:

throw SALOME_Exception("my pertinent message");

or like this:

throw SALOME_Exception(LOCALIZED("my pertinent message"));

where LOCALIZED is a macro provided with utils_SALOME_Exception.hxx which gives file name and line number.

The exception is handled like this:

try
  {
    ...
  }
catch (const SALOME_Exception &ex)
  {
    cerr << ex.what() <<endl;
  }

The what() method overrides the one defined in the STL exception class.

2.2.1   definition

The idl SALOME_Exception provides a generic CORBA exception for SALOME, with an attribute that gives an exception type,a message, plus optional source file name and line number.

This idl is intended to serve for all user CORBA exceptions raised in SALOME code, as IDL specification does not support exception inheritance. So, all the user CORBA exceptions from SALOME could be handled in a single catch.

The exception types defined in idl are:

• COMM CORBA communication problem,
• BAD_PARAM Bad User parameters,
• INTERNAL_ERROR application level problem (often irrecoverable).

CORBA system and user exceptions already defined in the packages used within SALOME, such as OmniORB exceptions, must be handled separately.

2.2.2   usage

3.1.1   Definition

A singleton is an application data which is created and deleted only once at the end of the application process. The C++ compiler allows the user to create a static singleton data before the first executable statement. They are deleted after the last statement execution.

The SINGLETON_ template class deals with dynamic singleton. It is useful for functor objects. For example, an object that connects the application to a system at creation and disconnects the application at deletion.

3.1.2   Usage

To create a single instance of a POINT object:

# include "Utils_SINGLETON.hxx"
... 
POINT *ptrPoint=SINGLETON_<POINT>::Instance() ; 
assert(ptrPoint!=NULL) ;

No need to delete ptrPoint. Deletion is achieved automatically at exit. If the user tries to create more than one singleton by using the class method SINGLETON_<TYPE>::Instance(), the pointer is returned with the same value even if this is done in different functions (threads ?):

POINT *p1=SINGLETON_<POINT>::Instance() ;
... 
POINT *p2=SINGLETON_<POINT>::Instance() ; 

assert(p1==p2)

3.1.3   Design description

Here are the principles features of the singleton design:

• the user creates an object of class TYPE by using the class method SINGLETON_<TYPE>::Instance() which returns a pointer to the single object ;
• to create an object, SINGLETON_<TYPE>::Instance() uses the default constructor of class TYPE ;
• at the same time, this class method creates a destructor object which is added to the generic list of destructor objects to be executed at the end of the application (atexit) ;
• at the end of the application process all the deletions are performed by the Nettoyage() C function which executes the destruction objects end then deletes the destructions objects themselves ;
• the Nettoyage() C function using atexit() C function is embedded in a static single object ATEXIT_().