1 #LyX 1.1 created this file. For more info see http://www.lyx.org/
14 \paperorientation portrait
17 \paragraph_separation indent
19 \quotes_language english
23 \paperpagestyle default
26 \added_space_top vfill \added_space_bottom vfill
27 SALOME Kernel resources for developer
30 Antoine Yessayan, Paul Rascle
33 Version 0.1 January 16, 2002
39 This document describes the development environment for C++ and Python.
40 Makefiles generation and usage are introduced in another document:
41 \begin_inset Quotes eld
44 using the SALOME configuration and building system environment
45 \begin_inset Quotes erd
49 Development environment is intended here as: trace and debug macros usage;
50 SALOME exceptions usage, in C++ and Python; user CORBA exceptions usage,
51 in C++ and Python, with and without Graphical User Interface; some general
52 purpose services such as singleton, used for CORBA connection and disconnection.
56 \begin_inset LatexCommand \tableofcontents{}
63 Trace and debug Utilities
66 During the development process, an execution log is useful to identify problems.
67 This log contains messages, variables values, source files names and line
69 It is recommended to verify assertions on variables values and if necessary,
70 to stop the execution at debug time, in order to validate all parts of
74 Two modes: debug and release
77 The goal of debug mode is to check as many features as possible during the
78 early stages of the development process.
79 The purpose of the utilities provided in SALOME is to help the developer
80 to add detailed traces and check variables values, without writing a lot
84 When the code is assumed to be valid, the release mode optimizes execution,
85 in terms of speed, memory, and display only user level messages.
88 But, some informations must always be displayed in both modes: especially
89 messages concerning environment or internal errors, with version identification.
90 When an end user is confronted to such a message, he may refer to a configurati
91 on documentation or send the message to the people in charge of SALOME installat
92 ion, or to the development team, following the kind of error.
95 C++ Macros for trace and debug
98 SALOME provides C++ macros for trace and debug.
101 SALOME/src/utils/utilities.h
103 and this file must be included in C++ source.
104 Some macros are activated only in debug mode, others are always activated.
105 To activate the debug mode,
109 must be defined, which is the case when SALOME Makefiles are generated
110 from configure, without options.
115 is undefined (release mode), the debug mode macros are defined empty (they
117 So, when switching from debug to release, it is possible (and recommended)
118 to let the macro calls unchanged in the source.
121 All the macros writing on the standard output start by flushing the standard
123 At the end of the display those macros flush the standard output.
126 Two informations are systematically added in front of the information displayed:
129 the name of the source file in which the macros is set;
132 the line number of the source file at which the macro is set.
133 \layout Subsubsection
135 Macros defined in debug and release modes
145 writes on the standard output informations about the compiling process:
149 the name of the compiler :
156 the date and the time of the compiling processing process.
163 does not have any argument.
164 Moreover, it is defined in both compiling mode :
178 #include "utilities.h"
181 int main(int argc , char **argv)
199 In both compiling mode
211 writes on the standard output the string which has been passed in argument
218 #include "utilities.h"
221 int main(int argc , char **argv)
231 INFOS("NORMAL END OF THE PROCESS");
243 main.cxx [5] : NORMAL END OF THE PROCESS
244 \layout Subsubsection
246 Macros defined only in debug mode
256 compiling mode only, the C++ macro
260 writes on the standard output the string which has been passed in argument
266 compiling mode, this macro is blank.
272 #include "utilities.h"
281 int main(int argc , char **argv)
291 const char *str = "Salome";
304 MESSAGE(c_str(st+" and CASTEM"));
316 - Trace main.cxx [8] : Salome
319 - Trace main.cxx [12] : Aster and CASTEM
329 compiling mode, The C++ macro
337 to the one passed in argument by the user and displays the result on the
343 compiling mode, this macro is blank.
349 #include "utilities.h"
352 int main(int argc , char **argv)
370 - Trace main.cxx [3] : Begin of a.out
380 compiling mode, The C++ macro
388 to the one passed in argument by the user and displays the result on the
394 compiling mode, this macro is blank.
400 #include "utilities.h"
403 int main(int argc , char **argv)
421 - Trace main.cxx [4] : Normal end of a.out
431 compiling mode, The C++ macro
435 displays its argument which is an application variable followed by the
436 value of the variable.
441 compiling mode, this macro is blank.
447 #include "utilities.h"
450 int main(int argc , char **argv)
459 if( i > 0 ) SCRUTE(i) ; i=i+1;
471 - Trace main.cxx [5] : i=999
481 compiling mode only, The C++ macro
485 checks the expression passed in argument to be not NULL.
486 If it is NULL the process is stopped and the condition is written on the
492 compiling mode, this macro is blank.
498 is already defined, this macro is ignored.
504 #include "utilities.h"
511 const char *ptrS = fonc();
517 cout << strlen(ptrS);
539 C++ exceptions: class SALOME_Exception
540 \layout Subsubsection
549 provides a generic method to send a message, with optional source file
550 name and line number.
551 This class is intended to serve as a base class for all kinds of exceptions
553 All the exceptions derived from
557 could be handled in a single catch, in which the message associated to
558 the exception is displayed, or sent to a log file.
565 inherits its behavior from the STL class exception.
566 \layout Subsubsection
573 SALOME/src/utils/utils_SALOME_Exception.hxx
575 must be included in the C++ source, when raised or trapped:
584 utils_SALOME_Exception.hxx
596 SALOME_Exception( const char *text,
599 const char *fileName=0,
602 const unsigned int lineNumber=0 );
605 The exception is raised like this:
608 throw SALOME_Exception("my pertinent message");
614 throw SALOME_Exception(LOCALIZED("my pertinent message"));
617 where LOCALIZED is a macro provided with
619 utils_SALOME_Exception.hxx
621 which gives file name and line number.
624 The exception is handled like this:
639 catch (const SALOME_Exception &ex)
645 cerr << ex.what() <<endl;
655 method overrides the one defined in the STL exception class.
659 \layout Subsubsection
668 provides a generic CORBA exception for SALOME, with an attribute that gives
669 an exception type,a message, plus optional source file name and line number.
673 This idl is intended to serve for all user CORBA exceptions raised in SALOME
674 code, as IDL specification does not support exception inheritance.
675 So, all the user CORBA exceptions from SALOME could be handled in a single
679 The exception types defined in idl are:
682 COMM CORBA communication problem,
685 BAD_PARAM Bad User parameters,
688 INTERNAL_ERROR application level problem (often irrecoverable).
691 CORBA system and user exceptions already defined in the packages used within
692 SALOME, such as OmniORB exceptions, must be handled separately.
693 \layout Subsubsection
701 The CORBA Server header for
705 and a macro to throw the exception are provided with the header
707 SALOME/src/Utils/Utils_CorbaException.hxx
712 #include "Utils_CorbaException.hxx"
715 The exception is raised with a macro which appends file name and line number.
718 if (myStudyName.size() == 0)
721 THROW_SALOME_CORBA_EXCEPTION("No Study Name given",
729 CORBA Client, GUI Qt C++
732 The CORBA Client header for
736 and a Qt function header that displays a message box are provided in
738 SALOME/src/SALOMEGUI/SALOMEGUI_QtCatchCorbaException.hxx
743 #include "SALOMEGUI_QtCatchCorbaException.hxx"
746 A typical exchange with a CORBA Servant will be:
756 // one ore more CORBA calls
762 catch (const SALOME::SALOME_Exception & S_ex)
768 QtCatchCorbaException(S_ex);
776 CORBA Client, C++, without GUI
779 Nothing specific has been provided to the developer yet.
780 See the idl or the Qt function
782 SALOMEGUI_QtCatchCorbaException.hxx
784 to see how to get the information given by the exception object.
791 \layout Subsubsection
796 A singleton is an application data which is created and deleted only once
797 at the end of the application process.
798 The C++ compiler allows the user to create a static singleton data before
799 the first executable statement.
800 They are deleted after the last statement execution.
807 template class deals with dynamic singleton.
808 It is useful for functor objects.
809 For example, an object that connects the application to a system at creation
810 and disconnects the application at deletion.
811 \layout Subsubsection
816 To create a single instance a POINT object :
819 # include "Utils_SINGLETON.hxx"
826 POINT *ptrPoint=SINGLETON_<POINT>::Instance() ;
829 assert(ptrPoint!=NULL) ;
832 No need to delete ptrPoint.
833 Deletion is achieved automatically at exit.
834 If the user tries to create more than one singleton by using the class
837 SINGLETON_<TYPE>::Instance()
839 , the pointer is returned with the same value even if this is done in different
840 functions (threads ?).
843 POINT *p1=SINGLETON_<POINT>::Instance() ;
850 POINT *p2=SINGLETON_<POINT>::Instance() ;
854 \layout Subsubsection
859 Here are the principles features of the singleton design :
862 the user creates an object of class
866 by using the class method
868 SINGLETON_<TYPE>::Instance()
870 which returns a pointer to the single object ;
875 SINGLETON_<TYPE>::Instance()
877 uses the default constructor of class
884 at the same time, this class method creates a destructor object which is
885 added to the generic list of destructor objects to be executed at the end
893 at the end of the application process all the deletions are performed by
899 function which executes the destruction objects end then deletes the destructi
900 ons objects themselves ;
908 function using atexit() C \SpecialChar ~
909 function is embedded in a static single object
