586183e0a80001479c7496310f0db372f9bc68a2
[nobug] / 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 Calling `NOBUG_THREAD_ID_SET("worker")` will yield in a thread
56 identifier 'worker_1' for example.
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 looks like:
66
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