diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index b787c7e8b..5748546db 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -297,7 +297,7 @@ as a convenience to aid in creating portable applications. // |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 +// |xref:nng_socket_pair.3supp.adoc[nng_socket_pair()]|create connected pair of BSD sockets |xref:nng_thread_create.3supp.adoc[nng_thread_create()]|create thread |xref:nng_thread_destroy.3supp.adoc[nng_thread_destroy()]|reap thread |xref:nng_thread_set_name.3supp.adoc[nng_thread_set_name()]|set thread name diff --git a/docs/man/nng_socket_pair.3supp.adoc b/docs/man/nng_socket_pair.3supp.adoc deleted file mode 100644 index 7718e27b9..000000000 --- a/docs/man/nng_socket_pair.3supp.adoc +++ /dev/null @@ -1,52 +0,0 @@ -= nng_socket_pair(3supp) -// -// Copyright 2024 Staysail Systems, Inc. -// -// 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_socket_pair - create a connected pair of BSD sockets - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_socket_pair(int fds[2]); ----- - -== DESCRIPTION - -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 xref:nng_socket.7.adoc[_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. - -NOTE: At present only POSIX platforms implementing `socketpair()` are supported with this function. - -TIP: This function may be useful for creating a shared connection between a parent process and -a child process on UNIX platforms, without requiring a shared filesystem or TCP connection. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ENOMEM`:: Insufficient memory exists. -`NNG_ENOTSUP`:: This platform does not support socket pairs. - -== SEE ALSO - -[.text-left] -xref:nng_socket.7.adoc[nng_socket(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index 1d7065c26..c68fb2b31 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -1,8 +1,8 @@ # Summary -- [API](./api.md) +- [API](./api/index.md) - - [Threading Functions](./api/thr/index.md) + - [Threading and Synchronization](./api/thr/index.md) - [nng_cv](./api/thr/nng_cv.md) - [nng_mtx](./api/thr/nng_mtx.md) @@ -14,6 +14,7 @@ - [nng_id_map](./api/util/nng_id_map.md) - [nng_msleep](./api/util/nng_msleep.md) - [nng_random](./api/util/nng_random.md) + - [nng_socket_pair](./api/util/nng_socket_pair.md) - [nng_strdup](./api/util/nng_strdup.md) - [nng_strerror](./api/util/nng_strerror.md) - [nng_version](./api/util/nng_version.md) diff --git a/docs/ref/api.md b/docs/ref/api.md deleted file mode 100644 index 84d0501f5..000000000 --- a/docs/ref/api.md +++ /dev/null @@ -1,4 +0,0 @@ -# API - -- [Threading Support](api/thr/) -- [Utility Functions](api/util/) diff --git a/docs/ref/api/index.md b/docs/ref/api/index.md new file mode 100644 index 000000000..6ad8257f5 --- /dev/null +++ b/docs/ref/api/index.md @@ -0,0 +1,4 @@ +# API + +- [Threading and Synchronization](api/thr/) +- [Utility Functions](api/util/) diff --git a/docs/ref/api/thr/index.md b/docs/ref/api/thr/index.md index 6355cfefe..bdd8bef48 100644 --- a/docs/ref/api/thr/index.md +++ b/docs/ref/api/thr/index.md @@ -1,4 +1,8 @@ -# Threading Functions +# Threading and Synchronization + +These interfaces are likely to be useful when implementing concurrent designs. +Furthermore, because NNG itself is based on concurrency, the synchronization primitives +are likely to be useful in callback functions and similar situations. - [nng_cv](nng_cv.md) - [nng_mtx](nng_mtx.md) diff --git a/docs/ref/api/util/index.md b/docs/ref/api/util/index.md index 1f202c0f5..cc6ee7e2f 100644 --- a/docs/ref/api/util/index.md +++ b/docs/ref/api/util/index.md @@ -2,14 +2,15 @@ This section documents various utility functions that may help with application portability. These are not fundamental to NNG -or Scalability Protocols, but we find them useful for a variety +or Scalability Protocols, but they are likely useful for a variety of other uses. -- [nng_alloc](nng_alloc.md) -- [nng_clock](nng_clock.md) -- [nng_id_map](nng_id_map.md) -- [nng_msleep](nng_msleep.md) -- [nng_random](nng_random.md) -- [nng_strdup](nng_strdup.md) -- [nng_strerror](nng_strerror.md) -- [nng_version](nng_version.md) +- [nng_alloc](nng_alloc.md) --- allocate memory +- [nng_clock](nng_clock.md) --- get time +- [nng_id_map](nng_id_map.md) --- identifier based mapping table +- [nng_msleep](nng_msleep.md) --- sleep milliseconds +- [nng_random](nng_random.md) --- get random number +- [nng_socket_pair](nng_socket_pair.md) --- create a connected pair of BSD sockets +- [nng_strdup](nng_strdup.md) --- duplicate string +- [nng_strerror](nng_strerror.md) --- return an error description +- [nng_version](nng_version.md) --- report library version diff --git a/docs/ref/tran/socket.md b/docs/ref/tran/socket.md index 0b7d5a457..c55966a87 100644 --- a/docs/ref/tran/socket.md +++ b/docs/ref/tran/socket.md @@ -4,10 +4,10 @@ The {{i:_socket_ transport}} supports communication between peers across arbitrary BSD sockets, such as those that are -created with [`nng_socket_pair()`][nng_socket_pair]. +created with [`nng_socket_pair`][nng_socket_pair]. This transport only supports [listeners][listener], -using [`nng_listener_create()`][nng_listener_create]. +using [`nng_listener_create`][nng_listener_create]. > [!NOTE] > Attempts to create [dialers][dialer] using this transport will result in `NNG_ENOTSUP`. @@ -63,7 +63,7 @@ Additionally, the following options may be supported on pipes when the platform [dialer]: [TODO.md] [nng_sockaddr]: [TODO.md] [nng_listener_create]: [TODO.md] -[nng_socket_pair]: [TODO.md] +[nng_socket_pair]: ../../api/util/nng_socket_pair.md [NNG_OPT_LOCADDR]: [TODO.md] [NNG_OPT_REMADDR]: [TODO.md] [NNG_OPT_URL]: [TODO.md]