1 ======================================================================
2 SALOME Kernel resources for developer
3 ======================================================================
5 *html version of this document is produced with docutils*::
7 rst2html doc.txt > doc.html
13 :Version: 0.3 - february 17, 2006
15 +-------------------------------------------+
16 | **WORK in PROGRESS, INCOMPLETE DOCUMENT** |
17 +-------------------------------------------+
21 This document describes the development environment for
22 C++ and Python. Makefiles generation and usage are
23 introduced in another document: "using the SALOME
24 configuration and building system environment".
25 Development environment is intended here as: trace and
26 debug macros usage; SALOME exceptions usage, in C++ and
27 Python; user CORBA exceptions usage, in C++ and Python,
28 with and without Graphical User Interface; some general
29 purpose services such as singleton, used for CORBA
30 connection and disconnection.
35 Trace and debug Utilities
36 =========================
38 During the development process, an execution log is
39 useful to identify problems. This log contains
40 messages, variables values, source files names and line
41 numbers. It is recommended to verify assertions on
42 variables values and if necessary, to stop the
43 execution at debug time, in order to validate all parts
46 Two modes: debug and release
47 ----------------------------
49 The goal of debug mode is to check as many features as
50 possible during the early stages of the development
51 process. The purpose of the utilities provided in
52 SALOME is to help the developer to add detailed traces
53 and check variables values, without writing a lot of code.
55 When the code is assumed to be valid, the release mode
56 optimizes execution, in terms of speed, memory, and
57 display only user level messages.
59 But, some informations must always be displayed in both
60 modes: especially messages concerning environment or
61 internal errors, with version identification. When an
62 end user is confronted to such a message, he may refer
63 to a configuration documentation or send the message to
64 the people in charge of SALOME installation, or to the
65 development team, following the kind of error.
67 C++ Macros for trace and debug
68 ------------------------------
70 SALOME provides C++ macros for trace and debug. These
73 KERNEL_SRC/src/SALOMELocalTrace/utilities.h
75 This file must be included in C++ source. Some
76 macros are activated only in debug mode, others are
77 always activated. To activate the debug mode, ``_DEBUG_``
78 must be defined, which is the case when SALOME
79 Makefiles are generated from configure, without
80 options. When ``_DEBUG_`` is undefined (release mode:
81 ``configure --disable-debug --enable-production``), the
82 debug mode macros are defined empty (they do nothing).
83 So, when switching from debug to release, it is
84 possible (and recommended) to let the macro calls
85 unchanged in the source.
87 All the macros generate trace messages, stored in a
88 circular buffer pool. A separate thread reads the
89 messages in the buffer pool, and, depending on options
90 given at SALOME start, writes the messages on the
91 standard output, a file, or send them via CORBA, in
92 case of a multi machine configuration.
94 Three informations are systematically added in front of
95 the information displayed:
97 * the thread number from which the message come from;
99 * the name of the source file in which the macros is set;
101 * the line number of the source file at which the macro
104 Macros defined in debug and release modes
105 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
107 **INFOS_COMPILATION**
108 The C++ macro INFOS_COMPILATION writes on the trace
109 buffer pool informations about the compiling process:
111 * the name of the compiler : g++, KCC, CC, pgCC;
113 * the date and the time of the compiling processing process.
115 This macro INFOS_COMPILATION does not have any
116 argument. Moreover, it is defined in both compiling
117 mode : _DEBUG_ and _RELEASE_.
121 #include "utilities.h"
122 int main(int argc , char **argv)
130 In both compiling mode _DEBUG_ and _RELEASE_, The C++
131 macro INFOS writes on the trace buffer pool the string
132 which has been passed in argument by the user.
136 #include "utilities.h"
137 int main(int argc , char **argv)
140 INFOS("NORMAL END OF THE PROCESS");
146 main.cxx [5] : NORMAL END OF THE PROCESS
149 **INTERRUPTION(str)**
150 In both compiling mode _DEBUG_ and _RELEASE_, The C++
151 macro INTERRUPTION writes on the trace buffer pool the
152 string, with a special ABORT type. When the thread in
153 charge of collecting messages finds this message, it
154 terminates the application, after message treatment.
156 **IMMEDIATE_ABORT(str)**
157 In both compiling mode _DEBUG_ and _RELEASE_, The C++
158 macro IMMEDIATE_ABORT writes the message str immediately on
159 standard error and exits the application. Remaining
160 messages not treated by the message collector thread
163 Macros defined only in debug mode
164 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
167 In _DEBUG_ compiling mode only, the C++ macro MESSAGE
168 writes on the trace buffer pool the string which has
169 been passed in argument by the user. In _RELEASE_
170 compiling mode, this macro is blank.
174 #include "utilities.h"
179 int main(int argc , char **argv)
182 const char *str = "Salome";
186 MESSAGE(c_str(st+" and CASTEM"));
192 - Trace main.cxx [8] : Salome
193 - Trace main.cxx [12] : Aster and CASTEM
195 **BEGIN_OF(func_name)**
196 In _DEBUG_ compiling mode, The C++ macro BEGIN_OF
197 appends the string "Begin of " to the one passed in
198 argument by the user and displays the result on the
199 trace buffer pool. In _RELEASE_ compiling mode, this
204 #include "utilities.h"
205 int main(int argc , char **argv)
213 - Trace main.cxx [3] : Begin of a.out
216 **END_OF(func_name)**
217 In _DEBUG_ compiling mode, The C++ macro END_OF appends
218 the string "Normal end of " to the one passed in
219 argument by the user and displays the result on the
220 trace buffer pool. In _RELEASE_ compiling mode, this
225 #include "utilities.h"
226 int main(int argc , char **argv)
234 - Trace main.cxx [4] : Normal end of a.out
237 In _DEBUG_ compiling mode, The C++ macro SCRUTE
238 displays its argument which is an application variable
239 followed by the value of the variable. In _RELEASE_
240 compiling mode, this macro is blank.
244 #include "utilities.h"
245 int main(int argc , char **argv)
248 if( i > 0 ) SCRUTE(i) ; i=i+1;
254 - Trace main.cxx [5] : i=999
256 **ASSERT(condition)**
257 In _DEBUG_ compiling mode only, The C++ macro ASSERT
258 checks the expression passed in argument to be not
259 NULL. If it is NULL the condition is written with the
260 macro INTERRUPTION (see above). The process exits after
261 trace of this last message. In _RELEASE_ compiling
262 mode, this macro is blank. N.B. : if ASSERT is already
263 defined, this macro is ignored.
267 #include "utilities.h"
269 const char *ptrS = fonc();
271 cout << strlen(ptrS);
281 C++ exceptions: class SALOME_Exception
282 --------------------------------------
287 The class SALOME_Exception provides a generic method to
288 send a message, with optional source file name and line
289 number. This class is intended to serve as a base class
290 for all kinds of exceptions SALOME code. All the
291 exceptions derived from SALOME_Exception could be
292 handled in a single catch, in which the message
293 associated to the exception is displayed, or sent to a
296 The class SALOME_Exception inherits its behavior from
297 the STL class exception.
302 The header SALOME/src/utils/utils_SALOME_Exception.hxx
303 must be included in the C++ source, when raised or trapped::
305 #include "utils_SALOME_Exception.hxx"
307 The SALOME_Exception constructor is::
309 SALOME_Exception( const char *text,
310 const char *fileName=0,
311 const unsigned int lineNumber=0 );
313 The exception is raised like this::
315 throw SALOME_Exception("my pertinent message");
319 throw SALOME_Exception(LOCALIZED("my pertinent message"));
321 where LOCALIZED is a macro provided with
322 ``utils_SALOME_Exception.hxx`` which gives file name and
325 The exception is handled like this::
331 catch (const SALOME_Exception &ex)
333 cerr << ex.what() <<endl;
336 The what() method overrides the one defined in the STL
345 The idl SALOME_Exception provides a generic CORBA
346 exception for SALOME, with an attribute that gives an
347 exception type,a message, plus optional source file
348 name and line number.
350 This idl is intended to serve for all user CORBA
351 exceptions raised in SALOME code, as IDL specification
352 does not support exception inheritance. So, all the
353 user CORBA exceptions from SALOME could be handled in a
356 The exception types defined in idl are:
358 - COMM CORBA communication problem,
360 - BAD_PARAM Bad User parameters,
362 - INTERNAL_ERROR application level problem (often irrecoverable).
364 CORBA system and user exceptions already defined in the
365 packages used within SALOME, such as OmniORB
366 exceptions, must be handled separately.
374 The CORBA Server header for SALOME_Exception and a
375 macro to throw the exception are provided with the
376 header ``KERNEL_SRC/src/Utils/Utils_CorbaException.hxx``::
378 #include "Utils_CorbaException.hxx"
380 The exception is raised with a macro which appends file
381 name and line number::
383 if (myStudyName.size() == 0)
384 THROW_SALOME_CORBA_EXCEPTION("No Study Name given",
387 CORBA Client, GUI Qt C++
388 ^^^^^^^^^^^^^^^^^^^^^^^^
390 **NO MORE AVAILABLE in SALOME 3.x**
392 The CORBA Client header for SALOME_Exception and a Qt
393 function header that displays a message box are
396 ``KERNEL_SRC/src/SALOMEGUI/SALOMEGUI_QtCatchCorbaException.hxx``
400 #include "SALOMEGUI_QtCatchCorbaException.hxx"
402 A typical exchange with a CORBA Servant will be::
406 ... // one ore more CORBA calls
409 catch (const SALOME::SALOME_Exception & S_ex)
411 QtCatchCorbaException(S_ex);
416 CORBA Client, C++, without GUI
417 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
419 Nothing specific has been provided to the developer
420 yet. See the idl or the Qt function
421 SALOMEGUI_QtCatchCorbaException.hxx to see how to get
422 the information given by the exception object.
433 A singleton is an application data which is created and
434 deleted only once at the end of the application
435 process. The C++ compiler allows the user to create a
436 static singleton data before the first executable
437 statement. They are deleted after the last statement execution.
439 The ``SINGLETON_`` template class deals with dynamic
440 singleton. It is useful for functor objects. For
441 example, an object that connects the application to a
442 system at creation and disconnects the application at deletion.
447 To create a single instance of a POINT object::
449 # include "Utils_SINGLETON.hxx"
451 POINT *ptrPoint=SINGLETON_<POINT>::Instance() ;
452 assert(ptrPoint!=NULL) ;
454 No need to delete ptrPoint. Deletion is achieved
455 automatically at exit. If the user tries to create more
456 than one singleton by using the class method
457 SINGLETON_<TYPE>::Instance(), the pointer is returned
458 with the same value even if this is done in different
459 functions (threads ?)::
461 POINT *p1=SINGLETON_<POINT>::Instance() ;
463 POINT *p2=SINGLETON_<POINT>::Instance() ;
470 Here are the principles features of the singleton
473 * the user creates an object of class TYPE by using the
474 class method ``SINGLETON_<TYPE>::Instance()`` which
475 returns a pointer to the single object ;
477 * to create an object, ``SINGLETON_<TYPE>::Instance()``
478 uses the default constructor of class TYPE ;
480 * at the same time, this class method creates a
481 destructor object which is added to the generic list
482 of destructor objects to be executed at the end of
483 the application (atexit) ;
485 * at the end of the application process all the
486 deletions are performed by the ``Nettoyage()`` C function
487 which executes the destruction objects end then
488 deletes the destructions objects themselves ;
490 * the ``Nettoyage()`` C function using ``atexit()`` C function
491 is embedded in a static single object ``ATEXIT_()``.