From 4d178a9eb65b973d18c80afa328a070ee09fd768 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Fri, 5 Apr 2024 08:07:57 -0700 Subject: Refactor thread related pages. --- docs/man/nng_cv_alloc.3supp.adoc | 60 ---------------------- docs/man/nng_cv_free.3supp.adoc | 42 --------------- docs/man/nng_cv_until.3supp.adoc | 91 --------------------------------- docs/man/nng_cv_wait.3supp.adoc | 86 ------------------------------- docs/man/nng_cv_wake.3supp.adoc | 61 ---------------------- docs/man/nng_cv_wake1.3supp.adoc | 61 ---------------------- docs/man/nng_mtx_alloc.3supp.adoc | 58 --------------------- docs/man/nng_mtx_free.3supp.adoc | 43 ---------------- docs/man/nng_mtx_lock.3supp.adoc | 65 ----------------------- docs/man/nng_mtx_unlock.3supp.adoc | 48 ----------------- docs/man/nng_thread_create.3supp.adoc | 87 ------------------------------- docs/man/nng_thread_destroy.3supp.adoc | 47 ----------------- docs/man/nng_thread_set_name.3supp.adoc | 48 ----------------- 13 files changed, 797 deletions(-) delete mode 100644 docs/man/nng_cv_alloc.3supp.adoc delete mode 100644 docs/man/nng_cv_free.3supp.adoc delete mode 100644 docs/man/nng_cv_until.3supp.adoc delete mode 100644 docs/man/nng_cv_wait.3supp.adoc delete mode 100644 docs/man/nng_cv_wake.3supp.adoc delete mode 100644 docs/man/nng_cv_wake1.3supp.adoc delete mode 100644 docs/man/nng_mtx_alloc.3supp.adoc delete mode 100644 docs/man/nng_mtx_free.3supp.adoc delete mode 100644 docs/man/nng_mtx_lock.3supp.adoc delete mode 100644 docs/man/nng_mtx_unlock.3supp.adoc delete mode 100644 docs/man/nng_thread_create.3supp.adoc delete mode 100644 docs/man/nng_thread_destroy.3supp.adoc delete mode 100644 docs/man/nng_thread_set_name.3supp.adoc (limited to 'docs/man') diff --git a/docs/man/nng_cv_alloc.3supp.adoc b/docs/man/nng_cv_alloc.3supp.adoc deleted file mode 100644 index 9e58e3f1..00000000 --- a/docs/man/nng_cv_alloc.3supp.adoc +++ /dev/null @@ -1,60 +0,0 @@ -= nng_cv_alloc(3supp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_cv_alloc - allocate condition variable - -== SYNOPSIS - -[source, c] ----- -#include -#include - -typedef struct nng_cv nng_cv; - -int nng_cv_alloc(nng_cv **cvp, nng_mtx *mtx); ----- - -== DESCRIPTION - -The `nng_cv_alloc()` function allocates a condition variable, using -the mutex _mtx_, and returns it in _cvp_. - -Every condition variable is associated with a mutex, which must be -owned when a thread waits for the condition using -xref:nng_cv_wait.3supp.adoc[`nng_cv_wait()`] or -xref:nng_cv_until.3supp.adoc[`nng_cv_until()`]. -The mutex must also be owned when signaling the condition using the -xref:nng_cv_wake.3supp.adoc[`nng_cv_wake()`] or -xref:nng_cv_wake1.3supp.adoc[`nng_cv_wake1()`] functions. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists. - -== SEE ALSO - -[.text-left] -xref:nng_cv_free.3supp.adoc[nng_cv_free(3supp)], -xref:nng_cv_until.3supp.adoc[nng_cv_until(3supp)], -xref:nng_cv_wait.3supp.adoc[nng_cv_wait(3supp)], -xref:nng_cv_wake.3supp.adoc[nng_cv_wake(3supp)], -xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1(3supp)], -xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_cv_free.3supp.adoc b/docs/man/nng_cv_free.3supp.adoc deleted file mode 100644 index 0610b52f..00000000 --- a/docs/man/nng_cv_free.3supp.adoc +++ /dev/null @@ -1,42 +0,0 @@ -= nng_cv_free(3supp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_cv_free - free condition variable - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_cv_free(nng_cv *cv); ----- - -== DESCRIPTION - -The `nng_cv_free()` function frees the condition variable _cv_. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_cv_until.3supp.adoc b/docs/man/nng_cv_until.3supp.adoc deleted file mode 100644 index 9cf7c714..00000000 --- a/docs/man/nng_cv_until.3supp.adoc +++ /dev/null @@ -1,91 +0,0 @@ -= nng_cv_until(3supp) -// -// Copyright 2021 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_cv_until - wait for condition or timeout - -== SYNOPSIS - -[source, c] ----- -#include -#include - -int nng_cv_until(nng_cv *cv, nng_time when); ----- - -== DESCRIPTION - -The `nng_cv_until()` waits until either the condition variable _cv_ is signaled -by another thread calling either xref:nng_cv_wake.3supp.adoc[`nng_cv_wake()`] or -xref:nng_cv_wake1.3supp.adoc[`nng_cv_wake1()`], or the system clock (as tracked -by xref:nng_clock.3supp.adoc[`nng_clock()`]) reaches _when_. - -The caller must have have ownership of the mutex that was used when -_cv_ was allocated. -This function will drop the ownership of that mutex, and reacquire it -atomically just before returning to the caller. -(The waiting is done without holding the mutex.) - -NOTE: Any condition may be used or checked, but the condition must be -checked, as it is possible for this function to wake up spuriously. -The best way to do this is inside a loop that repeats until the condition -tests for true. - -== EXAMPLE - -The following example demonstrates use of this function: - -.Example 1: Waiting for the condition -[source, c] ----- - - expire = nng_clock() + 1000; // 1 second in the future - nng_mtx_lock(m); // assume cv was allocated using m - while (!condition_true) { - if (nng_cv_until(cv, expire) == NNG_ETIMEDOUT) { - printf("Time out reached!\n"); - break; - } - } - // condition_true is true - nng_mtx_unlock(m); ----- - -.Example 2: Signaling the condition -[source, c] ----- - nng_mtx_lock(m); - condition_true = true; - nng_cv_wake(cv); - nng_mtx_unlock(m); ----- - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], -xref:nng_cv_wait.3supp.adoc[nng_cv_wait(3supp)], -xref:nng_cv_wake.3supp.adoc[nng_cv_wake(3supp)], -xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1(3supp)], -xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], -xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)], -xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_cv_wait.3supp.adoc b/docs/man/nng_cv_wait.3supp.adoc deleted file mode 100644 index 1d9c16be..00000000 --- a/docs/man/nng_cv_wait.3supp.adoc +++ /dev/null @@ -1,86 +0,0 @@ -= nng_cv_wait(3supp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_cv_wait - wait for condition - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_cv_wait(nng_cv *cv); ----- - -== DESCRIPTION - -The `nng_cv_wait()` waits for the condition variable _cv_ to be signaled -by another thread calling either xref:nng_cv_wake.3supp.adoc[`nng_cv_wake()`] or -xref:nng_cv_wake1.3supp.adoc[`nng_cv_wake1()`]. - -The caller must have have ownership of the mutex that was used when -_cv_ was allocated. -This function will drop the ownership of that mutex, and reacquire it -atomically just before returning to the caller. -(The waiting is done without holding the mutex.) - -NOTE: Any condition may be used or checked, but the condition must be -checked, as it is possible for this function to wake up spuriously. -The best way to do this is inside a loop that repeats until the condition -tests for true. - -== EXAMPLE - -The following example demonstrates use of this function: - -.Example 1: Waiting for the condition -[source, c] ----- - - nng_mtx_lock(m); // assume cv was allocated using m - while (!condition_true) { - nng_cv_wait(cv); - } - // condition_true is true - nng_mtx_unlock(m); ----- - -.Example 2: Signaling the condition -[source, c] ----- - nng_mtx_lock(m); - condition_true = true; - nng_cv_wake(cv); - nng_mtx_unlock(m); ----- - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], -xref:nng_cv_until.3supp.adoc[nng_cv_until(3supp)], -xref:nng_cv_wake.3supp.adoc[nng_cv_wake(3supp)], -xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1(3supp)], -xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], -xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)], -xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_cv_wake.3supp.adoc b/docs/man/nng_cv_wake.3supp.adoc deleted file mode 100644 index 6ee2945d..00000000 --- a/docs/man/nng_cv_wake.3supp.adoc +++ /dev/null @@ -1,61 +0,0 @@ -= nng_cv_wake(3supp) -// -// Copyright 2020 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_cv_wake - wake all waiters - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_cv_wake(nng_cv *cv); ----- - -== DESCRIPTION - -The `nng_cv_wake()` wakes any threads waiting for the condition variable _cv_ -to be signaled in the xref:nng_cv_wait.3supp.adoc[`nng_cv_wait()`] or -xref:nng_cv_until.3supp.adoc[`nng_cv_until()`] functions. - -The caller must have have ownership of the mutex that was used when -_cv_ was allocated. - -NOTE: The caller should already have set the condition that the waiters -will check, while holding the mutex. - -TIP: This function wakes all threads, which is generally safer but can -lead to a performance problem when there are many waiters, as they are all -woken simultaneously and may contend for resources. -See xref:nng_cv_wake1.3supp.adoc[`nng_cv_wake1()`] for a solution to this problem. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], -xref:nng_cv_until.3supp.adoc[nng_cv_until(3supp)], -xref:nng_cv_wait.3supp.adoc[nng_cv_wait(3supp)], -xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1(3supp)], -xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], -xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)], -xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_cv_wake1.3supp.adoc b/docs/man/nng_cv_wake1.3supp.adoc deleted file mode 100644 index 4f8b8326..00000000 --- a/docs/man/nng_cv_wake1.3supp.adoc +++ /dev/null @@ -1,61 +0,0 @@ -= nng_cv_wake1(3supp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_cv_wake1 - wake one waiter - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_cv_wake1(nng_cv *cv); ----- - -== DESCRIPTION - -The `nng_cv_wake1()` wakes at most one thread waiting for the condition -variable _cv_ -to be signaled in the xref:nng_cv_wait.3supp.adoc[`nng_cv_wait()`] or -xref:nng_cv_until.3supp.adoc[`nng_cv_until()`] functions. - -The caller must have have ownership of the mutex that was used when -_cv_ was allocated. - -NOTE: The caller should already have set the condition that the waiters -will check, while holding the mutex. - -NOTE: The caller cannot predict which waiter will be woken, and so the design must -ensure that it is sufficient that _any_ waiter be woken. -When in doubt, it is safer to use xref:nng_cv_wake.3supp.adoc[`nng_cv_wake()`]. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], -xref:nng_cv_until.3supp.adoc[nng_cv_until(3supp)], -xref:nng_cv_wait.3supp.adoc[nng_cv_wait(3supp)], -xref:nng_cv_wake.3supp.adoc[nng_cv_wake(3supp)], -xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], -xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)], -xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_mtx_alloc.3supp.adoc b/docs/man/nng_mtx_alloc.3supp.adoc deleted file mode 100644 index 45bbfac2..00000000 --- a/docs/man/nng_mtx_alloc.3supp.adoc +++ /dev/null @@ -1,58 +0,0 @@ -= nng_mtx_alloc(3supp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_mtx_alloc - allocate mutex - -== SYNOPSIS - -[source, c] ----- -#include -#include - -typedef struct nng_mtx nng_mtx; - -int nng_mtx_alloc(nng_mtx **mtxp); ----- - -== DESCRIPTION - -The `nng_mtx_alloc()` function allocates mutex and returns it in _mtxp_. - -The mutex objects created by this function are suitable only for -simple lock and unlock operations, and are not recursive. -Every effort has been made to use light-weight underlying primitives when available. - -Mutex (mutual exclusion) objects can be thought of as binary semaphores, -where only a single thread of execution is permitted to acquire the semaphore. - -Furthermore, a mutex can only be unlocked by the thread that locked it. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists. - -== SEE ALSO - -[.text-left] -xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], -xref:nng_mtx_free.3supp.adoc[nng_mtx_free(3supp)], -xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)], -xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_mtx_free.3supp.adoc b/docs/man/nng_mtx_free.3supp.adoc deleted file mode 100644 index 2867afe1..00000000 --- a/docs/man/nng_mtx_free.3supp.adoc +++ /dev/null @@ -1,43 +0,0 @@ -= nng_mtx_free(3supp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_mtx_free - free mutex - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_mtx_free(nng_mtx *mtx); ----- - -== DESCRIPTION - -The `nng_mtx_free()` function frees the mutex _mtx_. -The mutex must not be locked when this function is called. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_mtx_lock.3supp.adoc b/docs/man/nng_mtx_lock.3supp.adoc deleted file mode 100644 index 91fd2ab5..00000000 --- a/docs/man/nng_mtx_lock.3supp.adoc +++ /dev/null @@ -1,65 +0,0 @@ -= nng_mtx_lock(3supp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_mtx_lock - lock mutex - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_mtx_lock(nng_mtx *mtx); ----- - -== DESCRIPTION - -The `nng_mtx_lock()` acquires exclusive ownership of the mutex _mtx_. -If the lock is already owned, this function will wait until the current -owner releases it with xref:nng_mtx_unlock.3supp.adoc[`nng_mtx_unlock()`]. - -If multiple threads are waiting for the lock, the order of acquisition -is not specified. - -NOTE: A mutex can _only_ be unlocked by the thread that locked it. - -IMPORTANT: Mutex locks are _not_ recursive; attempts to reacquire the -same mutex may result in deadlock or aborting the current program. -It is a programming error for the owner of a mutex to attempt to -reacquire it. - -**** -_NNG_ offers neither a non-blocking variant that can fail, -nor recursive mutexes. -This is by design, as _NNG_ itself does not use such things, -and most often the need for them is the result of poor design. -If such capabilities are needed, they may be synthesized fairly -easily from mutexes and condition variables. -**** - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], -xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], -xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock(3supp)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_mtx_unlock.3supp.adoc b/docs/man/nng_mtx_unlock.3supp.adoc deleted file mode 100644 index d1b048e6..00000000 --- a/docs/man/nng_mtx_unlock.3supp.adoc +++ /dev/null @@ -1,48 +0,0 @@ -= nng_mtx_unlock(3supp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_mtx_unlock - unlock mutex - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_mtx_unlock(nng_mtx *mtx); ----- - -== DESCRIPTION - -The `nng_mtx_unlock()` relinquishes ownership of the mutex _mtx_ that -was previously acquired via xref:nng_mtx_lock.3supp.adoc[`nng_mtx_lock()`]. - -IMPORTANT: A mutex can _only_ be unlocked by the thread that locked it. -Attempting to unlock a mutex that is not owned by the caller will result -in undefined behavior. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], -xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock(3supp)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_thread_create.3supp.adoc b/docs/man/nng_thread_create.3supp.adoc deleted file mode 100644 index 129bddea..00000000 --- a/docs/man/nng_thread_create.3supp.adoc +++ /dev/null @@ -1,87 +0,0 @@ -= nng_thread_create(3supp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_thread_create - create thread - -== SYNOPSIS - -[source, c] ----- -#include -#include - -typedef struct nng_thread nng_thread; - -int nng_thread_create(nng_thread **thrp, void (*func)(void *), void *arg); ----- - -== DESCRIPTION - -The `nng_thread_create()` function creates a single thread of execution, -running _func_ with the argument _arg_. -The thread is started immediately. -A pointer to the thread object is returned in _thrp_. - -The intention of this program is to facilitate writing parallel programs. -Threads created by this program will be based upon the underlying -threading mechanism of the system that _NNG_ is running on. -This may include use of coroutines. - -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 -xref:nng_thread_destroy.3supp.adoc[`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 xref:nng_aio.5.adoc[`nng_aio`] structures. - -TIP: Threads can be synchronized using -xref:nng_mtx_alloc.3supp.adoc[mutexes] and -xref:nng_cv_alloc.3supp.adoc[condition variables]. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient free memory exists. - -== SEE ALSO - -[.text-left] -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_cv_alloc.3supp.adoc[nng_cv_alloc(3supp)], -xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc(3supp)], -xref:nng_thread_destroy.3supp.adoc[nng_thread_destroy(3supp)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_thread_destroy.3supp.adoc b/docs/man/nng_thread_destroy.3supp.adoc deleted file mode 100644 index 95eed813..00000000 --- a/docs/man/nng_thread_destroy.3supp.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nng_thread_destroy(3supp) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_thread_destroy - reap thread - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_thread_destroy(nng_thread *thread); ----- - -== DESCRIPTION - -The `nng_thread_destroy()` function reaps the _thread_. -It waits for the thread function to return, and then deallocates -the resources for the thread. - -IMPORTANT: Do not call this function from the thread function itself, -or a deadlock will occur. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_thread_create.3supp.adoc[nng_thread_create(3supp)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_thread_set_name.3supp.adoc b/docs/man/nng_thread_set_name.3supp.adoc deleted file mode 100644 index 36dd8267..00000000 --- a/docs/man/nng_thread_set_name.3supp.adoc +++ /dev/null @@ -1,48 +0,0 @@ -= nng_thread_set_name(3supp) -// -// Copyright 2020 Staysail Systems, Inc. -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_thread_set_name - set thread name - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_thread_set_name(nng_thread *thread, const char *name); ----- - -== DESCRIPTION - -The `nng_thread_set_name()` function attempts to set the name for the _thread_ to _name_. - -If _thread_ is `NULL`, then the name is set for the current thread. - -Support for this, and how names are exposed, varies between platform implementations. -This function is intended to facilitate debugging applications that may have many threads. - -TIP: Internal threads created by _NNG_ will have names beginning with `nng:`. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_thread_create.3supp.adoc[nng_thread_create(3supp)], -xref:nng.7.adoc[nng(7)] -- cgit v1.2.3-70-g09d2