From 331bd5a7c360083f245fe6c82afa38dd05c4a9c9 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 24 Mar 2024 22:19:42 -0700 Subject: More org stuff --- docs/reference/src/SUMMARY.md | 10 +++-- docs/reference/src/api/aio/nng_aio_free.md | 3 +- docs/reference/src/api/aio/nng_aio_result.md | 14 +++---- docs/reference/src/api/aio/nng_aio_wait.md | 2 +- docs/reference/src/api/aio_provider.md | 10 ----- docs/reference/src/api/general.md | 1 - docs/reference/src/api/index.md | 16 ++++---- docs/reference/src/api/nng_aio.md | 59 ---------------------------- docs/reference/src/api/nng_alloc.md | 44 --------------------- docs/reference/src/api/nng_clock.md | 43 -------------------- docs/reference/src/api/nng_free.md | 35 ----------------- docs/reference/src/api/util/index.md | 1 + docs/reference/src/api/util/nng_alloc.md | 44 +++++++++++++++++++++ docs/reference/src/api/util/nng_clock.md | 43 ++++++++++++++++++++ docs/reference/src/api/util/nng_free.md | 35 +++++++++++++++++ docs/reference/src/api/util/nng_version.md | 36 +++++++++++++++++ docs/reference/src/protocols/pub.md | 40 +++++++++++++++++++ 17 files changed, 223 insertions(+), 213 deletions(-) delete mode 100644 docs/reference/src/api/aio_provider.md delete mode 100644 docs/reference/src/api/general.md delete mode 100644 docs/reference/src/api/nng_aio.md delete mode 100644 docs/reference/src/api/nng_alloc.md delete mode 100644 docs/reference/src/api/nng_clock.md delete mode 100644 docs/reference/src/api/nng_free.md create mode 100644 docs/reference/src/api/util/index.md create mode 100644 docs/reference/src/api/util/nng_alloc.md create mode 100644 docs/reference/src/api/util/nng_clock.md create mode 100644 docs/reference/src/api/util/nng_free.md create mode 100644 docs/reference/src/api/util/nng_version.md create mode 100644 docs/reference/src/protocols/pub.md (limited to 'docs/reference') diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md index 4ae2c79b..ba1454d8 100644 --- a/docs/reference/src/SUMMARY.md +++ b/docs/reference/src/SUMMARY.md @@ -9,6 +9,7 @@ - [Protocols](./protocols/index.md) - [BUS](protocols/bus.md) + - [PUB](protocols/pub.md) - [REP](protocols/rep.md) - [Transports](./transports/index.md) @@ -44,17 +45,18 @@ - [nng_aio_get_input](api/aio_provider/nng_aio_get_input.md) - [nng_aio_set_output](api/aio_provider/nng_aio_set_output.md) - - [General Purpose Functions](api/general.md) + - [Utility Functions](api/util/index.md) - - [nng_alloc](api/nng_alloc.md) - - [nng_clock](api/nng_clock.md) + - [nng_alloc](api/util/nng_alloc.md) + - [nng_clock](api/util/nng_clock.md) + - [nng_free](api/util/nng_free.md) + - [nng_version](api/util/nng_version.md) - [nng_cv_alloc](api/nng_cv_alloc.md) - [nng_cv_free](api/nng_cv_free.md) - [nng_cv_until](api/nng_cv_until.md) - [nng_cv_wait](api/nng_cv_wait.md) - [nng_cv_wake](api/nng_cv_wake.md) - [nng_cv_wake1](api/nng_cv_wake1.md) - - [nng_free](api/nng_free.md) - [Context Functions](api/context.md) diff --git a/docs/reference/src/api/aio/nng_aio_free.md b/docs/reference/src/api/aio/nng_aio_free.md index c558535d..3d73dd7c 100644 --- a/docs/reference/src/api/aio/nng_aio_free.md +++ b/docs/reference/src/api/aio/nng_aio_free.md @@ -31,5 +31,4 @@ This can be useful to discard the _aio_ object from within the callback for the ## SEE ALSO [nng_aio_alloc()](nng_aio_alloc.md), -[nng_aio_stop()](nng_aio_stop.md), -[nng_aio](nng_aio.md) +[nng_aio_stop()](nng_aio_stop.md) diff --git a/docs/reference/src/api/aio/nng_aio_result.md b/docs/reference/src/api/aio/nng_aio_result.md index fe6688fd..607f34d4 100644 --- a/docs/reference/src/api/aio/nng_aio_result.md +++ b/docs/reference/src/api/aio/nng_aio_result.md @@ -19,11 +19,12 @@ with the handle _aio_. If the operation was successful, then 0 is returned. Otherwise a non-zero error code is returned. -NOTE: The return value from this function is undefined if the operation -has not completed yet. -Either call this from the handle's completion -callback, or after waiting for the operation to complete with -[`nng_aio_wait()`](nng_aio_wait.md). +> [!NOTE] +> The return value from this function is undefined if the operation +> has not completed yet. +> Either call this from the handle's completion +> callback, or after waiting for the operation to complete with +> [`nng_aio_wait()`](nng_aio_wait.md). ## RETURN VALUES @@ -42,5 +43,4 @@ Various other return values are possible depending on the operation. [nng_aio_abort()](nng_aio_abort.md), [nng_aio_alloc()](nng_aio_alloc.md), [nng_aio_wait()](nng_aio_wait.md), -[nng_strerror()](nng_strerror.md), -[nng_aio](nng_aio.md), +[nng_strerror()](../util/nng_strerror.md) diff --git a/docs/reference/src/api/aio/nng_aio_wait.md b/docs/reference/src/api/aio/nng_aio_wait.md index 52f5671e..be81378c 100644 --- a/docs/reference/src/api/aio/nng_aio_wait.md +++ b/docs/reference/src/api/aio/nng_aio_wait.md @@ -24,7 +24,7 @@ function will not be called until the callback has completed. > [!IMPORTANT] > This function should never be called from a function that itself -> is a callback of an [`nng_aio`](nng_aio.md), either this one or any other. +> is a callback of an [`nng_aio`](index.md), either this one or any other. > Doing so may result in a deadlock. ## SEE ALSO diff --git a/docs/reference/src/api/aio_provider.md b/docs/reference/src/api/aio_provider.md deleted file mode 100644 index cf5acce7..00000000 --- a/docs/reference/src/api/aio_provider.md +++ /dev/null @@ -1,10 +0,0 @@ -# Asynchronous I/O for Providers - -This section documents functions used when implementing I/O providers. - -I/O providers actually perform the operations that are linked to -an [`nng_aio`](nng_aio.md) object. - -Most applications will not use the functions listed here. -Applications the implement their own HTTP handler functions, or -custom transport providers, might make use of these functions. diff --git a/docs/reference/src/api/general.md b/docs/reference/src/api/general.md deleted file mode 100644 index a830d6bd..00000000 --- a/docs/reference/src/api/general.md +++ /dev/null @@ -1 +0,0 @@ -# General Purpose Functions diff --git a/docs/reference/src/api/index.md b/docs/reference/src/api/index.md index 1541b541..fb27e444 100644 --- a/docs/reference/src/api/index.md +++ b/docs/reference/src/api/index.md @@ -10,14 +10,16 @@ the _NNG_ programming interface. We have organized the reference material along general functional areas. They are: +- Sockets +- Dialers, Listeners, and Pipes +- Contexts - [Asynchronous I/O](aio/index.md) - [Asynchronous I/O for Providers](aio_provider/index.md) -- General Utility Functions -- Scalability Protocol Sockets -- Scalability Protocol Contexts -- Concurrency / Multi-threading -- HTTP Server +- Utility Functions +- Threads and Synchronization - HTTP Client -- Streaming API -- Statistics API +- HTTP Server +- TLS Support +- Connected Streams +- Statistics - Legacy Compatibility diff --git a/docs/reference/src/api/nng_aio.md b/docs/reference/src/api/nng_aio.md deleted file mode 100644 index 667e785c..00000000 --- a/docs/reference/src/api/nng_aio.md +++ /dev/null @@ -1,59 +0,0 @@ -# nng_aio - -## NAME - -nng_aio --- asynchronous I/O handle - -```c -#include - -typedef struct nng_aio nng_aio; -``` - -## DESCRIPTION - -An `nng_aio`{{hi:aio}} is an opaque structure used in conjunction with -{{i:asynchronous I/O}} operations. -Every asynchronous operation uses one of these structures, each of which -can only be used with a single operation at a time. - -Asynchronous operations are performed without blocking calling application -threads. -Instead the application registers a callback function to be executed -when the operation is complete (whether successfully or not). -This callback will be executed exactly once. - -The asynchronous I/O framework also supports cancellation of -operations that are already in progress -(see [`nng_aio_cancel()`](nng_aio_cancel.md)), as well setting a maximum -timeout for them to complete within -(see [`nng_aio_set_timeout()`](nng_aio_set_timeout.md)). - -It is also possible to initiate an asynchronous operation, and wait for it to -complete [`nng_aio_wait()`](nng_aio_wait.md). - -These structures are created using the [`nng_aio_alloc()`](nng_aio_alloc.md), -and destroyed using [`nng_aio_free()`](nng_aio_free.md). - -> [!IMPORTANT] -> A given `nng_aio` can only have a single operation in progress -> at any given time. Attempts to reuse an `nng_aio` while another -> operation is in progress will generally cause a crash. - -## SEE ALSO - -[nng_aio_abort()](nng_aio_abort.md), -[nng_aio_alloc()](nng_aio_alloc.md), -[nng_aio_cancel()](nng_aio_cancel.md), -[nng_aio_count()](nng_aio_count.md), -[nng_aio_free()](nng_aio_free.md), -[nng_aio_get_input()](nng_aio_get_input.md), -[nng_aio_get_msg()](nng_aio_get_msg.md), -[nng_aio_get_output()](nng_aio_get_output.md), -[nng_aio_result()](nng_aio_result.md), -[nng_aio_set_input()](nng_aio_set_input.md), -[nng_aio_set_iov()](nng_aio_set_iov.md), -[nng_aio_set_msg()](nng_aio_set_msg.md), -[nng_aio_set_timeout()](nng_aio_set_timeout.md), -[nng_aio_stop()](nng_aio_stop.md), -[nng_aio_wait()](nng_aio_wait.md), diff --git a/docs/reference/src/api/nng_alloc.md b/docs/reference/src/api/nng_alloc.md deleted file mode 100644 index 6cc4b21f..00000000 --- a/docs/reference/src/api/nng_alloc.md +++ /dev/null @@ -1,44 +0,0 @@ -# nng_alloc() - -## NAME - -nng_alloc --- allocate memory - -## SYNOPSIS - -```c -#include - -void *nng_alloc(size_t size); -``` - -## DESCRIPTION - -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()`](nng_send.md) using -the flag `NNG_FLAG_ALLOC`. Alternatively, it can be freed when no -longer needed using [`nng_free()`](nng_free.md). - -> [!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. - -## RETURN VALUES - -This function returns a pointer to the allocated memory on success, -and `NULL` otherwise. - -## ERRORS - -No errors are returned, but if memory cannot be allocated then `NULL` -is returned. - -## SEE ALSO - -[nng_free()](nng_free.md), -[nng_send()](nng_send.md) diff --git a/docs/reference/src/api/nng_clock.md b/docs/reference/src/api/nng_clock.md deleted file mode 100644 index 37be0d0c..00000000 --- a/docs/reference/src/api/nng_clock.md +++ /dev/null @@ -1,43 +0,0 @@ -# nng_clock() - -## NAME - -nng_clock - get time - -## SYNOPSIS - -```c -#include -#include - -typedef uint64_t nng_time; - -nng_time nng_clock(void); -``` - -## DESCRIPTION - -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()`](nng_cv_until.md). - -## RETURN VALUES - -Milliseconds since reference time. - -## SEE ALSO - -[nng_sleep_aio()](nng_sleep_aio.md), -[nng_cv_until()](nng_cv_until.md), -[nng_msleep()](nng_msleep.md), -[nng_duration](nng_duration.md) diff --git a/docs/reference/src/api/nng_free.md b/docs/reference/src/api/nng_free.md deleted file mode 100644 index cc1d3308..00000000 --- a/docs/reference/src/api/nng_free.md +++ /dev/null @@ -1,35 +0,0 @@ -# nng_free() - -## NAME - -nng_free --- free memory - -## SYNOPSIS - -```c -#include - -void nng_free(void *ptr, size_t size); -``` - -## DESCRIPTION - -The `nng_free()` function deallocates a memory region of size _size_, -that was previously allocated by [`nng_alloc()`](nng_alloc.md) or -[`nng_recv()`](nng_recv.md) with the `NNG_FLAG_ALLOC` flag. - -> [!IMPORTANT] -> It is very important that _size_ match the allocation size -> used to allocate the memory. - -> [!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. - -## SEE ALSO - -[nng_alloc()](nng_alloc.md), -[nng_recv()](nng_free.md) diff --git a/docs/reference/src/api/util/index.md b/docs/reference/src/api/util/index.md new file mode 100644 index 00000000..a830d6bd --- /dev/null +++ b/docs/reference/src/api/util/index.md @@ -0,0 +1 @@ +# General Purpose Functions diff --git a/docs/reference/src/api/util/nng_alloc.md b/docs/reference/src/api/util/nng_alloc.md new file mode 100644 index 00000000..98f71fa5 --- /dev/null +++ b/docs/reference/src/api/util/nng_alloc.md @@ -0,0 +1,44 @@ +# nng_alloc() + +## NAME + +nng_alloc --- allocate memory + +## SYNOPSIS + +```c +#include + +void *nng_alloc(size_t size); +``` + +## DESCRIPTION + +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()`](../socket/nng_send.md) using +the flag `NNG_FLAG_ALLOC`. Alternatively, it can be freed when no +longer needed using [`nng_free()`](nng_free.md). + +> [!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. + +## RETURN VALUES + +This function returns a pointer to the allocated memory on success, +and `NULL` otherwise. + +## ERRORS + +No errors are returned, but if memory cannot be allocated then `NULL` +is returned. + +## SEE ALSO + +[nng_free()](nng_free.md), +[nng_send()](../socket/nng_send.md) diff --git a/docs/reference/src/api/util/nng_clock.md b/docs/reference/src/api/util/nng_clock.md new file mode 100644 index 00000000..3653bfa2 --- /dev/null +++ b/docs/reference/src/api/util/nng_clock.md @@ -0,0 +1,43 @@ +# nng_clock() + +## NAME + +nng_clock - get time + +## SYNOPSIS + +```c +#include +#include + +typedef uint64_t nng_time; + +nng_time nng_clock(void); +``` + +## DESCRIPTION + +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()`](../threads/nng_cv_until.md). + +## RETURN VALUES + +Milliseconds since reference time. + +## SEE ALSO + +[nng_sleep_aio()](nng_sleep_aio.md), +[nng_cv_until()](../threads/nng_cv_until.md), +[nng_msleep()](nng_msleep.md), +[nng_duration](nng_duration.md) diff --git a/docs/reference/src/api/util/nng_free.md b/docs/reference/src/api/util/nng_free.md new file mode 100644 index 00000000..ca527914 --- /dev/null +++ b/docs/reference/src/api/util/nng_free.md @@ -0,0 +1,35 @@ +# nng_free() + +## NAME + +nng_free --- free memory + +## SYNOPSIS + +```c +#include + +void nng_free(void *ptr, size_t size); +``` + +## DESCRIPTION + +The `nng_free()` function deallocates a memory region of size _size_, +that was previously allocated by [`nng_alloc()`](nng_alloc.md) or +[`nng_recv()`](../socket/nng_recv.md) with the `NNG_FLAG_ALLOC` flag. + +> [!IMPORTANT] +> It is very important that _size_ match the allocation size +> used to allocate the memory. + +> [!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. + +## SEE ALSO + +[nng_alloc()](nng_alloc.md), +[nng_recv()](nng_free.md) diff --git a/docs/reference/src/api/util/nng_version.md b/docs/reference/src/api/util/nng_version.md new file mode 100644 index 00000000..7cc10bdf --- /dev/null +++ b/docs/reference/src/api/util/nng_version.md @@ -0,0 +1,36 @@ +# nng_version(3) + +## NAME + +nng_version - report library version + +## SYNOPSIS + +```c +#include + +const char * nng_version(void); +``` + +## DESCRIPTION + +The `nng_version()` function returns a human readable {{i:version number}} +for _NNG_. + +Additionally, compile time version information is available +via some predefined macros: + +- {{i:`NNG_MAJOR_VERSION`}}: Major version number. +- {{i:`NNG_MINOR_VERSION`}}: Minor version number. +- {{i:`NNG_PATCH_VERSION`}}: Patch version number. + +_NNG_ is developed and released using +[Semantic Versioning 2.0](http://www.semver.org), and +the version numbers reported refer to both the API and the library itself. +(The {{i:ABI}} -- {{i: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.) + +## RETURN VALUES + +Null-terminated string containing the library version number. diff --git a/docs/reference/src/protocols/pub.md b/docs/reference/src/protocols/pub.md new file mode 100644 index 00000000..bd49b1d3 --- /dev/null +++ b/docs/reference/src/protocols/pub.md @@ -0,0 +1,40 @@ +# PUB Protocol + +The {{i:_PUB_ protocol}}{{hi:protocol, _PUB_} is one half of a {{i:publisher}}/subscriber pattern. +In this pattern, a publisher sends data, which is broadcast to all +subscribers. +The subscribing applications only see the data to which +they have subscribed. + +The _PUB_ protocol is the publisher side, and the +[_SUB_](sub.md) protocol is the subscriber side. + +> [!NOTE] +> In this implementation, the publisher delivers all messages to all +> subscribers. +> The subscribers maintain their own subscriptions, and filter them locally. +> Thus, this pattern should not be used in an attempt to reduce bandwidth +> consumption. + +The topics that subscribers subscribe to is just the first part of +the message body. +Applications should construct their messages accordingly. + +## Socket Operations + +The [`nng_pub0_open()`](../api/nng_pub_open.md) functions create a publisher socket. +This socket may be used to send messages, but is unable to receive them. +Attempts to receive messages will result in `NNG_ENOTSUP`. + +## Protocol Versions + +Only version 0 of this protocol is supported. +(At the time of writing, no other versions of this protocol have been defined.) + +## Protocol Options + +The _PUB_ protocol has no protocol-specific options. + +## Protocol Headers + +The _PUB_ protocol has no protocol-specific headers. -- cgit v1.2.3-70-g09d2