diff options
| -rw-r--r-- | docs/man/libnng.3.adoc | 10 | ||||
| -rw-r--r-- | docs/man/nng_id_map.3supp.adoc | 108 | ||||
| -rw-r--r-- | docs/man/nng_mtx_alloc.3supp.adoc | 57 | ||||
| -rw-r--r-- | docs/man/nng_mtx_free.3supp.adoc | 42 | ||||
| -rw-r--r-- | docs/man/nng_mtx_lock.3supp.adoc | 55 | ||||
| -rw-r--r-- | docs/man/nng_mtx_unlock.3supp.adoc | 47 |
6 files changed, 5 insertions, 314 deletions
diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 8b893cae..89546f48 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -286,12 +286,12 @@ as a convenience to aid in creating portable applications. |xref:nng_cv_wait.3supp.adoc[nng_cv_wait()]|wait for condition |xref:nng_cv_wake.3supp.adoc[nng_cv_wake()]|wake all waiters |xref:nng_cv_wake1.3supp.adoc[nng_cv_wake1()]|wake one waiter -|xref:nng_id_map.3supp.adoc[nng_id_map]|identifier based mapping table +// |xref:nng_id_map.3supp.adoc[nng_id_map]|identifier based mapping table |xref:nng_msleep.3supp.adoc[nng_msleep()]|sleep for milliseconds -|xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc()]|allocate mutex -|xref:nng_mtx_free.3supp.adoc[nng_mtx_free()]|free mutex -|xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock()]|lock mutex -|xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock()]|unlock mutex +// |xref:nng_mtx_alloc.3supp.adoc[nng_mtx_alloc()]|allocate mutex +// |xref:nng_mtx_free.3supp.adoc[nng_mtx_free()]|free mutex +// |xref:nng_mtx_lock.3supp.adoc[nng_mtx_lock()]|lock mutex +// |xref:nng_mtx_unlock.3supp.adoc[nng_mtx_unlock()]|unlock mutex |xref:nng_opts_parse.3supp.adoc[nng_opts_parse()]|parse command line options |xref:nng_random.3supp.adoc[nng_random()]|get random number |xref:nng_socket_pair.3supp.adoc[nng_socket_pair()]|create connected pair of BSD sockets diff --git a/docs/man/nng_id_map.3supp.adoc b/docs/man/nng_id_map.3supp.adoc deleted file mode 100644 index 5bebf1c4..00000000 --- a/docs/man/nng_id_map.3supp.adoc +++ /dev/null @@ -1,108 +0,0 @@ -= nng_id_map(3supp) -// -// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech> -// -// 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_id_map - identifier based mapping table - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> -#include <nng/supplemental/util/idhash.h> - -typedef struct nng_id_map_s nng_id_map; - -#define NNG_MAP_RANDOM 1 - -int nng_id_map_alloc(nng_id_map **map_p, uint64_t lo, uint64_t hi, int flags); -void nng_id_map_free(nng_id_map *map); -void *nng_id_get(nng_id_map *map, uint64_t id); -int nng_id_set(nng_id_map *map, uint64_t, void *value); -int nng_id_alloc(nng_id_map *map, uint64_t *id_p, void *value); -int nng_id_remove(nng_id_map *map, uint64_t id); -bool nng_id_visit(nng_id_map *map, uint64_t *id_p, void **value_p, uint32_t *cursor); - ----- - -== DESCRIPTION - -These functions provide support for managing tables of data based on -identifiers, ensuring that identifiers are allocated uniquely and within -specified range limits. - -The table stores data pointers (which must not be `NULL`) at a logical numeric index. -It does so efficiently, even if large gaps exist, and it provides a means to efficiently -allocate a numeric identifier from a pool of unused identifiers. - -Identifiers are allocated in increasing order, without reusing old identifiers until the -largest possible identifier is allocated. After wrapping, only identifiers that are no longer -in use will be considered. -No effort to order the availability of identifiers based on when they were freed is made. - -An initial table is allocated with `nng_id_map_alloc()`, which takes the lowest legal identifier in _lo_, -and the largest legal identifier in _hi_. -The new table is returned in _map_p_, and should be used as the _map_ argument to the rest of these functions. - -**** -As a special convenience, if these are specified as zero, then a full range of 32-bit identifiers is assumed. -If identifiers larger than or equal to 2^32^ are required, then both _lo_ and _hi_ must be specified with the -exact values desired. -**** - -The _flags_ argument is a bit mask of flags for the table. -If `NNG_MAP_RANDOM` is specified, then the starting point for allocations is randomized, but subsequent allocations will then be monotonically increasing. -This is useful to reduce the odds of different instances of an application using the same identifiers at the same time. - -The `nng_id_get()` function returns the value previously stored with the given identifier. -If no value is currently associated with the identifer, it returns `NULL`. - -The `nng_id_set()` function sets the value with the associated identifier. -This can be used to replace a previously allocated identifier. -If the identifier was not previously allocated, then it is allocated as part of the call. -This function does not necessarily honor the identifier range limits set for the map when it was allocated. - -The `nng_id_alloc()` function allocates a new identifier from the range for the map, and associates it with -the supplied _value_. - -The `nng_id_remove()` function removes the identifier and its associated value from the table. - -The `nng_id_visit()` function is used to iterate over all items in the table. -The caller starts the iteration by setting the _cursor_ to 0 before calling it. -For each call, the associated key and value of the next item will be returned in __id_p__, and __value_p__ and the _cursor_ will be updated. -When all items have been iterated, the function returns `false`. -The order of items returned is not guaranteed to be sequential. -The caller must not attempt to derive any value of the _cursor_ as it refers to internal table indices. - -NOTE: These functions are limited to storing at most 2^32^ identifiers, even though the identifers may -themselves be larger than 2^32^. - -IMPORTANT: These functions are *not* thread-safe. -Callers should use a xref:nng_mtx_lock.3supp[mutex] or similar approach when thread-safety is needed. - -== RETURN VALUES - -The `nng_id_map_alloc()`, `nng_id_set()`, `nng_id_alloc()`, and `nng_id_remove()` functions -return 0 on success, or -1 on failure. - -The `nng_id_map_get()` function returns the requested data pointer, or `NULL` if the identifier was not found. - -== ERRORS - -[horizontal] -`NNG_ENOENT`:: The _id_ does not exist in the table. -`NNG_ENOMEM`:: Insufficient memory is available, or the table is full. - -== SEE ALSO - -[.text-left] -xref:nng_mtx_lock.3supp.adoc[nng(7)] -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 68ce691b..00000000 --- a/docs/man/nng_mtx_alloc.3supp.adoc +++ /dev/null @@ -1,57 +0,0 @@ -= nng_mtx_alloc(3supp) -// -// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// 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 <nng/nng.h> - -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 f247cbf9..00000000 --- a/docs/man/nng_mtx_free.3supp.adoc +++ /dev/null @@ -1,42 +0,0 @@ -= nng_mtx_free(3supp) -// -// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// 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 <nng/nng.h> - -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 5f4276fc..00000000 --- a/docs/man/nng_mtx_lock.3supp.adoc +++ /dev/null @@ -1,55 +0,0 @@ -= nng_mtx_lock(3supp) -// -// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// 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 <nng/nng.h> - -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. - -== 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 1752fcf7..00000000 --- a/docs/man/nng_mtx_unlock.3supp.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nng_mtx_unlock(3supp) -// -// Copyright 2024 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// 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 <nng/nng.h> - -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)] |