54ca6187a020d9127bee2fd0e5e0d3efed8542cc
[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  NOBUG_THREAD_ID_SET(name)
15
16 `name`::
17         New name for the thread
18
19 Nobug will assemble a unique identifier by appending a underscore and a
20 number to name, for example `NOBUG_THREAD_ID_SET("gui")` will result in a
21 identifier like "gui_5". When you don't set a thread identifier, then NoBug
22 assigns one automatically with the name 'thread' preprended if needed. Thread
23 identifiers may be reset with a new call to this macro.
24
25 PARA NOBUG_THREAD_ID_GET; THREAD_ID_GET; query thread id
26  NOBUG_THREAD_ID_GET
27
28 Will return a const char* of the thread id in multithreaded programs and
29 a pointer to a literal empty string in singlethreaded programs.
30
31 PARA NOBUG_THREAD_DATA; THREAD_DATA; thread local data for application use
32  NOBUG_THREAD_DATA
33
34 Evaluates to a variable of type `void*` which can be used to store
35 thread local information. This is useable for xref:_callbacks[callbacks] which may
36 prepare context information to be reused later.
37
38 This macro is also available in singlethreaded programs, refering to a
39 single global variable.
40
41 Nobug initializes this variable to `NULL` and then touches it never again.
42