From c5afb3b3c70c026e8f72674ff6973581055658e7 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Wed, 27 Mar 2024 07:53:26 -0700 Subject: Add nng_mtx_* functions. --- 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/reference/src/SUMMARY.md | 4 ++ docs/reference/src/api/msg/index.md | 25 ++++----- docs/reference/src/api/threads/nng_mtx_alloc.md | 44 ++++++++++++++++ docs/reference/src/api/threads/nng_mtx_free.md | 23 +++++++++ docs/reference/src/api/threads/nng_mtx_lock.md | 38 ++++++++++++++ docs/reference/src/api/threads/nng_mtx_unlock.md | 29 +++++++++++ 10 files changed, 151 insertions(+), 226 deletions(-) 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 create mode 100644 docs/reference/src/api/threads/nng_mtx_alloc.md create mode 100644 docs/reference/src/api/threads/nng_mtx_free.md create mode 100644 docs/reference/src/api/threads/nng_mtx_lock.md create mode 100644 docs/reference/src/api/threads/nng_mtx_unlock.md (limited to 'docs') 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/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md index 0a99d045..98d70ad7 100644 --- a/docs/reference/src/SUMMARY.md +++ b/docs/reference/src/SUMMARY.md @@ -111,6 +111,10 @@ - [nng_cv_wait](api/threads/nng_cv_wait.md) - [nng_cv_wake](api/threads/nng_cv_wake.md) - [nng_cv_wake1](api/threads/nng_cv_wake1.md) + - [nng_mtx_alloc](api/threads/nng_mtx_alloc.md) + - [nng_mtx_free](api/threads/nng_mtx_free.md) + - [nng_mtx_lock](api/threads/nng_mtx_lock.md) + - [nng_mtx_unlock](api/threads/nng_mtx_unlock.md) - [Legacy Compatibility](api/compat/index.md) diff --git a/docs/reference/src/api/msg/index.md b/docs/reference/src/api/msg/index.md index 1a7bdabf..54d8d9b8 100644 --- a/docs/reference/src/api/msg/index.md +++ b/docs/reference/src/api/msg/index.md @@ -48,25 +48,26 @@ that would affect the binary representation of the `nng_msg` itself. ### Example 1: Preparing a message for use ```c -#include -nng_msg *m; -if (nng_msg_alloc(&m, strlen("content") + 1) != 0) { - // handle error -} -strcpy(nng_msg_body(m), "content"); + #include + + nng_msg *m; + if (nng_msg_alloc(&m, strlen("content") + 1) != 0) { + // handle error + } + strcpy(nng_msg_body(m), "content"); ``` ### Example 2: Preallocating message content ```c -if (nng_msg_alloc(&m, 1024) != 0) { - // handle error -} -while ((val64 = next_datum()) != 0) P - if (nng_msg_append_u64(m, val64) != 0) { + if (nng_msg_alloc(&m, 1024) != 0) { // handle error } -} + while ((val64 = next_datum()) != 0) P + if (nng_msg_append_u64(m, val64) != 0) { + // handle error + } + } ``` ## See Also diff --git a/docs/reference/src/api/threads/nng_mtx_alloc.md b/docs/reference/src/api/threads/nng_mtx_alloc.md new file mode 100644 index 00000000..64263d59 --- /dev/null +++ b/docs/reference/src/api/threads/nng_mtx_alloc.md @@ -0,0 +1,44 @@ +# nng_mtx_alloc + +## NAME + +nng_mtx_alloc - allocate mutex + +## SYNOPSIS + +```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 + +- `NNG_ENOMEM`: Insufficient free memory exists. + +## SEE ALSO + +[nng_cv_alloc](nng_cv_alloc.md), +[nng_mtx_free](nng_mtx_free.md), +[nng_mtx_lock](nng_mtx_lock.md), +[nng_mtx_unlock](nng_mtx_unlock.md) diff --git a/docs/reference/src/api/threads/nng_mtx_free.md b/docs/reference/src/api/threads/nng_mtx_free.md new file mode 100644 index 00000000..a6fe7d7b --- /dev/null +++ b/docs/reference/src/api/threads/nng_mtx_free.md @@ -0,0 +1,23 @@ +# nng_mtx_free + +## NAME + +nng_mtx_free --- free mutex + +## SYNOPSIS + +```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. + +## SEE ALSO + +[nng_mtx_alloc](nng_mtx_alloc) diff --git a/docs/reference/src/api/threads/nng_mtx_lock.md b/docs/reference/src/api/threads/nng_mtx_lock.md new file mode 100644 index 00000000..2e50f010 --- /dev/null +++ b/docs/reference/src/api/threads/nng_mtx_lock.md @@ -0,0 +1,38 @@ +# nng_mtx_lock + +## NAME + +nng_mtx_lock --- lock mutex + +## SYNOPSIS + +```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 [`nng_mtx_unlock()`](nng_mtx_unlock.md). + +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. + +> [!NOTE] +> 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. + +## SEE ALSO + +[nng_cv_alloc](nng_cv_alloc.md), +[nng_mtx_alloc](nng_mtx_alloc.md), +[nng_mtx_unlock](nng_mtx_unlock.md) diff --git a/docs/reference/src/api/threads/nng_mtx_unlock.md b/docs/reference/src/api/threads/nng_mtx_unlock.md new file mode 100644 index 00000000..d5815287 --- /dev/null +++ b/docs/reference/src/api/threads/nng_mtx_unlock.md @@ -0,0 +1,29 @@ +# nng_mtx_unlock(3supp) + +## NAME + +nng_mtx_unlock --- unlock mutex + +## SYNOPSIS + +```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 [`nng_mtx_lock()`](nng_mtx_lock.md). + +> [!NOTE] +> 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. + +## SEE ALSO + +[nng_mtx_alloc](nng_mtx_alloc), +[nng_mtx_lock](nng_mtx_lock) -- cgit v1.2.3-70-g09d2