aboutsummaryrefslogtreecommitdiff
path: root/docs/ref/api/thr
diff options
context:
space:
mode:
Diffstat (limited to 'docs/ref/api/thr')
-rw-r--r--docs/ref/api/thr/nng_thread.md84
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