From 874f04fdaccf30c296bcde7e9f87bf8d8ba3f7c6 Mon Sep 17 00:00:00 2001
From: Garrett D'Amore
nng_alloc(), -nng_clock(), -nng_free(), -nng_random(), -nng_version()
+nng_alloc, +nng_clock, +nng_free, +nng_random, +nng_version
+ + + + + + + + + + + + + +nng_alloc — allocate memory
+#include <nng/nng.h>
+
+void *nng_alloc(size_t size);
+
+The nng_alloc() function allocates a contiguous memory region of
+at least size bytes.
+The memory will be 64-bit aligned.
The returned memory can be used to hold message buffers, in which
+case it can be directly passed to nng_send() using
+the flag NNG_FLAG_ALLOC. Alternatively, it can be freed when no
+longer needed using nng_free().
+ + important +
+Do not use the system free() function (or the C++ delete operator) to release this memory.
+On some configurations this may work, but on others it will lead to a crash or
+other unpredictable behavior.
This function returns a pointer to the allocated memory on success,
+and NULL otherwise.
No errors are returned, but if memory cannot be allocated then NULL
+is returned.
nng_clock - get time
+#include <nng/nng.h>
+#include <nng/supplemental/util/platform.h>
+
+typedef uint64_t nng_time;
+
+nng_time nng_clock(void);
+
+The nng_clock() function returns the number of elapsed milliseconds since some
+arbitrary time in the past.
+The resolution of the clock depends on the underlying timing facilities
+of the system.
+This function may be used for timing, but applications should not expect
+very fine-grained values.
+ + note +
+The reference time will be the same for a given program, +but different programs may have different references.
+This function is intended to help with setting appropriate
+timeouts using nng_cv_until()
+or nng_aio_set_expire().
Milliseconds since reference time.
+nng_sleep_aio, +nng_cv_until, +nng_msleep, +nng_duration
+ + + + + + + + + + + + -nng_alloc — allocate memory
-nng_free — free memory
+#include <nng/nng.h>
-void *nng_alloc(size_t size);
+void nng_free(void *ptr, size_t size);
-The nng_alloc() function allocates a contiguous memory region of
-at least size bytes.
-The memory will be 64-bit aligned.
The returned memory can be used to hold message buffers, in which
-case it can be directly passed to nng_send() using
-the flag NNG_FLAG_ALLOC. Alternatively, it can be freed when no
-longer needed using nng_free().
The nng_free() function deallocates a memory region of size size,
+that was previously allocated by nng_alloc() or
+nng_recv() with the NNG_FLAG_ALLOC flag.
important
-Do not use the system free() function (or the C++ delete operator) to release this memory.
-On some configurations this may work, but on others it will lead to a crash or
-other unpredictable behavior.
It is very important that size match the allocation size +used to allocate the memory.
This function returns a pointer to the allocated memory on success,
-and NULL otherwise.
No errors are returned, but if memory cannot be allocated then NULL
-is returned.
+ + important +
+Do not attempt to use this function to deallocate memory
+obtained by a call to the system malloc() or calloc() functions,
+or the C++ new operator.
+Doing so may result in unpredictable
+behavior, including corruption of application memory.
nng_clock - get time
-nng_id_map — identifier based mapping table
+#include <nng/nng.h>
-#include <nng/supplemental/util/platform.h>
+#include <nng/supplemental/util/idhash.h>
-typedef uint64_t nng_time;
+typedef struct nng_id_map_s nng_id_map;
-nng_time nng_clock(void);
+#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);
-The nng_clock() function returns the number of elapsed milliseconds since some
-arbitrary time in the past.
-The resolution of the clock depends on the underlying timing facilities
-of the system.
-This function may be used for timing, but applications should not expect
-very fine-grained values.
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 is made to order the availability of identifiers based on when they were freed.1
+The concern about possibly reusing a recently released identifier +comes into consideration after the range has wrapped. Given a sufficiently +large range, this is unlikely to be a concern.
+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.
If these lo and hi are both zero, then a full range of 32-bit identifiers is assumed.2
+Consequently, if identifiers larger than or equal to 232 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.
note
-The reference time will be the same for a given program, -but different programs may have different references.
+These functions are limited to storing at most 232 used identifiers, even though the identifers may +themselves be larger than 232.
This function is intended to help with setting appropriate
-timeouts using nng_cv_until()
-or nng_aio_set_expire().
Milliseconds since reference time.
-nng_sleep_aio, -nng_cv_until, -nng_msleep, -nng_duration
++ + note +
+These functions are not thread-safe. +Callers should use a [mutex][mutex] or similar approach when thread-safety is needed.
+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.
NNG_ENOENT: The id does not exist in the table.NNG_ENOMEM: Insufficient memory is available, or the table is full.nng_free — free memory
-nng_msleep — sleep milliseconds
+#include <nng/nng.h>
+#include <nng/supplemental/util/platform.h>
-void nng_free(void *ptr, size_t size);
+void nng_msleep(nng_duration msec);
-The nng_free() function deallocates a memory region of size size,
-that was previously allocated by nng_alloc() or
-nng_recv() with the NNG_FLAG_ALLOC flag.
- - important -
-It is very important that size match the allocation size -used to allocate the memory.
-The nng_msleep() blocks the caller for at least msec milliseconds.
- important + note
-Do not attempt to use this function to deallocate memory
-obtained by a call to the system malloc() or calloc() functions,
-or the C++ new operator.
-Doing so may result in unpredictable
-behavior, including corruption of application memory.
This function may block for longer than requested. +The actual wait time is determined by the capabilities of the +underlying system.
nng_msleep — sleep milliseconds
-nng_random — get random number
+#include <nng/nng.h>
#include <nng/supplemental/util/platform.h>
-void nng_msleep(nng_duration msec);
+uint32_t nng_random(void);
-The nng_msleep() blocks the caller for at least msec milliseconds.
- - note -
-This function may block for longer than requested. -The actual wait time is determined by the capabilities of the -underlying system.
-The nng_random() returns a random number.
+The value returned is suitable for use with cryptographic functions such as
+key generation.
+The value is obtained using platform-specific cryptographically strong random
+number facilities when available.
Returns a random 32-bit value.
+ + + + + + + + + + + + -nng_random — get random number
-nng_sleep_aio - sleep asynchronously
+#include <nng/nng.h>
-#include <nng/supplemental/util/platform.h>
-uint32_t nng_random(void);
+void nng_sleep_aio(nng_duration msec, nng_aio *aio);
-The nng_random() returns a random number.
-The value returned is suitable for use with cryptographic functions such as
-key generation.
-The value is obtained using platform-specific cryptographically strong random
-number facilities when available.
Returns a random 32-bit value.
+The nng_sleep_aio() function provides an asynchronous delay mechanism,
+causing the callback for aio to be executed after msec milliseconds.
+If the sleep finishes completely, the result will always be zero.
+ + note +
+If a timeout is set on aio using
+nng_aio_set_timeout(), and it is shorter
+than msec,
+then the sleep will wake up early, with a result code of NNG_ETIMEDOUT.
nng_clock, +nng_msleep, +Asynchronous I/O
+ + + + + + + + + + + + -nng_sleep_aio - sleep asynchronously
-nng_socket_pair — create a connected pair of BSD sockets
+#include <nng/nng.h>
+#include <nng/supplemental/util/platform.h>
-void nng_sleep_aio(nng_duration msec, nng_aio *aio);
+int nng_socket_pair(int fds[2]);
-The nng_sleep_aio() function provides an asynchronous delay mechanism,
-causing the callback for aio to be executed after msec milliseconds.
-If the sleep finishes completely, the result will always be zero.
The nng_socket_pair() function creates a pair of connected BSD sockets.
+These sockets, which are returned in the fds array, are suitable for
+use with the BSD Socket transport.
On POSIX platforms, this is a thin wrapper around the standard socketpair() function,
+using the AF_UNIX family and the SOCK_STREAM socket type.1
At present only POSIX platforms implementing socketpair() support this function.
- note + tip
-If a timeout is set on aio using
-nng_aio_set_timeout(), and it is shorter
-than msec,
-then the sleep will wake up early, with a result code of NNG_ETIMEDOUT.
This function may be useful for creating a shared connection between a parent process and +a child process on UNIX platforms, without requiring the processes use a shared filesystem or TCP connection.
nng_clock, -nng_msleep, -Asynchronous I/O
+This function returns 0 on success, and non-zero otherwise.
+NNG_ENOMEM: Insufficient memory exists.NNG_ENOTSUP: This platform does not support socket pairs.nng_strdup — duplicate string
-#include <nng/nng.h>
char *nng_strdup(const char *src);
-The nng_strdup() duplicates the string src and returns it.
This is logically equivalent to using nng_alloc()
+
This is logically equivalent to using nng_alloc()
to allocate a region of memory of strlen(s) + 1 bytes, and then
using strcpy() to copy the string into the destination before
returning it.
The returned string should be deallocated with
-nng_strfree(), or may be deallocated using the
-nng_free() using the length of the returned string plus
+nng_strfree(), or may be deallocated using the
+nng_free() using the length of the returned string plus
one (for the NUL terminating byte).
@@ -8537,15 +13006,27 @@ one (for the NUL terminating byte).
Do not use the system free() or similar functions to deallocate
the string, since those may use a different memory arena!
This function returns the new string on success, and NULL on failure.
No errors are returned, but a NULL return value should be
treated the same as NNG_ENOMEM.
nng_alloc.md, -nng_free.md, -nng_strfree.md
+nng_alloc.md, +nng_free.md, +nng_strfree.md
+ + + + + + + + + + + +nng_strerror — return an error description
-#include <nng/nng.h>
const char * nng_strerror(int err);
-The nng_strerror() returns the human-readable description of the
given error in err.
The returned error message is provided in US English, but in the @@ -8637,9 +13118,21 @@ Therefore applications must not depend on the message, but may use them verbatim when supplying information to end-users, such as in diagnostic messages or log entries.
This function returns the human-readable error message, terminated
by a NUL byte.
nng_strfree — free memory
-#include <nng/nng.h>
void nng_strfree(char *str);
-The nng_strfree() function deallocates the string str.
-This is equivalent to using nng_free() with
+This is equivalent to using nng_free() with
the length of str plus one (for the NUL terminating byte) as
the size.
This should only be used with strings that were allocated
-by nng_strdup() or nng_alloc().
+by nng_strdup() or nng_alloc().
In all cases, the allocation size of the string must be the same
as strlen(__str__) + 1.
strlen(__str__) + 1.
important
Consequently, if the a string created with
-nng_strdup() is modified to be shorter, then
+nng_strdup() is modified to be shorter, then
it is incorrect to call this function.
-(The nng_free() function can be used instead in that
+(The nng_free() function can be used instead in that
case, using the length of the original string plus one for the size.)
nng_alloc, -nng_free, -nng_strdup
+nng_alloc, +nng_free, +nng_strdup
+ + + + + + + + + + + +nng_version — report library version
-#include <nng/nng.h>
const char * nng_version(void);
-The nng_version() function returns a human readable version number
for NNG.
Additionally, compile time version information is available @@ -8836,8 +13341,20 @@ the version numbers reported refer to both the API and the library itself. (The ABI – application binary interface – between the library and the application is controlled in a similar, but different manner depending upon the link options and how the library is built.)
-NUL-terminated string containing the library version number.
nng_cv_alloc — allocate condition variable
-#include <nng/nng.h>
#include <nng/supplemental/util/platform.h>
@@ -8984,29 +13516,41 @@ typedef struct nng_cv nng_cv;
int nng_cv_alloc(nng_cv **cvp, nng_mtx *mtx);
-The nng_cv_alloc() function allocates a condition variable, using
+
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
-nng_cv_wait() or
-nng_cv_until().
+nng_cv_wait() or
+nng_cv_until().
The mutex must also be owned when signaling the condition using the
-nng_cv_wake() or
-nng_cv_wake1() functions.
nng_cv_wake() or
+nng_cv_wake1() functions.
+This function returns 0 on success, and non-zero otherwise.
-NNG_ENOMEM: Insufficient free memory exists.nng_cv_free, -nng_cv_until, -nng_cv_wait, -nng_cv_wake, -nng_cv_wake1, -nng_mtx_alloc
+nng_cv_free, +nng_cv_until, +nng_cv_wait, +nng_cv_wake, +nng_cv_wake1, +nng_mtx_alloc
+ + + + + + + + + + + +nng_cv_free — free condition variable
-#include <nng/nng.h>
#include <nng/supplemental/util/platform.h>
void nng_cv_free(nng_cv *cv);
-The nng_cv_free() function frees the condition variable cv.
nng_cv_until — wait for condition or timeout
-#include <nng/nng.h>
#include <nng/supplemental/util/platform.h>
int nng_cv_until(nng_cv *cv, nng_time when);
-The nng_cv_until() waits until either the condition variable cv is signaled
by another thread calling either
-nng_cv_wake() or
-nng_cv_wake1(), or the system clock (as tracked
-by nng_clock()) reaches when.
nng_cv_wake() or
+nng_cv_wake1(), or the system clock (as tracked
+by 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 @@ -9205,15 +13761,27 @@ tests for true.
nng_cv_wake(cv); nng_mtx_unlock(m); -nng_clock(), -nng_cv_alloc(), -nng_cv_wait(), -nng_cv_wake(), -nng_cv_wake1(), -nng_mtx_alloc(), -nng_mtx_lock(), -nng_mtx_unlock()
+nng_clock(), +nng_cv_alloc(), +nng_cv_wait(), +nng_cv_wake(), +nng_cv_wake1(), +nng_mtx_alloc(), +nng_mtx_lock(), +nng_mtx_unlock()
+ + + + + + + + + + + +nng_cv_wait — wait for condition
-#include <nng/nng.h>
#include <nng/supplemental/util/platform.h>
void nng_cv_wait(nng_cv *cv);
-The nng_cv_wait() waits for the condition variable cv to be signaled
-by another thread calling either nng_cv_wake() or
-nng_cv_wake1().
nng_cv_wake() or
+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 @@ -9326,14 +13894,26 @@ tests for true.
nng_cv_wake(cv); nng_mtx_unlock(m); -nng_cv_alloc, -nng_cv_until, -nng_cv_wake, -nng_cv_wake1, -nng_mtx_alloc, -nng_mtx_lock, -nng_mtx_unlock
+nng_cv_alloc, +nng_cv_until, +nng_cv_wake, +nng_cv_wake1, +nng_mtx_alloc, +nng_mtx_lock, +nng_mtx_unlock
+ + + + + + + + + + + +nng_cv_wake — wake all waiters
-#include <nng/nng.h>
#include <nng/supplemental/util/platform.h>
void nng_cv_wake(nng_cv *cv);
-The nng_cv_wake() wakes any threads waiting for the condition variable cv
-to be signaled in the nng_cv_wait() or
-nng_cv_until() functions.
nng_cv_wait() or
+nng_cv_until() functions.
The caller must have have ownership of the mutex that was used when cv was allocated.
The caller should already have set the condition that the waiters @@ -9426,16 +14006,28 @@ will check, while holding the mutex.
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 nng_cv_wake1() for a solution to this problem.
nng_cv_wake1() for a solution to this problem.
-nng_cv_alloc, -nng_cv_until, -nng_cv_wait, -nng_cv_wake1, -nng_mtx_alloc, -nng_mtx_lock, -nng_mtx_unlock
+nng_cv_alloc, +nng_cv_until, +nng_cv_wait, +nng_cv_wake1, +nng_mtx_alloc, +nng_mtx_lock, +nng_mtx_unlock
+ + + + + + + + + + + +nng_cv_wake1 — wake one waiter
-#include <nng/nng.h>
#include <nng/supplemental/util/platform.h>
void nng_cv_wake1(nng_cv *cv);
-The nng_cv_wake1() wakes at most one thread waiting for the condition
variable cv
-to be signaled in the nng_cv_wait() or
-nng_cv_until() functions.
nng_cv_wait() or
+nng_cv_until() functions.
The caller must have have ownership of the mutex that was used when cv was allocated.
The caller should already have set the condition that the waiters @@ -9528,16 +14120,28 @@ will check, while holding the mutex.
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 nng_cv_wake().
nng_cv_wake().
-nng_cv_alloc, -nng_cv_until, -nng_cv_wait, -nng_cv_wake, -nng_mtx_alloc, -nng_mtx_lock, -nng_mtx_unlock
+nng_cv_alloc, +nng_cv_until, +nng_cv_wait, +nng_cv_wake, +nng_mtx_alloc, +nng_mtx_lock, +nng_mtx_unlock
+ + + + + + + + + + + +nng_mtx_alloc - allocate mutex
-nng_mtx_alloc — allocate mutex
+#include <nng/nng.h>
#include <nng/supplemental/util/platform.h>
@@ -9616,25 +14220,37 @@ typedef struct nng_mtx nng_mtx;
int nng_mtx_alloc(nng_mtx **mtxp);
-The nng_mtx_alloc() function allocates mutex and returns it in mtxp.
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.
-This function returns 0 on success, and non-zero otherwise.
-NNG_ENOMEM: Insufficient free memory exists.nng_cv_alloc, -nng_mtx_free, -nng_mtx_lock, -nng_mtx_unlock
+nng_cv_alloc, +nng_mtx_free, +nng_mtx_lock, +nng_mtx_unlock
+ + + + + + + + + + + +nng_mtx_free — free mutex
-#include <nng/nng.h>
#include <nng/supplemental/util/platform.h>
void nng_mtx_free(nng_mtx *mtx);
-The nng_mtx_free() function frees the mutex mtx.
The mutex must not be locked when this function is called.
nng_mtx_lock — lock mutex
-#include <nng/nng.h>
#include <nng/supplemental/util/platform.h>
void nng_mtx_lock(nng_mtx *mtx);
-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().
If multiple threads are waiting for the lock, the order of acquisition is not specified.
nng_cv_alloc, -nng_mtx_alloc, -nng_mtx_unlock
+nng_cv_alloc, +nng_mtx_alloc, +nng_mtx_unlock
+ + + + + + + + + + + +nng_mtx_unlock — unlock mutex
-#include <nng/nng.h>
#include <nng/supplemental/util/platform.h>
void nng_mtx_unlock(nng_mtx *mtx);
-The nng_mtx_unlock() relinquishes ownership of the mutex mtx that
-was previously acquired via nng_mtx_lock().
nng_mtx_lock().
@@ -9907,9 +14547,21 @@ was previously acquired via nng_mt
Attempting to unlock a mutex that is not owned by the caller will result
in undefined behavior.