1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
|
# nng_thread
## NAME
nng_thread --- thread of execution
## SYNOPSIS
```c
#include <nng/nng.h>
typedef struct nng_thread nng_thread;
int nng_thread_create(nng_thread **thrp, void (*func)(void *), void *arg);
void nng_thread_destroy(nng_thread *thr);
void nng_thread_set_name(nng_thread *thr, const char *name);
```
### DESCRIPTION
The {{i:`nng_thread`}} structure is used to represent a {{i:thread}} of execution.
In NNG, a thread has an execution fuction _func_, and can be assumed to run this concurrently
to other threads, including the main thread of the application. The thread persists
until the function _func_ returns.
> [!TIP]
> The detail of whether the thread represents an operating system thread,
> a process, or a "green" thread (also known as a a fiber or coroutine) is determined by the platform.
> Portable applications should avoid depending on this implementation detail.
The `nng_thread_create` function creates a thread,
running _func_ with the argument _arg_.
The thread is started immediately.
A pointer to the thread object is returned in _thrp_.
Using threads created by this function can make it easy to write
programs that use simple sequential execution, using functions in the
_NNG_ suite that would otherwise normally wait synchronously for completion.
When the thread is no longer needed, the {{i: `nng_thread_destroy`}}
function should be used to reap it.
(This function will block waiting for _func_ to return.)
> [!IMPORTANT]
> Thread objects created by this function may not be real system-level
> threads capable of performing blocking I/O operations using normal blocking system calls.
> If use of blocking system calls is required (not including APIs provided
> by the _NNG_ library itself of course), then real OS-specific threads
> should be created instead (such as with `pthread_create` or similar functions.)
> [!IMPORTANT]
> Thread objects created by this function cannot be passed to any system threading functions.
> [!TIP]
> The system may impose limits on the number of threads that can be created.
> Typically applications should not create more than a dozen of these.
> If greater concurrency or scalability is needed, consider instead using
> an asynchronous model using [`nng_aio`][aio] structures.
> [!TIP]
> Threads can be synchronized using [mutexes][mutex] and
> [condition variables][condvar].
In order to facilitate debugging, {{i:`nng_thread_set_name`}} may be called
to provide a name for the thread. This may change how the thread is represented
in debuggers. Not all platforms support setting the thread name.
## RETURN VALUES
The `nng_thread_create` function returns 0 on success, and non-zero otherwise.
## ERRORS
- `NNG_ENOMEM`: Insufficient free memory exists.
## SEE ALSO
[nng_cv][condvar],
[nng_mutex][mutex]
[condvar]: ../thr/nng_cv.md
[mutex]: ../thr/nng_mtx.md
[aio]: TODO.md
|
