From e5dd32f1b358b8b07863dddcd71e0a8109614b2f Mon Sep 17 00:00:00 2001
From: prascle During the development process, an execution log is useful to
identify problems. This log contains messages, variables values,
source files names and line numbers. It is recommended to verify
assertions on variables values and if necessary, to stop the execution
-at debug time, in order to validate all parts of code.
-
-1. Trace and debug Utilities
+1. Trace and debug Utilities
1.1 Two modes: debug and release
+at debug time, in order to validate all parts of code.
The goal of debug mode is to check as many features as possible during the early stages of the development process. The purpose of the utilities provided in SALOME is to help the developer to add detailed traces and check variables values, without writing a lot -of code. +of code.
+When the code is assumed to be valid, the release mode optimizes execution, in terms of speed, memory, and display only user level -messages. +messages.
+But, some informations must always be displayed in both modes: especially messages concerning environment or internal errors, with version identification. When an end user is confronted to such a message, he may refer to a configuration documentation or send the message to the people in charge of SALOME installation, or to the -development team, following the kind of error. -
SALOME provides C++ macros for trace and debug. These macros
-are in SALOME/src/utils/utilities.h
and this file must be included
-in C++ source. Some macros are activated only in debug mode, others
-are always activated. To activate the debug mode, _DEBUG_
must be
-defined, which is the case when SALOME Makefiles are generated from
-configure, without options. When _DEBUG_
is undefined (release mode),
-the debug mode macros are defined empty (they do nothing). So, when
-switching from debug to release, it is possible (and recommended)
-to let the macro calls unchanged in the source.
-
All the macros writing on the standard output start by flushing -the standard error. At the end of the display those macros flush -the standard output. -
Two informations are systematically added in front of the information
-displayed:
+are in SALOME/src/SALOMELocalTrace/utilities.h
and this file must
+be included in C++ source. Some macros are activated only in debug
+mode, others are always activated. To activate the debug mode, _DEBUG_
+must be defined, which is the case when SALOME Makefiles are generated
+from configure, without options. When _DEBUG_
is undefined (release
+mode: configure --disable-debug --enable-production
), the debug mode
+macros are defined empty (they do nothing). So, when switching from
+debug to release, it is possible (and recommended) to let the macro
+calls unchanged in the source.
All the macros generate trace messages, stored in a circular +buffer pool. A separate thread reads the messages in the buffer pool, +and, depending on options given at SALOME start, writes the messages +on the standard output, a file, or send them via CORBA, in case of +a multi machine configuration.
+ +Three informations are systematically added in front of the information +displayed:
+
The C++ macro INFOS_COMPILATION
writes on the standard output
-informations about the compiling process:
+
The C++ macro INFOS_COMPILATION
writes on the trace buffer pool
+informations about the compiling process:
g++, KCC, CC, pgCC
;This macro INFOS_COMPILATION
does not have any argument. Moreover,
-it is defined in both compiling mode : _DEBUG_
and _RELEASE_
.
-
Example :
+it is defined in both compiling mode : _DEBUG_
and _RELEASE_
.
Example :
+
#include "utilities.h" @@ -81,12 +99,15 @@ int main(int argc , char **argv) ... }+
In both compiling mode _DEBUG_
and _RELEASE_
, The C++ macro INFOS
-writes on the standard output the string which has been passed in
-argument by the user.
-
Example : +writes on the trace buffer pool the string which has been passed +in argument by the user.
+ +Example :
+
#include "utilities.h" @@ -97,19 +118,39 @@ int main(int argc , char **argv) return 0; }-
displays : +
+displays :
+
main.cxx [5] : NORMAL END OF THE PROCESS ++ +
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.
In both compiling mode _DEBUG_
and _RELEASE_
, The C++ macro IMMEDIATE_ABORT
+writes the message immediately on standard error and exits the application.
+Remaining messages not treated by the message collector thread are
+lost.
In _DEBUG_
compiling mode only, the C++ macro MESSAGE
writes
-on the standard output the string which has been passed in argument
-by the user. In _RELEASE_
compiling mode, this macro is blank.
-
Example :
+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" @@ -126,19 +167,24 @@ int main(int argc , char **argv) return 0; }-
displays : +
+displays :
+
- Trace main.cxx [8] : Salome - Trace main.cxx [12] : Aster and CASTEM+
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 standard output. In _RELEASE_
-compiling mode, this macro is blank.
-
Example :
+user and displays the result on the trace buffer pool. In _RELEASE_
+compiling mode, this macro is blank.
Example :
+
#include "utilities.h" @@ -148,18 +194,23 @@ int main(int argc , char **argv) return 0; }-
displays : +
+displays :
+
- Trace main.cxx [3] : Begin of a.out+
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 standard output. In _RELEASE_
compiling
-mode, this macro is blank.
-
Example :
+and displays the result on the trace buffer pool. In _RELEASE_
compiling
+mode, this macro is blank.
Example :
+
#include "utilities.h" @@ -169,17 +220,22 @@ int main(int argc , char **argv) return 0; }-
displays : +
+displays :
+
- Trace main.cxx [4] : Normal end of a.out+
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 :
+the variable. In _RELEASE_
compiling mode, this macro is blank.
Example :
+
#include "utilities.h" @@ -190,19 +246,25 @@ int main(int argc , char **argv) return 0; }-
displays : +
+displays :
+
- Trace main.cxx [5] : i=999+
In _DEBUG_
compiling mode only, The C++ macro ASSERT
checks the
-expression passed in argument to be not NULL. If it is NULL the process
-is stopped and the condition is written on the standard output. In
-_RELEASE_
compiling mode, this macro is blank. N.B. : if ASSERT
is
-already defined, this macro is ignored.
-
Example :
+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" @@ -216,6 +278,7 @@ int k; ASSERT(k<10); cout << table[k];+
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 exception is displayed, or sent to a log file.
+
The class SALOME_Exception
inherits its behavior from the STL
-class exception.
+class exception.
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:
+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: +
+The exception is raised like this:
+
throw SALOME_Exception("my pertinent message");-
or like this: +
+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: +which gives file name and line number.
+ +The exception is handled like this:
+
try @@ -63,56 +75,71 @@ catch (const SALOME_Exception &ex) cerr << ex.what() <<endl; }+
The what()
method overrides the one defined in the STL exception
-class.
-
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.
+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: +a single catch.
+ +The exception types defined in idl are:
+
CORBA communication problem, -
Bad User parameters, -
application level problem (often irrecoverable). +
CORBA communication problem,
+Bad User parameters,
+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. +used within SALOME, such as OmniORB exceptions, must be handled separately.
+The CORBA Server header for SALOME_Exception
and a macro to throw
-the exception are provided with the header SALOME/src/Utils/Utils_CorbaException.hxx
:
+the exception are provided with the header SALOME/src/Utils/Utils_CorbaException.hxx
:
#include "Utils_CorbaException.hxx"+
The exception is raised with a macro which appends file name -and line number. +and line number.
+
if (myStudyName.size() == 0) THROW_SALOME_CORBA_EXCEPTION("No Study Name given", \ SALOME::BAD_PARAM);+
The CORBA Client header for SALOME_Exception
and a Qt function
-header that displays a message box are provided in SALOME/src/SALOMEGUI/SALOMEGUI_QtCatchCorbaException.hxx
:
+header that displays a message box are provided in SALOME/src/SALOMEGUI/SALOMEGUI_QtCatchCorbaException.hxx
:
#include "SALOMEGUI_QtCatchCorbaException.hxx"-
A typical exchange with a CORBA Servant will be: +
+A typical exchange with a CORBA Servant will be:
+
try @@ -123,12 +150,15 @@ catch (const SALOME::SALOME_Exception & S_ex) { QtCatchCorbaException(S_ex); } ++
Nothing specific has been provided to the developer yet. See
the idl or the Qt function SALOMEGUI_QtCatchCorbaException.hxx
to
-see how to get the information given by the exception object.
+see how to get the information given by the exception object.
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. +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.
+at deletion.
To create a single instance a POINT object : +
To create a single instance a POINT object :
+
# include "Utils_SINGLETON.hxx" @@ -36,11 +39,13 @@ at deletion. 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 ?).
+functions (threads ?).
POINT *p1=SINGLETON_<POINT>::Instance() ; @@ -48,9 +53,11 @@ POINT *p1=SINGLETON_<POINT>::Instance() ; POINT *p2=SINGLETON_<POINT>::Instance() ; assert(p1==p2)+
Here are the principles features of the singleton design : +
Here are the principles features of the singleton design :
+
TYPE
by using the class method
@@ -62,13 +69,16 @@ the default constructor of class TYPE
;atexit
) ;
Nettoyage()
C function which executes the destruction objects
+by the Nettoyage()
C function which executes the destruction objects
end then deletes the destructions objects themselves ;Nettoyage()
C function using atexit() C function is embedded
-in a static single object ATEXIT_()
.Nettoyage()
C function using atexit() C function is embedded
+in a static single object ATEXIT_()
.
+-
+
+ + +
)XziK@Qx(eHB(+8=l{b y~H8)5;iJszfl?f+Orrv
z4X~y6mr!&Bp)M{5A3?C53o%h<%03|5qnTqG>MO2;y_mtPhdMPph&pLAEo71^?&PuK
zF9tZ~GZmbn-YyoUEnz=aj9(nJ;GqAo!7n=fF1J4nYByF2mhh>z^v2+oTj}u5q-Y(JdZ<-${n
zz{%ZaKtFO