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 *This document corresponds to SALOME2 3.2.0*
  10
  11 :Authors:
  12    Antoine Yessayan,
  13    Paul Rascle
  14
  15 :Version:  0.3 - february 17, 2006
  16
  17 +-------------------------------------------+
  18 | **WORK in PROGRESS, INCOMPLETE DOCUMENT** |
  19 +-------------------------------------------+
  20
  21 -------------------------------------------------------------------------------
  22
  23 **Abstract**
  24
  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.
  35
  36 .. contents::
  37 .. sectnum::
  38
  39 -------------------------------------------------------------------------------
  40
  41 Trace and debug Utilities
  42 =========================
  43
  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
  50 of code.
  51
  52 Two modes: debug and release
  53 ----------------------------
  54
  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.
  60
  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.
  64
  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.
  72
  73 C++ Macros for trace and debug
  74 ------------------------------
  75
  76 SALOME provides C++ macros for trace and debug. These
  77 macros are in::
  78
  79   KERNEL_SRC/src/SALOMELocalTrace/utilities.h
  80
  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.
  92
  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.
  99
 100 Three informations are systematically added in front of
 101 the information displayed:
 102
 103 * the thread number from which the message come from;
 104
 105 * the name of the source file in which the macros is set;
 106
 107 * the line number of the source file at which the macro
 108   is set.
 109
 110 Macros defined in debug and release modes
 111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 112
 113 **INFOS_COMPILATION**
 114    The C++ macro INFOS_COMPILATION writes on the trace
 115    buffer pool informations about the compiling process:
 116
 117    * the name of the compiler : g++, KCC, CC, pgCC;
 118
 119    * the date and the time of the compiling processing process.
 120
 121    This macro INFOS_COMPILATION does not have any
 122    argument. Moreover, it is defined in both compiling
 123    mode : _DEBUG_ and _RELEASE_.
 124
 125    Example::
 126
 127      #include "utilities.h"
 128      int main(int argc , char **argv)
 129      {
 130        INFOS_COMPILATION;
 131        ...
 132      }
 133      INFOS(str)
 134
 135 **INFOS**
 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.
 139
 140    Example::
 141
 142      #include "utilities.h"
 143      int main(int argc , char **argv)
 144      {
 145        ...
 146        INFOS("NORMAL END OF THE PROCESS");
 147        return 0;
 148      }
 149
 150    displays::
 151
 152       main.cxx [5] : NORMAL END OF THE PROCESS
 153
 154
 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.
 161
 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
 167    are lost.
 168
 169 Macros defined only in debug mode
 170 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 171
 172 **MESSAGE(str)**
 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.
 177
 178    Example::
 179
 180      #include "utilities.h"
 181      #include <string>
 182
 183      using namespace std;
 184
 185      int main(int argc , char **argv)
 186      {
 187        ...
 188        const char *str = "Salome";
 189        MESSAGE(str);
 190        ... const string st;
 191        st = "Aster";
 192        MESSAGE(c_str(st+" and CASTEM"));
 193        return 0;
 194      }
 195
 196    displays::
 197
 198      - Trace main.cxx [8] : Salome
 199      - Trace main.cxx [12] : Aster and CASTEM
 200
 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
 206    macro is blank.
 207
 208    Example::
 209
 210       #include "utilities.h"
 211       int main(int argc , char **argv)
 212       {
 213         BEGIN_OF(argv[0]);
 214         return 0;
 215       }
 216
 217    displays::
 218
 219      - Trace main.cxx [3] : Begin of a.out
 220
 221
 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
 227    macro is blank.
 228
 229    Example::
 230
 231       #include "utilities.h"
 232       int main(int argc , char **argv)
 233       {
 234         END_OF(argv[0]);
 235         return 0;
 236       }
 237
 238    displays::
 239
 240       - Trace main.cxx [4] : Normal end of a.out
 241
 242 **SCRUTE(var)**
 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.
 247
 248    Example::
 249
 250       #include "utilities.h"
 251       int main(int argc , char **argv)
 252       {
 253         const int i=999;
 254         if( i > 0 ) SCRUTE(i) ; i=i+1;
 255         return 0;
 256       }
 257
 258    displays::
 259
 260       - Trace main.cxx [5] : i=999
 261
 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.
 270
 271    Example::
 272
 273       #include "utilities.h"
 274       ...
 275       const char *ptrS = fonc();
 276       ASSERT(ptrS!=NULL);
 277       cout << strlen(ptrS);
 278       float table[10];
 279       int k;
 280       ...
 281       ASSERT(k<10);
 282       cout << table[k];
 283
 284 Exceptions
 285 ==========
 286
 287 C++ exceptions: class SALOME_Exception
 288 --------------------------------------
 289
 290 definition
 291 ~~~~~~~~~~
 292
 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
 300 log file.
 301
 302 The class SALOME_Exception inherits its behavior from
 303 the STL class exception.
 304
 305 usage
 306 ~~~~~
 307
 308 The header SALOME/src/utils/utils_SALOME_Exception.hxx
 309 must be included in the C++ source, when raised or trapped::
 310
 311    #include "utils_SALOME_Exception.hxx"
 312
 313 The SALOME_Exception constructor is::
 314
 315    SALOME_Exception( const char *text,
 316                      const char *fileName=0,
 317                      const unsigned int lineNumber=0 );
 318
 319 The exception is raised like this::
 320
 321    throw SALOME_Exception("my pertinent message");
 322
 323 or like this::
 324
 325    throw SALOME_Exception(LOCALIZED("my pertinent message"));
 326
 327 where LOCALIZED is a macro provided with
 328 ``utils_SALOME_Exception.hxx`` which gives file name and
 329 line number.
 330
 331 The exception is handled like this::
 332
 333    try
 334      {
 335        ...
 336      }
 337    catch (const SALOME_Exception &ex)
 338      {
 339        cerr << ex.what() <<endl;
 340      }
 341
 342 The what() method overrides the one defined in the STL
 343 exception class.
 344
 345 CORBA exceptions
 346 ----------------
 347
 348 definition
 349 ~~~~~~~~~~
 350
 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.
 355
 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
 360 single catch.
 361
 362 The exception types defined in idl are:
 363
 364   - COMM CORBA communication problem,
 365
 366   - BAD_PARAM Bad User parameters,
 367
 368   - INTERNAL_ERROR application level problem (often irrecoverable).
 369
 370 CORBA system and user exceptions already defined in the
 371 packages used within SALOME, such as OmniORB
 372 exceptions, must be handled separately.
 373
 374 usage
 375 ~~~~~
 376
 377 CORBA servant, C++
 378 ^^^^^^^^^^^^^^^^^^
 379
 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``::
 383
 384       #include "Utils_CorbaException.hxx"
 385
 386    The exception is raised with a macro which appends file
 387    name and line number::
 388
 389       if (myStudyName.size() == 0)
 390         THROW_SALOME_CORBA_EXCEPTION("No Study Name given",
 391                                      SALOME::BAD_PARAM);
 392
 393 CORBA Client, GUI Qt C++
 394 ^^^^^^^^^^^^^^^^^^^^^^^^
 395
 396    **NO MORE AVAILABLE in SALOME 3.x**
 397
 398    The CORBA Client header for SALOME_Exception and a Qt
 399    function header that displays a message box are
 400    provided in:
 401
 402      ``KERNEL_SRC/src/SALOMEGUI/SALOMEGUI_QtCatchCorbaException.hxx``
 403
 404    ::
 405
 406      #include "SALOMEGUI_QtCatchCorbaException.hxx"
 407
 408    A typical exchange with a CORBA Servant will be::
 409
 410       try
 411       {
 412         ... // one ore more CORBA calls
 413       }
 414
 415       catch (const SALOME::SALOME_Exception & S_ex)
 416       {
 417         QtCatchCorbaException(S_ex);
 418       }
 419
 420
 421
 422 CORBA Client, C++, without GUI
 423 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 424
 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.
 429
 430 Miscellaneous tools
 431 ===================
 432
 433 Singleton
 434 ---------
 435
 436 Definition
 437 ~~~~~~~~~~
 438
 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.
 444
 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.
 449
 450 Usage
 451 ~~~~~
 452
 453 To create a single instance of a POINT object::
 454
 455   # include "Utils_SINGLETON.hxx"
 456   ...
 457   POINT *ptrPoint=SINGLETON_<POINT>::Instance() ;
 458   assert(ptrPoint!=NULL) ;
 459
 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 ?)::
 466
 467   POINT *p1=SINGLETON_<POINT>::Instance() ;
 468   ...
 469   POINT *p2=SINGLETON_<POINT>::Instance() ;
 470
 471   assert(p1==p2)
 472
 473 Design description
 474 ~~~~~~~~~~~~~~~~~~
 475
 476 Here are the principles features of the singleton
 477 design:
 478
 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 ;
 482
 483 * to create an object, ``SINGLETON_<TYPE>::Instance()``
 484   uses the default constructor of class TYPE ;
 485
 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) ;
 490
 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 ;
 495
 496 * the ``Nettoyage()`` C  function using ``atexit()`` C  function
 497   is embedded in a static single object ``ATEXIT_()``.
 498
 499
 500 -------------------------------------------------------------------------------
 501
 502 +----------------------------------+------------------------------------------+
 503 | `General KERNEL documentation`_  | `End User KERNEL Doxygen documentation`_ |
 504 +----------------------------------+------------------------------------------+
 505
 506 .. _`General KERNEL documentation`:           ./index.html
 507 .. _`End User KERNEL Doxygen documentation`:  ./tui/KERNEL/index.html