Document nng_init and nng_fini

3 files changed, 85 insertions, 2 deletions

diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md
index 0492f33e..a37ba31e 100644
--- a/docs/ref/SUMMARY.md
+++ b/docs/ref/SUMMARY.md
@@ -6,6 +6,8 @@
 
 - [API Reference](./api/index.md)
 
+  - [Initialization](./api/init.md)
+
   - [Messages](./api/msg.md)
 
   - [Sockets](./api/sock.md)
diff --git a/docs/ref/api/init.md b/docs/ref/api/init.md
new file mode 100644
index 00000000..6e737cf3
--- /dev/null
+++ b/docs/ref/api/init.md
@@ -0,0 +1,81 @@
+# Initialization & Finalization
+
+This chapter details the function used to initialize
+the library before first use, and the funtion used to
+finalize the library and deallocate any resources used by the library.
+
+## Initialization
+
+```c
+typedef struct {
+    int16_t num_task_threads;
+    int16_t max_task_threads;
+    int16_t num_expire_threads;
+    int16_t max_expire_threads;
+    int16_t num_poller_threads;
+    int16_t max_poller_threads;
+    int16_t num_resolver_threads;
+} nng_init_params;
+
+extern int nng_init(nng_init_parms *params);
+```
+
+Before using other interfaces in this library, it is necessary to initialize
+the library. The {{i:`nng_init`}} function performs this initialization.
+
+The function is idempotent, although on tear down, every call to `nng_init` must
+be paired with a call to [`nng_fini`] or no resources will be released.
+This allows for libraries consuming these interfaces to safely initialize and finalize
+the library without disrupting other consumers in the same process.
+
+Further, only the first call to this function may have a value of _params_ other than `NULL`.
+If _params_ is not `NULL`, and the library has already been intiazed, then `nng_init` will
+return [`NNG_EBUSY`].
+
+In some cases it is desirable to tune certain runtime parameters for the library, which
+can be done by supplying a non-`NULL` _params_ argument.
+
+### Parameters
+
+The individual fields of the `nng_init_params` structure can be used to adjust certain
+runtime tunables for the library. There is no guarantee that these tunables are implemented,
+and applications should not depend upon them for correct operation.
+
+Any member of `nng_init_params` that is set to zero will be ignored, and any built in default
+will be used instead for that value.
+
+> [!NOTE]
+> Applications should make sure that structure is zero initialized before calling `nng_init`.
+
+The following parameters are present:
+
+- `num_task_threads` and `max_task_threads` \
+  Configures the number of threads to use for tasks, which are used principally for completion
+  callbacks. The maximum value can be used to provide an upper limit while still allowing
+  for a dynamically calculated value to be used, as long as it does not exceeed the maximum.
+
+- `num_expire_threads` and `max_expire_threads` \
+  Configures the number of threads used for expiring operations. Using a larger value will
+  reduce contention on some common locks, and may improve performance.
+
+- `num_poller_threads` and `max_poller_threads` \
+  Configures the number of threads to be used for performing I/O. Not all configurations support
+  changing these values.
+
+- `num_resolver_threads` \
+  Changes the number of threads used for asynchronous DNS look ups.
+
+## Finalization
+
+```c
+extern void nng_init(nng_init_parms *params);
+```
+
+When the consumer is ready to deallocate any resoures allocated by the library, it should call
+the {{i:`nng_fini`}} function. Each call to `nng_fini` should be paired with an earlier call to
+[`nng_init`].
+
+After calling `nng_fini`, the consuming application must not make any other calls to NNG functions,
+except that it may use `nng_init` to initialize the application for further use.
+
+{{#include ../xref.md}}
diff --git a/docs/ref/xref.md b/docs/ref/xref.md
index 55ec1a3c..b9b4c503 100644
--- a/docs/ref/xref.md
+++ b/docs/ref/xref.md
@@ -74,6 +74,8 @@
 [`nng_socket_peer_name`]: /api/sock.md#socket-identity
 [`nng_socket_get_recv_poll_fd`]: /api/sock.md#polling-socket-events
 [`nng_socket_get_send_poll_fd`]: /api/sock.md#polling-socket-events
+[`nng_init`]: /api/init.md#initialization
+[`nng_fini`]: /api/init.md#finalization
 [`nng_sub0_ctx_subscribe`]: /TODO.md
 [`nng_sub0_ctx_unsubscribe`]: /TODO.md
 [`nng_sub0_socket_subscribe`]: /TODO.md
@@ -93,8 +95,6 @@
 [`nng_aio_set_output`]: /TODO.md
 [`nng_send`]: /TODO.md
 [`nng_recv`]: /TODO.md
-[`nng_init`]: /TODO.md
-[`nng_fini`]: /TODO.md
 
 <!-- Macros -->