doc/salome/kernel_resources.dox

   1 /*!
   2
   3 \page kernel_resources Salome Kernel resources for developer
   4
   5
   6
   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.
  17
  18 \section S2_kernel_res Trace and debug Utilities
  19
  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
  26 of code.
  27
  28 \subsection subsection21 Two modes: debug and release
  29
  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.
  35
  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.
  39
  40 But, some informations 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.
  47
  48 \subsection subsection22 C++ Macros for trace and debug
  49
  50 %SALOME provides C++ macros for trace and debug. These
  51 macros are in:
  52
  53 \code
  54 KERNEL_SRC/src/SALOMELocalTrace/utilities.h
  55 \endcode
  56
  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.
  68
  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.
  75
  76 Three informations 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
  81   is set.
  82
  83 \subsection subsection23 Macros defined in debug and release modes
  84
  85 - <b>INFOS_COMPILATION</b>\n
  86    The C++ macro INFOS_COMPILATION writes on the trace
  87    buffer pool informations 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.
  90    .
  91    This macro INFOS_COMPILATION does not have any
  92    argument. Moreover, it is defined in both compiling
  93    mode : _DEBUG_ and _RELEASE_.\n
  94    Example:
  95    \code
  96 #include "utilities.h"
  97 int main(int argc , char **argv)
  98 {
  99   INFOS_COMPILATION;
 100   ...
 101 }
 102   \endcode
 103
 104 - <b>INFOS</b>\n
 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
 108    Example:
 109    \code
 110 #include "utilities.h"
 111 int main(int argc , char **argv)
 112 {
 113   ...
 114   INFOS("NORMAL END OF THE PROCESS");
 115   return 0;
 116 }
 117    \endcode
 118    Displays:
 119    \code
 120 main.cxx [5] : NORMAL END OF THE PROCESS
 121    \endcode
 122
 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.
 129
 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
 135    are lost.
 136
 137 \subsection subsection24 Macros defined only in debug mode
 138
 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
 144    Example:
 145    \code
 146 #include "utilities.h"
 147 #include <string>
 148
 149 using namespace std;
 150
 151 int main(int argc , char **argv)
 152 {
 153   ...
 154   const char *str = "Salome";
 155   MESSAGE(str);
 156   ... const string st;
 157   st = "Aster";
 158   MESSAGE(c_str(st+" and CASTEM"));
 159   return 0;
 160 }
 161
 162    \endcode
 163    Displays:
 164    \code
 165 - Trace main.cxx [8] : Salome
 166 - Trace main.cxx [12] : Aster and CASTEM
 167    \endcode
 168
 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
 174    macro is blank.\n
 175    Example:
 176    \code
 177 #include "utilities.h"
 178 int main(int argc , char **argv)
 179 {
 180   BEGIN_OF(argv[0]);
 181   return 0;
 182 }
 183    \endcode
 184    Displays:
 185    \code
 186      - Trace main.cxx [3] : Begin of a.out
 187    \endcode
 188
 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
 194    macro is blank.\n
 195    Example:
 196    \code
 197 #include "utilities.h"
 198 int main(int argc , char **argv)
 199 {
 200   END_OF(argv[0]);
 201   return 0;
 202 }
 203   \endcode
 204    Displays:
 205    \code
 206 - Trace main.cxx [4] : Normal end of a.out
 207    \endcode
 208
 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
 214    Example:
 215    \code
 216 #include "utilities.h"
 217 int main(int argc , char **argv)
 218 {
 219   const int i=999;
 220   if( i > 0 ) SCRUTE(i) ; i=i+1;
 221   return 0;
 222 }
 223    \endcode
 224    Displays:
 225    \code
 226 - Trace main.cxx [5] : i=999
 227    \endcode
 228
 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
 237    Example:
 238    \code
 239 #include "utilities.h"
 240 ...
 241 const char *ptrS = fonc();
 242 ASSERT(ptrS!=NULL);
 243 cout << strlen(ptrS);
 244 float table[10];
 245 int k;
 246 ...
 247 ASSERT(k<10);
 248 cout << table[k];
 249    \endcode
 250
 251 \section S3_kernel_res Exceptions
 252
 253 \subsection subsection31 C++ exceptions: class SALOME_Exception
 254
 255 \subsubsection subsubsection311 Definition
 256
 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
 264 log file.
 265
 266 The class SALOME_Exception inherits its behavior from
 267 the STL class exception.
 268
 269 \subsubsection subsubsection312 Usage
 270
 271 The header %SALOME/src/utils/utils_SALOME_Exception.hxx
 272 must be included in the C++ source, when raised or trapped:
 273
 274 \code
 275 #include "utils_SALOME_Exception.hxx"
 276 \endcode
 277
 278 The SALOME_Exception constructor is:
 279
 280 \code
 281 SALOME_Exception( const char *text,
 282                   const char *fileName=0,
 283                   const unsigned int lineNumber=0 );
 284 \endcode
 285
 286 The exception is raised like this:
 287
 288 \code
 289 throw SALOME_Exception("my pertinent message");
 290 \endcode
 291
 292 or like this:
 293
 294 \code
 295 throw SALOME_Exception(LOCALIZED("my pertinent message"));
 296 \endcode
 297
 298 where LOCALIZED is a macro provided with
 299 utils_SALOME_Exception.hxx which gives file name and
 300 line number.
 301
 302 The exception is handled like this:
 303
 304 \code
 305    try
 306 {
 307   ...
 308 }
 309 catch (const SALOME_Exception &ex)
 310 {
 311   cerr << ex.what() <<endl;
 312 }
 313 \endcode
 314
 315 The what() method overrides the one defined in the STL
 316 exception class.
 317
 318 \subsection subsection32 CORBA exceptions
 319
 320 \subsubsection subsubsection321 Definition
 321
 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.
 326
 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
 331 single catch.
 332
 333 The exception types defined in idl are:
 334
 335   - COMM CORBA communication problem,
 336
 337   - BAD_PARAM Bad User parameters,
 338
 339   - INTERNAL_ERROR application level problem (often irrecoverable).
 340
 341 CORBA system and user exceptions already defined in the
 342 packages used within %SALOME, such as OmniORB
 343 exceptions, must be handled separately.
 344
 345 \subsubsection subsubsection322 Usage
 346 <b>CORBA servant, C++</b>
 347
 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:
 351
 352    \code
 353 #include "Utils_CorbaException.hxx"
 354    \endcode
 355
 356    The exception is raised with a macro which appends file
 357    name and line number:
 358
 359    \code
 360 if (myStudyName.size() == 0)
 361   THROW_SALOME_CORBA_EXCEPTION("No Study Name given",
 362                                SALOME::BAD_PARAM);
 363    \endcode
 364
 365 <b>CORBA Client, GUI Qt C++ (NO MORE AVAILABLE in %SALOME 3.x and later)</b>
 366
 367    The CORBA Client header for SALOME_Exception and a Qt
 368    function header that displays a message box are
 369    provided in:
 370
 371      KERNEL_SRC/src/SALOMEGUI/SALOMEGUI_QtCatchCorbaException.hxx
 372
 373    \code
 374 #include "SALOMEGUI_QtCatchCorbaException.hxx"
 375    \endcode
 376
 377    %A typical exchange with a CORBA Servant will be:
 378
 379    \code
 380 try
 381 {
 382  ... // one ore more CORBA calls
 383 }
 384
 385 catch (const SALOME::SALOME_Exception & S_ex)
 386 {
 387   QtCatchCorbaException(S_ex);
 388 }
 389    \endcode
 390
 391 <b>CORBA Client, C++, without GUI</b>
 392
 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.
 397
 398 \section S4_kernel_res Miscellaneous tools
 399
 400 \subsection subsection41 Singleton
 401 \subsubsection subsubsection411 Definition
 402
 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.
 408
 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.
 413
 414 \subsubsection subsubsection412 Usage
 415
 416 To create a single instance of a POINT %object:
 417
 418 \code
 419 # include "Utils_SINGLETON.hxx"
 420 ...
 421 POINT *ptrPoint=SINGLETON_<POINT>::Instance() ;
 422 assert(ptrPoint!=NULL) ;
 423 \endcode
 424
 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 ?):
 431
 432 \code
 433 POINT *p1=SINGLETON_<POINT>::Instance() ;
 434 ...
 435 POINT *p2=SINGLETON_<POINT>::Instance() ;
 436
 437 assert(p1==p2)
 438 \endcode
 439
 440 \subsubsection subsubsection413 Design description
 441
 442 Here are the principles features of the singleton
 443 design:
 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_().
 459
 460
 461 */