doc/initialization.txt

   1 HEAD- Initialization;;
   2
   3 HEAD++ Global Initialization;;
   4
   5 Before anything from NoBug can be used, NoBug must be initialised. This
   6 is archived by calling the `NOBUG_INIT()` macro before using any other of the
   7 NoBug facilities.
   8
   9 `NOBUG_INIT` can be called more than once, subsequent calls will be a no-op,
  10 thus initialising in main and in libraries won't interfere with one another.
  11
  12 Care must be taken when one already using NoBug features from dynamic
  13 initialized things in C++, one has to ensure that NoBug gets initialized first
  14 possibly by pulling up a singleton at very first.
  15
  16
  17 HEAD== Destroying NoBug;;
  18
  19 Since NoBug is intended to be available throughout its whole lifetime,
  20 destroying it is not to be advised. Nevertheless, there is a destroy function
  21
  22  void nobug_destroy (void);
  23
  24 to shutdown NoBug, and this frees all resources associated with it.
  25 This is mostly used in the NoBug testsuite itself to check for leaks,
  26 and it might be useful for other programs which employ some kind of
  27 leak checker.
  28
  29
  30 HEAD== Init logging Flags;;
  31
  32 If you want to use environment variable controlled debuging, then you have to
  33 initialize each defined flag with
  34
  35   NOBUG_INIT_FLAG(flagname)
  36
  37 or
  38
  39   NOBUG_INIT_FLAG_LIMIT(flagname, default)
  40
  41 or one of the C++ compatibility macros.
  42
  43 This is documented later in the xref:logconfig[logging configuration] chapter.
  44
  45
  46 HEAD== Threads;;
  47
  48 In Multithreaded programs you should assign an identifier to each
  49 thread. A thread identifier is a string which will be automatically
  50 appended with an underscore and an incrementing integer. It is is
  51 created using the following:
  52
  53   NOBUG_THREAD_ID_SET(name)
  54
  55 For example, calling `NOBUG_THREAD_ID_SET("worker")` will result in a thread
  56 identifier 'worker_1'.
  57
  58 If you don't set an identifier, then NoBug will automatically assign
  59 one.  This is further documented in the xref:multithreading[multi threading]
  60 section of this manual.
  61
  62
  63 PARA Initialization example; initexample; initialize NoBug, example
  64
  65 Thus the boilerplate code to pulling up NoBug in a multithreaded program looks
  66 like (omit `NOBUG_THREAD_ID_SET()` in single threaded programs):
  67 [source,C]
  68 -------------------------------------------------------
  69 #include <nobug.h>
  70 NOBUG_DEFINE_FLAG(example);
  71
  72 ...
  73
  74 int main()
  75 {
  76     NOBUG_INIT();
  77     NOBUG_THREAD_ID_SET("main");
  78     NOBUG_INIT_FLAG(example);
  79
  80     ...
  81 }
  82 -------------------------------------------------------
  83