some formatting fixes, missing empty lines, literal passthoughs
[nobug] / doc / multithreading.txt
1 HEAD- Multithreading; multithreading; using NoBug in multithreaded programs
2
3 It is important that NoBug protects certain operations with locks in
4 multithreaded programs. You have to ensure that 'HAVE_PTHREAD_H' is defined by
5 the configuration system and use the 'libnobugmt' library for linking. It is
6 particular important that libraries using NoBug are compiled with
7 'HAVE_PTHREAD_H' enabled when they are intended to be used in multithreaded
8 programs.
9
10 When Multithreading is used, log messages contain a identifier of the
11 originating thread. This identifier should be set by
12
13 PARA NOBUG_THREAD_ID_SET; THREAD_ID_SET; set or reset thread id
14
15  NOBUG_THREAD_ID_SET(name)
16
17 `name`::
18         New name for the thread
19
20 Nobug will assemble a unique identifier by appending a underscore and a
21 number to name, for example `NOBUG_THREAD_ID_SET("gui")` will result in a
22 identifier like "gui_5". When you don't set a thread identifier, then NoBug
23 assigns one automatically with the name 'thread' preprended if needed. Thread
24 identifiers may be reset with a new call to this macro.
25
26 PARA NOBUG_THREAD_ID_GET; THREAD_ID_GET; query thread id
27
28  NOBUG_THREAD_ID_GET
29
30 Will return a const char* of the thread id in multithreaded programs and
31 a pointer to a literal empty string in singlethreaded programs.
32
33 PARA NOBUG_THREAD_DATA; THREAD_DATA; thread local data for application use
34
35  NOBUG_THREAD_DATA
36
37 Evaluates to a variable of type `void*` which can be used to store
38 thread local information. This is useable for xref:_callbacks[callbacks] which may
39 prepare context information to be reused later.
40
41 This macro is also available in singlethreaded programs, refering to a
42 single global variable.
43
44 Nobug initializes this variable to `NULL` and then touches it never again.
45