diff options
Diffstat (limited to 'docs/ref/api/thr/nng_thread.md')
| -rw-r--r-- | docs/ref/api/thr/nng_thread.md | 84 |
1 files changed, 0 insertions, 84 deletions
diff --git a/docs/ref/api/thr/nng_thread.md b/docs/ref/api/thr/nng_thread.md deleted file mode 100644 index e13e77c6..00000000 --- a/docs/ref/api/thr/nng_thread.md +++ /dev/null @@ -1,84 +0,0 @@ -# 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 |
