3 \page kernel_resources Salome Kernel resources for developer
7 This document describes the development environment for
8 C++ and Python. Makefiles generation and usage are
9 introduced in another document: "using the %SALOME
10 configuration and building system environment".
11 Development environment is intended here as: trace and
12 debug macros usage; %SALOME exceptions usage, in C++ and
13 Python; user CORBA exceptions usage, in C++ and Python,
14 with and without Graphical User Interface; some general
15 purpose services such as singleton, used for CORBA
16 connection and disconnection.
18 \section S2_kernel_res Trace and debug Utilities
20 During the development process, an execution log is
21 useful to identify problems. This log contains
22 messages, variables values, source files names and line
23 numbers. It is recommended to verify assertions on
24 variables values and if necessary, to stop the
25 execution at debug time, in order to validate all parts
28 \subsection subsection21 Two modes: debug and release
30 The goal of debug mode is to check as many features as
31 possible during the early stages of the development
32 process. The purpose of the utilities provided in
33 %SALOME is to help the developer to add detailed traces
34 and check variables values, without writing a lot of code.
36 When the code is assumed to be valid, the release mode
37 optimizes execution, in terms of speed, memory, and
38 display only user level messages.
40 But, some information must always be displayed in both
41 modes: especially messages concerning environment or
42 internal errors, with version identification. When an
43 end user is confronted to such a message, he may refer
44 to a configuration documentation or send the message to
45 the people in charge of %SALOME installation, or to the
46 development team, following the kind of error.
48 \subsection subsection22 C++ Macros for trace and debug
50 %SALOME provides C++ macros for trace and debug. These
54 KERNEL_SRC/src/SALOMELocalTrace/utilities.h
57 This file must be included in C++ source. Some
58 macros are activated only in debug mode, others are
59 always activated. To activate the debug mode, _DEBUG_
60 must be defined, which is the case when %SALOME
61 Makefiles are generated from CMake build system, without
62 options. When _DEBUG_ is undefined (release mode:
63 cmake -DCMAKE_BUILD_TYPE=Release ../KERNEL_SRC), the
64 debug mode macros are defined empty (they do nothing).
65 So, when switching from debug to release, it is
66 possible (and recommended) to let the macro calls
67 unchanged in the source.
69 All the macros generate trace messages, stored in a
70 circular buffer pool. %A separate %thread reads the
71 messages in the buffer pool, and, depending on options
72 given at %SALOME start, writes the messages on the
73 standard output, a file, or send them via CORBA, in
74 case of a multi machine configuration.
76 Three information are systematically added in front of
77 the information displayed:
78 - the %thread number from which the message come from;
79 - the name of the source file in which the macros is set;
80 - the line number of the source file at which the macro
83 \subsection subsection23 Macros defined in debug and release modes
85 - <b>INFOS_COMPILATION</b>\n
86 The C++ macro INFOS_COMPILATION writes on the trace
87 buffer pool information about the compiling process:
88 - the name of the compiler : g++, KCC, CC, pgCC;
89 - the date and the time of the compiling processing process.
91 This macro INFOS_COMPILATION does not have any
92 argument. Moreover, it is defined in both compiling
93 mode : _DEBUG_ and _RELEASE_.\n
96 #include "utilities.h"
97 int main(int argc , char **argv)
105 In both compiling mode _DEBUG_ and _RELEASE_, The C++
106 macro INFOS writes on the trace buffer pool %the string
107 which has been passed in argument by the user.\n
110 #include "utilities.h"
111 int main(int argc , char **argv)
114 INFOS("NORMAL END OF THE PROCESS");
120 main.cxx [5] : NORMAL END OF THE PROCESS
123 - <b>INTERRUPTION(str)</b>\n
124 In both compiling mode _DEBUG_ and _RELEASE_, The C++
125 macro INTERRUPTION writes on the trace buffer pool the
126 %string, with a special ABORT type. When the %thread in
127 charge of collecting messages finds this message, it
128 terminates the application, after message treatment.
130 - <b>IMMEDIATE_ABORT(str)</b>\n
131 In both compiling mode _DEBUG_ and _RELEASE_, The C++
132 macro IMMEDIATE_ABORT writes the message str immediately on
133 standard error and exits the application. Remaining
134 messages not treated by the message collector %thread
137 \subsection subsection24 Macros defined only in debug mode
139 - <b>MESSAGE(str)</b>\n
140 In _DEBUG_ compiling mode only, the C++ macro MESSAGE
141 writes on the trace buffer pool the %string which has
142 been passed in argument by the user. In _RELEASE_
143 compiling mode, this macro is blank.\n
146 #include "utilities.h"
151 int main(int argc , char **argv)
154 const char *str = "Salome";
158 MESSAGE(c_str(st+" and CASTEM"));
165 - Trace main.cxx [8] : Salome
166 - Trace main.cxx [12] : Aster and CASTEM
169 - <b>BEGIN_OF(func_name)</b>\n
170 In _DEBUG_ compiling mode, The C++ macro BEGIN_OF
171 appends the %string "Begin of " to the one passed in
172 argument by the user and displays the result on the
173 trace buffer pool. In _RELEASE_ compiling mode, this
177 #include "utilities.h"
178 int main(int argc , char **argv)
186 - Trace main.cxx [3] : Begin of a.out
189 - <b>END_OF(func_name)</b>\n
190 In _DEBUG_ compiling mode, The C++ macro END_OF appends
191 the %string "Normal end of " to the one passed in
192 argument by the user and displays the result on the
193 trace buffer pool. In _RELEASE_ compiling mode, this
197 #include "utilities.h"
198 int main(int argc , char **argv)
206 - Trace main.cxx [4] : Normal end of a.out
209 - <b>SCRUTE(var)</b>\n
210 In _DEBUG_ compiling mode, The C++ macro SCRUTE
211 displays its argument which is an application variable
212 followed by the value of the variable. In _RELEASE_
213 compiling mode, this macro is blank.\n
216 #include "utilities.h"
217 int main(int argc , char **argv)
220 if( i > 0 ) SCRUTE(i) ; i=i+1;
226 - Trace main.cxx [5] : i=999
229 - <b>ASSERT(condition)</b>\n
230 In _DEBUG_ compiling mode only, The C++ macro ASSERT
231 checks the expression passed in argument to be not
232 NULL. If it is NULL the condition is written with the
233 macro INTERRUPTION (see above). The process exits after
234 trace of this last message. In _RELEASE_ compiling
235 mode, this macro is blank. N.B. : if ASSERT is already
236 defined, this macro is ignored.\n
239 #include "utilities.h"
241 const char *ptrS = fonc();
243 cout << strlen(ptrS);
251 \section S3_kernel_res Exceptions
253 \subsection subsection31 C++ exceptions: class SALOME_Exception
255 \subsubsection subsubsection311 Definition
257 The class SALOME_Exception provides a generic method to
258 send a message, with optional source file name and line
259 number. This class is intended to serve as a base class
260 for all kinds of exceptions %SALOME code. All the
261 exceptions derived from SALOME_Exception could be
262 handled in a single catch, in which the message
263 associated to the exception is displayed, or sent to a
266 The class SALOME_Exception inherits its behavior from
267 the STL class exception.
269 \subsubsection subsubsection312 Usage
271 The header %SALOME/src/utils/utils_SALOME_Exception.hxx
272 must be included in the C++ source, when raised or trapped:
275 #include "utils_SALOME_Exception.hxx"
278 The SALOME_Exception constructor is:
281 SALOME_Exception( const char *text,
282 const char *fileName=0,
283 const unsigned int lineNumber=0 );
286 The exception is raised like this:
289 throw SALOME_Exception("my pertinent message");
295 throw SALOME_Exception(LOCALIZED("my pertinent message"));
298 where LOCALIZED is a macro provided with
299 utils_SALOME_Exception.hxx which gives file name and
302 The exception is handled like this:
309 catch (const SALOME_Exception &ex)
311 cerr << ex.what() <<endl;
315 The what() method overrides the one defined in the STL
318 \subsection subsection32 CORBA exceptions
320 \subsubsection subsubsection321 Definition
322 The idl SALOME_Exception provides a generic CORBA
323 exception for %SALOME, with an attribute that gives an
324 exception type,a message, plus optional source file
325 name and line number.
327 This idl is intended to serve for all user CORBA
328 exceptions raised in %SALOME code, as IDL specification
329 does not support exception inheritance. So, all the
330 user CORBA exceptions from %SALOME could be handled in a
333 The exception types defined in idl are:
335 - COMM CORBA communication problem,
337 - BAD_PARAM Bad User parameters,
339 - INTERNAL_ERROR application level problem (often irrecoverable).
341 CORBA system and user exceptions already defined in the
342 packages used within %SALOME, such as OmniORB
343 exceptions, must be handled separately.
345 \subsubsection subsubsection322 Usage
346 <b>CORBA servant, C++</b>
348 The CORBA Server header for SALOME_Exception and a
349 macro to throw the exception are provided with the
350 header KERNEL_SRC/src/Utils/Utils_CorbaException.hxx:
353 #include "Utils_CorbaException.hxx"
356 The exception is raised with a macro which appends file
357 name and line number:
360 if (myStudyName.size() == 0)
361 THROW_SALOME_CORBA_EXCEPTION("No Study Name given",
365 <b>CORBA Client, GUI Qt C++ (NO MORE AVAILABLE in %SALOME 3.x and later)</b>
367 The CORBA Client header for SALOME_Exception and a Qt
368 function header that displays a message box are
371 KERNEL_SRC/src/SALOMEGUI/SALOMEGUI_QtCatchCorbaException.hxx
374 #include "SALOMEGUI_QtCatchCorbaException.hxx"
377 %A typical exchange with a CORBA Servant will be:
382 ... // one ore more CORBA calls
385 catch (const SALOME::SALOME_Exception & S_ex)
387 QtCatchCorbaException(S_ex);
391 <b>CORBA Client, C++, without GUI</b>
393 Nothing specific has been provided to the developer
394 yet. See the idl or the Qt function
395 SALOMEGUI_QtCatchCorbaException.hxx to see how to get
396 the information given by the exception %object.
398 \section S4_kernel_res Miscellaneous tools
400 \subsection subsection41 Singleton
401 \subsubsection subsubsection411 Definition
403 %A singleton is an application data which is created and
404 deleted only once at the end of the application
405 process. The C++ compiler allows the user to create a
406 static singleton data before the first executable
407 statement. They are deleted after the last statement execution.
409 The SINGLETON_ template class deals with dynamic
410 singleton. It is useful for functor objects. For
411 example, an %object that connects the application to a
412 system at creation and disconnects the application at deletion.
414 \subsubsection subsubsection412 Usage
416 To create a single instance of a POINT %object:
419 # include "Utils_SINGLETON.hxx"
421 POINT *ptrPoint=SINGLETON_<POINT>::Instance() ;
422 assert(ptrPoint!=NULL) ;
425 No need to delete ptrPoint. Deletion is achieved
426 automatically at exit. If the user tries to create more
427 than one singleton by using the class method
428 SINGLETON_<TYPE>::Instance(), the pointer is returned
429 with the same value even if this is done in different
430 functions (threads ?):
433 POINT *p1=SINGLETON_<POINT>::Instance() ;
435 POINT *p2=SINGLETON_<POINT>::Instance() ;
440 \subsubsection subsubsection413 Design description
442 Here are the principles features of the singleton
444 - the user creates an %object of class TYPE by using the
445 class method SINGLETON_<TYPE>::Instance() which
446 returns a pointer to the single %object ;
447 - to create an %object, SINGLETON_<TYPE>::Instance()
448 uses the default constructor of class TYPE ;
449 - at the same time, this class method creates a
450 destructor %object which is added to the generic list
451 of destructor objects to be executed at the end of
452 the application (atexit) ;
453 - at the end of the application process all the
454 deletions are performed by the Nettoyage() C function
455 which executes the destruction objects end then
456 deletes the destructions objects themselves ;
457 - the Nettoyage() C function using atexit() C function
458 is embedded in a static single %object ATEXIT_().