From 53d5c2766d90a53d3f6c0437bc59c1ad63ec701a Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Thu, 22 Mar 2018 14:06:07 -0700 Subject: Add documentation for supplemental functions. This includes platform portability stuff like mutexes and threads, etc. While here we fixed a problem with nng_opts_parse and we addressed the type of the platform API. --- docs/man/libnng.3.adoc | 17 ++- docs/man/nng_clock.3supp.adoc | 58 +++++++++++ docs/man/nng_cv_alloc.3supp.adoc | 58 +++++++++++ docs/man/nng_cv_free.3supp.adoc | 41 ++++++++ docs/man/nng_cv_until.3supp.adoc | 89 ++++++++++++++++ docs/man/nng_cv_wait.3supp.adoc | 85 +++++++++++++++ docs/man/nng_cv_wake.3supp.adoc | 60 +++++++++++ docs/man/nng_cv_wake1.3supp.adoc | 61 +++++++++++ docs/man/nng_msleep.3supp.adoc | 48 +++++++++ docs/man/nng_mtx_alloc.3supp.adoc | 56 ++++++++++ docs/man/nng_mtx_free.3supp.adoc | 42 ++++++++ docs/man/nng_mtx_lock.3supp.adoc | 63 ++++++++++++ docs/man/nng_mtx_unlock.3supp.adoc | 47 +++++++++ docs/man/nng_opts_parse.3supp | 183 --------------------------------- docs/man/nng_opts_parse.3supp.adoc | 183 +++++++++++++++++++++++++++++++++ docs/man/nng_random.3supp.adoc | 44 ++++++++ docs/man/nng_thread_create.3supp.adoc | 85 +++++++++++++++ docs/man/nng_thread_destroy.3supp.adoc | 46 +++++++++ 18 files changed, 1082 insertions(+), 184 deletions(-) create mode 100644 docs/man/nng_clock.3supp.adoc create mode 100644 docs/man/nng_cv_alloc.3supp.adoc create mode 100644 docs/man/nng_cv_free.3supp.adoc create mode 100644 docs/man/nng_cv_until.3supp.adoc create mode 100644 docs/man/nng_cv_wait.3supp.adoc create mode 100644 docs/man/nng_cv_wake.3supp.adoc create mode 100644 docs/man/nng_cv_wake1.3supp.adoc create mode 100644 docs/man/nng_msleep.3supp.adoc create mode 100644 docs/man/nng_mtx_alloc.3supp.adoc create mode 100644 docs/man/nng_mtx_free.3supp.adoc create mode 100644 docs/man/nng_mtx_lock.3supp.adoc create mode 100644 docs/man/nng_mtx_unlock.3supp.adoc delete mode 100644 docs/man/nng_opts_parse.3supp create mode 100644 docs/man/nng_opts_parse.3supp.adoc create mode 100644 docs/man/nng_random.3supp.adoc create mode 100644 docs/man/nng_thread_create.3supp.adoc create mode 100644 docs/man/nng_thread_destroy.3supp.adoc (limited to 'docs') diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 2fd0109f..feab3ebf 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -214,7 +214,22 @@ network applications with _NNG_, but they are made available as a convenience to aid in creating portable applications. |=== -|<>|parse command line options +|<>|get time +|<>|allocate condition variable +|<>|free condition variable +|<>|wait for condition or timeout +|<>|wait for condition +|<>|wake all waiters +|<>|wake one waiter +|<>|sleep for milliseconds +|<>|allocate mutex +|<>|free mutex +|<>|lock mutex +|<>|unlock mutex +|<>|parse command line options +|<>|get random number +|<>|create thread +|<>|reap thread |=== diff --git a/docs/man/nng_clock.3supp.adoc b/docs/man/nng_clock.3supp.adoc new file mode 100644 index 00000000..cfbf0bf3 --- /dev/null +++ b/docs/man/nng_clock.3supp.adoc @@ -0,0 +1,58 @@ += nng_clock(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_clock - get time + +== SYNOPSIS + +[source, c] +---- +#include +#include + +typedef uint64_t nng_time; + +nng_time nng_clock(void); +---- + +== DESCRIPTION + +The `nng_clock()` 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. + +IMPORTANT: The reference time will be the same for a given program, +but different programs may have different references. + +TIP: This function is intended mostly to help with setting appropriate +timeouts using <>. + +== RETURN VALUES + +Milliseconds since reference time. + +== ERRORS + +None. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_cv_alloc.3supp.adoc b/docs/man/nng_cv_alloc.3supp.adoc new file mode 100644 index 00000000..0668298f --- /dev/null +++ b/docs/man/nng_cv_alloc.3supp.adoc @@ -0,0 +1,58 @@ += 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 +<> or +<>. +The mutex must also be owned when signaling the condition using the +<> or +<> functions. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_cv_free.3supp.adoc b/docs/man/nng_cv_free.3supp.adoc new file mode 100644 index 00000000..3c076093 --- /dev/null +++ b/docs/man/nng_cv_free.3supp.adoc @@ -0,0 +1,41 @@ += 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 + +<>, +<> diff --git a/docs/man/nng_cv_until.3supp.adoc b/docs/man/nng_cv_until.3supp.adoc new file mode 100644 index 00000000..4d39ecc0 --- /dev/null +++ b/docs/man/nng_cv_until.3supp.adoc @@ -0,0 +1,89 @@ += nng_cv_until(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_until - wait for condition or timeout + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_cv_wait(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 <> or +<>, or the system clock (as tracked +by <>) 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] +---- + + nng_mtx_lock(m); // assume cv was allocated using m + while (!condition_true) { + if (nng_cv_wait(cv) == 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; + cv_wake(cv); + nng_mtx_unlock(m); +---- + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_cv_wait.3supp.adoc b/docs/man/nng_cv_wait.3supp.adoc new file mode 100644 index 00000000..034b3ea9 --- /dev/null +++ b/docs/man/nng_cv_wait.3supp.adoc @@ -0,0 +1,85 @@ += 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 <> or +<>. + +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; + cv_wake(cv); + nng_mtx_unlock(m); +---- + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_cv_wake.3supp.adoc b/docs/man/nng_cv_wake.3supp.adoc new file mode 100644 index 00000000..ad8dadfe --- /dev/null +++ b/docs/man/nng_cv_wake.3supp.adoc @@ -0,0 +1,60 @@ += nng_cv_wake(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_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 <> or +<> 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 problem known as the "`thundering herd`" when there are many +waiters, as they are all woken simultaneously. +See <> for a solution to this problem. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_cv_wake1.3supp.adoc b/docs/man/nng_cv_wake1.3supp.adoc new file mode 100644 index 00000000..1938a702 --- /dev/null +++ b/docs/man/nng_cv_wake1.3supp.adoc @@ -0,0 +1,61 @@ += 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 <> or +<> 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: While this function avoids the "`thundering herd`" problem, 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 <>. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_msleep.3supp.adoc b/docs/man/nng_msleep.3supp.adoc new file mode 100644 index 00000000..f3e7f25c --- /dev/null +++ b/docs/man/nng_msleep.3supp.adoc @@ -0,0 +1,48 @@ += nng_msleep(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_msleep - sleep milliseconds + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_msleep(nng_duration msec); +---- + +== DESCRIPTION + +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. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_mtx_alloc.3supp.adoc b/docs/man/nng_mtx_alloc.3supp.adoc new file mode 100644 index 00000000..ba4e0c06 --- /dev/null +++ b/docs/man/nng_mtx_alloc.3supp.adoc @@ -0,0 +1,56 @@ += 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 "`own`" 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 + +<>, +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_mtx_free.3supp.adoc b/docs/man/nng_mtx_free.3supp.adoc new file mode 100644 index 00000000..f0cb44de --- /dev/null +++ b/docs/man/nng_mtx_free.3supp.adoc @@ -0,0 +1,42 @@ += 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 + +<>, +<> diff --git a/docs/man/nng_mtx_lock.3supp.adoc b/docs/man/nng_mtx_lock.3supp.adoc new file mode 100644 index 00000000..54aacd37 --- /dev/null +++ b/docs/man/nng_mtx_lock.3supp.adoc @@ -0,0 +1,63 @@ += 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 <>. + +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 "`trylock`" operation, 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 + +<>, +<>, +<>, +<> diff --git a/docs/man/nng_mtx_unlock.3supp.adoc b/docs/man/nng_mtx_unlock.3supp.adoc new file mode 100644 index 00000000..281a3f1e --- /dev/null +++ b/docs/man/nng_mtx_unlock.3supp.adoc @@ -0,0 +1,47 @@ += 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_lock - lock mutex + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_mtx_unlock(nng_mtx *mtx); +---- + +== DESCRIPTION + +The `nng_mtx_unlock()` reqlinquishes ownership of the mutex _mtx_ that +was previously acquired via <>. + +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 + +<>, +<>, +<> diff --git a/docs/man/nng_opts_parse.3supp b/docs/man/nng_opts_parse.3supp deleted file mode 100644 index 6fc22a7f..00000000 --- a/docs/man/nng_opts_parse.3supp +++ /dev/null @@ -1,183 +0,0 @@ -= nng_opts_parse(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_opts_parse - parse command line options - -== SYNOPSIS - -[source, c] ----- -#include -#include - -typedef struct nng_optspec { - const char *o_name; // Long style name (may be NULL for short only) - int o_short; // Short option (no clustering!) - int o_val; // Value stored on a good parse (>0) - bool o_arg; // Option takes an argument if true -} nng_optspec; - -int nng_opts_parse(int argc, const char **argv, const nng_optspec *spec, int *val, const char **arg, int *idx); ----- - -== DESCRIPTION - -The `nng_opts_parse()` is function is a supplemental funtion intened to -facilitate parsing command line arguments. -This function exists largely to stand in for `getopt()` from POSIX -systems, but it is available everywhere that _NNG_ is, and it includes -some capabilities missing from `getopt()`. - -The function parses arguments from `main()` (using _argc_ and _argv_), -starting at the index referenced by _idx_. -(New invocations typically set the value pointed to by _idx_ to 1.) - -Options are parsed as specified by _spec_ (see <