1 ======================================================================
2 SALOME Kernel resources for developer
3 ======================================================================
5 *html version of this document is produced with docutils*::
7 rst2html doc.txt > doc.html
9 *This document corresponds to SALOME2 3.2.0*
15 :Version: 0.3 - february 17, 2006
17 +-------------------------------------------+
18 | **WORK in PROGRESS, INCOMPLETE DOCUMENT** |
19 +-------------------------------------------+
21 -------------------------------------------------------------------------------
25 This document describes the development environment for
26 C++ and Python. Makefiles generation and usage are
27 introduced in another document: "using the SALOME
28 configuration and building system environment".
29 Development environment is intended here as: trace and
30 debug macros usage; SALOME exceptions usage, in C++ and
31 Python; user CORBA exceptions usage, in C++ and Python,
32 with and without Graphical User Interface; some general
33 purpose services such as singleton, used for CORBA
34 connection and disconnection.
39 -------------------------------------------------------------------------------
41 Trace and debug Utilities
42 =========================
44 During the development process, an execution log is
45 useful to identify problems. This log contains
46 messages, variables values, source files names and line
47 numbers. It is recommended to verify assertions on
48 variables values and if necessary, to stop the
49 execution at debug time, in order to validate all parts
52 Two modes: debug and release
53 ----------------------------
55 The goal of debug mode is to check as many features as
56 possible during the early stages of the development
57 process. The purpose of the utilities provided in
58 SALOME is to help the developer to add detailed traces
59 and check variables values, without writing a lot of code.
61 When the code is assumed to be valid, the release mode
62 optimizes execution, in terms of speed, memory, and
63 display only user level messages.
65 But, some informations must always be displayed in both
66 modes: especially messages concerning environment or
67 internal errors, with version identification. When an
68 end user is confronted to such a message, he may refer
69 to a configuration documentation or send the message to
70 the people in charge of SALOME installation, or to the
71 development team, following the kind of error.
73 C++ Macros for trace and debug
74 ------------------------------
76 SALOME provides C++ macros for trace and debug. These
79 KERNEL_SRC/src/SALOMELocalTrace/utilities.h
81 This file must be included in C++ source. Some
82 macros are activated only in debug mode, others are
83 always activated. To activate the debug mode, ``_DEBUG_``
84 must be defined, which is the case when SALOME
85 Makefiles are generated from configure, without
86 options. When ``_DEBUG_`` is undefined (release mode:
87 ``configure --disable-debug --enable-production``), the
88 debug mode macros are defined empty (they do nothing).
89 So, when switching from debug to release, it is
90 possible (and recommended) to let the macro calls
91 unchanged in the source.
93 All the macros generate trace messages, stored in a
94 circular buffer pool. A separate thread reads the
95 messages in the buffer pool, and, depending on options
96 given at SALOME start, writes the messages on the
97 standard output, a file, or send them via CORBA, in
98 case of a multi machine configuration.
100 Three informations are systematically added in front of
101 the information displayed:
103 * the thread number from which the message come from;
105 * the name of the source file in which the macros is set;
107 * the line number of the source file at which the macro
110 Macros defined in debug and release modes
111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
113 **INFOS_COMPILATION**
114 The C++ macro INFOS_COMPILATION writes on the trace
115 buffer pool informations about the compiling process:
117 * the name of the compiler : g++, KCC, CC, pgCC;
119 * the date and the time of the compiling processing process.
121 This macro INFOS_COMPILATION does not have any
122 argument. Moreover, it is defined in both compiling
123 mode : _DEBUG_ and _RELEASE_.
127 #include "utilities.h"
128 int main(int argc , char **argv)
136 In both compiling mode _DEBUG_ and _RELEASE_, The C++
137 macro INFOS writes on the trace buffer pool the string
138 which has been passed in argument by the user.
142 #include "utilities.h"
143 int main(int argc , char **argv)
146 INFOS("NORMAL END OF THE PROCESS");
152 main.cxx [5] : NORMAL END OF THE PROCESS
155 **INTERRUPTION(str)**
156 In both compiling mode _DEBUG_ and _RELEASE_, The C++
157 macro INTERRUPTION writes on the trace buffer pool the
158 string, with a special ABORT type. When the thread in
159 charge of collecting messages finds this message, it
160 terminates the application, after message treatment.
162 **IMMEDIATE_ABORT(str)**
163 In both compiling mode _DEBUG_ and _RELEASE_, The C++
164 macro IMMEDIATE_ABORT writes the message str immediately on
165 standard error and exits the application. Remaining
166 messages not treated by the message collector thread
169 Macros defined only in debug mode
170 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
173 In _DEBUG_ compiling mode only, the C++ macro MESSAGE
174 writes on the trace buffer pool the string which has
175 been passed in argument by the user. In _RELEASE_
176 compiling mode, this macro is blank.
180 #include "utilities.h"
185 int main(int argc , char **argv)
188 const char *str = "Salome";
192 MESSAGE(c_str(st+" and CASTEM"));
198 - Trace main.cxx [8] : Salome
199 - Trace main.cxx [12] : Aster and CASTEM
201 **BEGIN_OF(func_name)**
202 In _DEBUG_ compiling mode, The C++ macro BEGIN_OF
203 appends the string "Begin of " to the one passed in
204 argument by the user and displays the result on the
205 trace buffer pool. In _RELEASE_ compiling mode, this
210 #include "utilities.h"
211 int main(int argc , char **argv)
219 - Trace main.cxx [3] : Begin of a.out
222 **END_OF(func_name)**
223 In _DEBUG_ compiling mode, The C++ macro END_OF appends
224 the string "Normal end of " to the one passed in
225 argument by the user and displays the result on the
226 trace buffer pool. In _RELEASE_ compiling mode, this
231 #include "utilities.h"
232 int main(int argc , char **argv)
240 - Trace main.cxx [4] : Normal end of a.out
243 In _DEBUG_ compiling mode, The C++ macro SCRUTE
244 displays its argument which is an application variable
245 followed by the value of the variable. In _RELEASE_
246 compiling mode, this macro is blank.
250 #include "utilities.h"
251 int main(int argc , char **argv)
254 if( i > 0 ) SCRUTE(i) ; i=i+1;
260 - Trace main.cxx [5] : i=999
262 **ASSERT(condition)**
263 In _DEBUG_ compiling mode only, The C++ macro ASSERT
264 checks the expression passed in argument to be not
265 NULL. If it is NULL the condition is written with the
266 macro INTERRUPTION (see above). The process exits after
267 trace of this last message. In _RELEASE_ compiling
268 mode, this macro is blank. N.B. : if ASSERT is already
269 defined, this macro is ignored.
273 #include "utilities.h"
275 const char *ptrS = fonc();
277 cout << strlen(ptrS);
287 C++ exceptions: class SALOME_Exception
288 --------------------------------------
293 The class SALOME_Exception provides a generic method to
294 send a message, with optional source file name and line
295 number. This class is intended to serve as a base class
296 for all kinds of exceptions SALOME code. All the
297 exceptions derived from SALOME_Exception could be
298 handled in a single catch, in which the message
299 associated to the exception is displayed, or sent to a
302 The class SALOME_Exception inherits its behavior from
303 the STL class exception.
308 The header SALOME/src/utils/utils_SALOME_Exception.hxx
309 must be included in the C++ source, when raised or trapped::
311 #include "utils_SALOME_Exception.hxx"
313 The SALOME_Exception constructor is::
315 SALOME_Exception( const char *text,
316 const char *fileName=0,
317 const unsigned int lineNumber=0 );
319 The exception is raised like this::
321 throw SALOME_Exception("my pertinent message");
325 throw SALOME_Exception(LOCALIZED("my pertinent message"));
327 where LOCALIZED is a macro provided with
328 ``utils_SALOME_Exception.hxx`` which gives file name and
331 The exception is handled like this::
337 catch (const SALOME_Exception &ex)
339 cerr << ex.what() <<endl;
342 The what() method overrides the one defined in the STL
351 The idl SALOME_Exception provides a generic CORBA
352 exception for SALOME, with an attribute that gives an
353 exception type,a message, plus optional source file
354 name and line number.
356 This idl is intended to serve for all user CORBA
357 exceptions raised in SALOME code, as IDL specification
358 does not support exception inheritance. So, all the
359 user CORBA exceptions from SALOME could be handled in a
362 The exception types defined in idl are:
364 - COMM CORBA communication problem,
366 - BAD_PARAM Bad User parameters,
368 - INTERNAL_ERROR application level problem (often irrecoverable).
370 CORBA system and user exceptions already defined in the
371 packages used within SALOME, such as OmniORB
372 exceptions, must be handled separately.
380 The CORBA Server header for SALOME_Exception and a
381 macro to throw the exception are provided with the
382 header ``KERNEL_SRC/src/Utils/Utils_CorbaException.hxx``::
384 #include "Utils_CorbaException.hxx"
386 The exception is raised with a macro which appends file
387 name and line number::
389 if (myStudyName.size() == 0)
390 THROW_SALOME_CORBA_EXCEPTION("No Study Name given",
393 CORBA Client, GUI Qt C++
394 ^^^^^^^^^^^^^^^^^^^^^^^^
396 **NO MORE AVAILABLE in SALOME 3.x**
398 The CORBA Client header for SALOME_Exception and a Qt
399 function header that displays a message box are
402 ``KERNEL_SRC/src/SALOMEGUI/SALOMEGUI_QtCatchCorbaException.hxx``
406 #include "SALOMEGUI_QtCatchCorbaException.hxx"
408 A typical exchange with a CORBA Servant will be::
412 ... // one ore more CORBA calls
415 catch (const SALOME::SALOME_Exception & S_ex)
417 QtCatchCorbaException(S_ex);
422 CORBA Client, C++, without GUI
423 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
425 Nothing specific has been provided to the developer
426 yet. See the idl or the Qt function
427 SALOMEGUI_QtCatchCorbaException.hxx to see how to get
428 the information given by the exception object.
439 A singleton is an application data which is created and
440 deleted only once at the end of the application
441 process. The C++ compiler allows the user to create a
442 static singleton data before the first executable
443 statement. They are deleted after the last statement execution.
445 The ``SINGLETON_`` template class deals with dynamic
446 singleton. It is useful for functor objects. For
447 example, an object that connects the application to a
448 system at creation and disconnects the application at deletion.
453 To create a single instance of a POINT object::
455 # include "Utils_SINGLETON.hxx"
457 POINT *ptrPoint=SINGLETON_<POINT>::Instance() ;
458 assert(ptrPoint!=NULL) ;
460 No need to delete ptrPoint. Deletion is achieved
461 automatically at exit. If the user tries to create more
462 than one singleton by using the class method
463 SINGLETON_<TYPE>::Instance(), the pointer is returned
464 with the same value even if this is done in different
465 functions (threads ?)::
467 POINT *p1=SINGLETON_<POINT>::Instance() ;
469 POINT *p2=SINGLETON_<POINT>::Instance() ;
476 Here are the principles features of the singleton
479 * the user creates an object of class TYPE by using the
480 class method ``SINGLETON_<TYPE>::Instance()`` which
481 returns a pointer to the single object ;
483 * to create an object, ``SINGLETON_<TYPE>::Instance()``
484 uses the default constructor of class TYPE ;
486 * at the same time, this class method creates a
487 destructor object which is added to the generic list
488 of destructor objects to be executed at the end of
489 the application (atexit) ;
491 * at the end of the application process all the
492 deletions are performed by the ``Nettoyage()`` C function
493 which executes the destruction objects end then
494 deletes the destructions objects themselves ;
496 * the ``Nettoyage()`` C function using ``atexit()`` C function
497 is embedded in a static single object ``ATEXIT_()``.
500 -------------------------------------------------------------------------------
502 +----------------------------------+------------------------------------------+
503 | `General KERNEL documentation`_ | `End User KERNEL Doxygen documentation`_ |
504 +----------------------------------+------------------------------------------+
506 .. _`General KERNEL documentation`: ./index.html
507 .. _`End User KERNEL Doxygen documentation`: ./tui/KERNEL/index.html