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/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 ++++++++++++++++ 6 files changed, 151 insertions(+), 12 deletions(-) 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/reference') 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