doc/initialization.txt

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