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