doc/kernel_resources.txt

   1 ======================================================================
   2 SALOME Kernel resources for developer
   3 ======================================================================
   4
   5 *html version of this document is produced with docutils*::
   6
   7   rst2html doc.txt > doc.html
   8
   9 :Authors:
  10    Antoine Yessayan,
  11    Paul Rascle
  12
  13 :Version:  0.3 - february 17, 2006
  14
  15 +-------------------------------------------+
  16 | **WORK in PROGRESS, INCOMPLETE DOCUMENT** |
  17 +-------------------------------------------+
  18
  19 **Abstract**
  20
  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.
  31
  32 .. contents::
  33 .. sectnum::
  34
  35 Trace and debug Utilities
  36 =========================
  37
  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
  44 of code.
  45
  46 Two modes: debug and release
  47 ----------------------------
  48
  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.
  54
  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.
  58
  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.
  66
  67 C++ Macros for trace and debug
  68 ------------------------------
  69
  70 SALOME provides C++ macros for trace and debug. These
  71 macros are in::
  72
  73   KERNEL_SRC/src/SALOMELocalTrace/utilities.h
  74
  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.
  86
  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.
  93
  94 Three informations are systematically added in front of
  95 the information displayed:
  96
  97 * the thread number from which the message come from;
  98
  99 * the name of the source file in which the macros is set;
 100
 101 * the line number of the source file at which the macro
 102   is set.
 103
 104 Macros defined in debug and release modes
 105 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 106
 107 **INFOS_COMPILATION**
 108    The C++ macro INFOS_COMPILATION writes on the trace
 109    buffer pool informations about the compiling process:
 110
 111    * the name of the compiler : g++, KCC, CC, pgCC;
 112
 113    * the date and the time of the compiling processing process.
 114
 115    This macro INFOS_COMPILATION does not have any
 116    argument. Moreover, it is defined in both compiling
 117    mode : _DEBUG_ and _RELEASE_.
 118
 119    Example::
 120
 121      #include "utilities.h"
 122      int main(int argc , char **argv)
 123      {
 124        INFOS_COMPILATION;
 125        ...
 126      }
 127      INFOS(str)
 128
 129 **INFOS**
 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.
 133
 134    Example::
 135
 136      #include "utilities.h"
 137      int main(int argc , char **argv)
 138      {
 139        ...
 140        INFOS("NORMAL END OF THE PROCESS");
 141        return 0;
 142      }
 143
 144    displays::
 145
 146       main.cxx [5] : NORMAL END OF THE PROCESS
 147
 148
 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.
 155
 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
 161    are lost.
 162
 163 Macros defined only in debug mode
 164 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 165
 166 **MESSAGE(str)**
 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.
 171
 172    Example::
 173
 174      #include "utilities.h"
 175      #include <string>
 176
 177      using namespace std;
 178
 179      int main(int argc , char **argv)
 180      {
 181        ...
 182        const char *str = "Salome";
 183        MESSAGE(str);
 184        ... const string st;
 185        st = "Aster";
 186        MESSAGE(c_str(st+" and CASTEM"));
 187        return 0;
 188      }
 189
 190    displays::
 191
 192      - Trace main.cxx [8] : Salome
 193      - Trace main.cxx [12] : Aster and CASTEM
 194
 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
 200    macro is blank.
 201
 202    Example::
 203
 204       #include "utilities.h"
 205       int main(int argc , char **argv)
 206       {
 207         BEGIN_OF(argv[0]);
 208         return 0;
 209       }
 210
 211    displays::
 212
 213      - Trace main.cxx [3] : Begin of a.out
 214
 215
 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
 221    macro is blank.
 222
 223    Example::
 224
 225       #include "utilities.h"
 226       int main(int argc , char **argv)
 227       {
 228         END_OF(argv[0]);
 229         return 0;
 230       }
 231
 232    displays::
 233
 234       - Trace main.cxx [4] : Normal end of a.out
 235
 236 **SCRUTE(var)**
 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.
 241
 242    Example::
 243
 244       #include "utilities.h"
 245       int main(int argc , char **argv)
 246       {
 247         const int i=999;
 248         if( i > 0 ) SCRUTE(i) ; i=i+1;
 249         return 0;
 250       }
 251
 252    displays::
 253
 254       - Trace main.cxx [5] : i=999
 255
 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.
 264
 265    Example::
 266
 267       #include "utilities.h"
 268       ...
 269       const char *ptrS = fonc();
 270       ASSERT(ptrS!=NULL);
 271       cout << strlen(ptrS);
 272       float table[10];
 273       int k;
 274       ...
 275       ASSERT(k<10);
 276       cout << table[k];
 277
 278 Exceptions
 279 ==========
 280
 281 C++ exceptions: class SALOME_Exception
 282 --------------------------------------
 283
 284 definition
 285 ~~~~~~~~~~
 286
 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
 294 log file.
 295
 296 The class SALOME_Exception inherits its behavior from
 297 the STL class exception.
 298
 299 usage
 300 ~~~~~
 301
 302 The header SALOME/src/utils/utils_SALOME_Exception.hxx
 303 must be included in the C++ source, when raised or trapped::
 304
 305    #include "utils_SALOME_Exception.hxx"
 306
 307 The SALOME_Exception constructor is::
 308
 309    SALOME_Exception( const char *text,
 310                      const char *fileName=0,
 311                      const unsigned int lineNumber=0 );
 312
 313 The exception is raised like this::
 314
 315    throw SALOME_Exception("my pertinent message");
 316
 317 or like this::
 318
 319    throw SALOME_Exception(LOCALIZED("my pertinent message"));
 320
 321 where LOCALIZED is a macro provided with
 322 ``utils_SALOME_Exception.hxx`` which gives file name and
 323 line number.
 324
 325 The exception is handled like this::
 326
 327    try
 328      {
 329        ...
 330      }
 331    catch (const SALOME_Exception &ex)
 332      {
 333        cerr << ex.what() <<endl;
 334      }
 335
 336 The what() method overrides the one defined in the STL
 337 exception class.
 338
 339 CORBA exceptions
 340 ----------------
 341
 342 definition
 343 ~~~~~~~~~~
 344
 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.
 349
 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
 354 single catch.
 355
 356 The exception types defined in idl are:
 357
 358   - COMM CORBA communication problem,
 359
 360   - BAD_PARAM Bad User parameters,
 361
 362   - INTERNAL_ERROR application level problem (often irrecoverable).
 363
 364 CORBA system and user exceptions already defined in the
 365 packages used within SALOME, such as OmniORB
 366 exceptions, must be handled separately.
 367
 368 usage
 369 ~~~~~
 370
 371 CORBA servant, C++
 372 ^^^^^^^^^^^^^^^^^^
 373
 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``::
 377
 378       #include "Utils_CorbaException.hxx"
 379
 380    The exception is raised with a macro which appends file
 381    name and line number::
 382
 383       if (myStudyName.size() == 0)
 384         THROW_SALOME_CORBA_EXCEPTION("No Study Name given",
 385                                      SALOME::BAD_PARAM);
 386
 387 CORBA Client, GUI Qt C++
 388 ^^^^^^^^^^^^^^^^^^^^^^^^
 389
 390    **NO MORE AVAILABLE in SALOME 3.x**
 391
 392    The CORBA Client header for SALOME_Exception and a Qt
 393    function header that displays a message box are
 394    provided in:
 395
 396      ``KERNEL_SRC/src/SALOMEGUI/SALOMEGUI_QtCatchCorbaException.hxx``
 397
 398    ::
 399
 400      #include "SALOMEGUI_QtCatchCorbaException.hxx"
 401
 402    A typical exchange with a CORBA Servant will be::
 403
 404       try
 405       {
 406         ... // one ore more CORBA calls
 407       }
 408
 409       catch (const SALOME::SALOME_Exception & S_ex)
 410       {
 411         QtCatchCorbaException(S_ex);
 412       }
 413
 414
 415
 416 CORBA Client, C++, without GUI
 417 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 418
 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.
 423
 424 Miscellaneous tools
 425 ===================
 426
 427 Singleton
 428 ---------
 429
 430 Definition
 431 ~~~~~~~~~~
 432
 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.
 438
 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.
 443
 444 Usage
 445 ~~~~~
 446
 447 To create a single instance of a POINT object::
 448
 449   # include "Utils_SINGLETON.hxx"
 450   ...
 451   POINT *ptrPoint=SINGLETON_<POINT>::Instance() ;
 452   assert(ptrPoint!=NULL) ;
 453
 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 ?)::
 460
 461   POINT *p1=SINGLETON_<POINT>::Instance() ;
 462   ...
 463   POINT *p2=SINGLETON_<POINT>::Instance() ;
 464
 465   assert(p1==p2)
 466
 467 Design description
 468 ~~~~~~~~~~~~~~~~~~
 469
 470 Here are the principles features of the singleton
 471 design:
 472
 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 ;
 476
 477 * to create an object, ``SINGLETON_<TYPE>::Instance()``
 478   uses the default constructor of class TYPE ;
 479
 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) ;
 484
 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 ;
 489
 490 * the ``Nettoyage()`` C  function using ``atexit()`` C  function
 491   is embedded in a static single object ``ATEXIT_()``.