From 548ab684fa83f3098dea4e7ce09d3f4f1bdb7358 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 30 Mar 2024 17:06:11 -0700 Subject: sock reorg --- docs/reference/src/SUMMARY.md | 10 +++---- docs/reference/src/api/socket/index.md | 7 ----- docs/reference/src/api/socket/nng_bus_open.md | 39 ------------------------ docs/reference/src/api/socket/nng_close.md | 41 ------------------------- docs/reference/src/api/socket/nng_pub_open.md | 39 ------------------------ docs/reference/src/refs.md | 29 +++++++++--------- docs/reference/src/sock/index.md | 9 ++++++ docs/reference/src/sock/nng_bus_open.md | 41 +++++++++++++++++++++++++ docs/reference/src/sock/nng_close.md | 43 +++++++++++++++++++++++++++ docs/reference/src/sock/nng_pub_open.md | 41 +++++++++++++++++++++++++ 10 files changed, 153 insertions(+), 146 deletions(-) delete mode 100644 docs/reference/src/api/socket/index.md delete mode 100644 docs/reference/src/api/socket/nng_bus_open.md delete mode 100644 docs/reference/src/api/socket/nng_close.md delete mode 100644 docs/reference/src/api/socket/nng_pub_open.md create mode 100644 docs/reference/src/sock/index.md create mode 100644 docs/reference/src/sock/nng_bus_open.md create mode 100644 docs/reference/src/sock/nng_close.md create mode 100644 docs/reference/src/sock/nng_pub_open.md (limited to 'docs') diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md index b88cb6b8..4816be30 100644 --- a/docs/reference/src/SUMMARY.md +++ b/docs/reference/src/SUMMARY.md @@ -1,7 +1,5 @@ # Summary -- [Chapter 1](./chapter_1.md) - - [Overview](./overview/index.md) - [RAW mode](./overview/raw.md) @@ -51,11 +49,11 @@ - [nng_msg_set_pipe](msg/nng_msg_set_pipe.md) - [nng_msg_trim](msg/nng_msg_trim.md) - - [Sockets](api/socket/index.md) + - [Sockets](sock/index.md) - - [nng_bus_open](api/socket/nng_bus_open.md) - - [nng_close](api/socket/nng_close.md) - - [nng_pub_open](api/socket/nng_pub_open.md) + - [nng_bus_open](sock/nng_bus_open.md) + - [nng_close](sock/nng_close.md) + - [nng_pub_open](sock/nng_pub_open.md) - [Contexts](ctx/index.md) diff --git a/docs/reference/src/api/socket/index.md b/docs/reference/src/api/socket/index.md deleted file mode 100644 index f9a85b23..00000000 --- a/docs/reference/src/api/socket/index.md +++ /dev/null @@ -1,7 +0,0 @@ -# Sockets - -## See Also - -[nng_bus_open](nng_bus_open.md) -[nng_close](nng_close.md) -[nng_pub_open](nng_pub_open.md) diff --git a/docs/reference/src/api/socket/nng_bus_open.md b/docs/reference/src/api/socket/nng_bus_open.md deleted file mode 100644 index 3eb235e3..00000000 --- a/docs/reference/src/api/socket/nng_bus_open.md +++ /dev/null @@ -1,39 +0,0 @@ -# nng_bus_open - -## NAME - -nng_bus_open --- create _BUS_ socket - -## SYNOPSIS - -```c -#include -#include - -int nng_bus0_open(nng_socket *s); - -int nng_bus0_open_raw(nng_socket *s); -``` - -## DESCRIPTION - -The `nng_bus0_open()` function creates a [_BUS_](../../protocols/bus.md) version 0 -[socket](index.md) and returns it at the location pointed to by _s_. - -The `nng_bus0_open_raw()` function creates a [_BUS_](../../protocols/bus.md) version 0 -[socket](index.md) in -[raw](../overview/raw.md) mode, and returns it at the location pointed to by _s_. - -## RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient memory is available. -- `NNG_ENOTSUP`: The protocol is not supported. - -## SEE ALSO - -[BUS protocol](../../protocols/bus.md), -[RAW mode](../../overview/raw.md) diff --git a/docs/reference/src/api/socket/nng_close.md b/docs/reference/src/api/socket/nng_close.md deleted file mode 100644 index fded0357..00000000 --- a/docs/reference/src/api/socket/nng_close.md +++ /dev/null @@ -1,41 +0,0 @@ -# nng_close - -## NAME - -nng_close --- close socket - -## SYNOPSIS - -```c -#include - -int nng_close(nng_socket s); -``` - -## DESCRIPTION - -The `nng_close()` function closes the supplied socket, _s_. -Messages that have been submitted for sending may be flushed or delivered, -depending upon the transport. - -Further attempts to use the socket after this call returns will result -in `NNG_ECLOSED`. -Threads waiting for operations on the socket when this -call is executed may also return with an `NNG_ECLOSED` result. - -> [!NOTE] -> Closing the socket while data is in transmission will likely lead to loss -> of that data. -> There is no automatic linger or flush to ensure that the socket send buffers -> have completely transmitted. -> It is recommended to wait a brief period after calling -> [`nng_send()`](nng_send.md) or similar functions, before calling this -> function. - -## RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ECLOSED`: The socket _s_ is already closed or was never opened. diff --git a/docs/reference/src/api/socket/nng_pub_open.md b/docs/reference/src/api/socket/nng_pub_open.md deleted file mode 100644 index 18321896..00000000 --- a/docs/reference/src/api/socket/nng_pub_open.md +++ /dev/null @@ -1,39 +0,0 @@ -# nng_pub_open - -## NAME - -nng*pub_open --- create \_PUB* socket - -## SYNOPSIS - -```c -#include -#include - -int nng_pub0_open(nng_socket *s); - -int nng_pub0_open_raw(nng_socket *s); -``` - -== DESCRIPTION - -The `nng_pub0_open()` function creates a [_PUB_](../../protocols/pub.md) version 0 -[socket](index.md) and returns it at the location pointed to by _s_. - -The `nng_pub0_open_raw()` function creates a [_PUB_](../../protocols/pub.md) version 0 -[socket](index.md) in -[raw](../../overview/raw.md) mode and returns it at the location pointed to by _s_. - -## RETURN VALUES - -These functions return 0 on success, and non-zero otherwise. - -## ERRORS - -- `NNG_ENOMEM`: Insufficient memory is available. -- `NNG_ENOTSUP`: The protocol is not supported. - -## SEE ALSO - -[PUB Protocol](../../protocols/pub.md), -[SUB Protocol](../../protocols/sub.md) diff --git a/docs/reference/src/refs.md b/docs/reference/src/refs.md index 47071a0a..4c954596 100644 --- a/docs/reference/src/refs.md +++ b/docs/reference/src/refs.md @@ -12,6 +12,7 @@ [sockaddr_in6]: ../overview/sockaddr_in6.md [raw]: ../overview/raw.md [url]: ../overview/url.md +[transport]: ../tran/index.md @@ -26,20 +27,20 @@ [sub]: ../proto/sub.md [surveyor]: ../proto/surveyor.md - - -[nng_bus_open]: ../api/nng_bus_open.md -[nng_ctx_open]: ../api/nng_ctx_open.md -[nng_pair_open]: ../api/nng_pair_open.md -[nng_pub_open]: ../api/nng_pub_open.md -[nng_pull_open]: ../api/nng_pull_open.md -[nng_push_open]: ../api/nng_push_open.md -[nng_rep_open]: ../api/nng_rep_open.md -[nng_req_open]: ../api/nng_req_open.md -[nng_respondent_open]: ../api/nng_respondent_open.md -[nng_socket_set]: ../api/nng_socket_set.md -[nng_surveyor_open]: ../api/nng_surveyor_open.md -[nng_sub_open]: ../api/nng_sub_open.md + + +[nng_bus_open]: ../sock/nng_bus_open.md +[nng_pair_open]: ../sock/nng_pair_open.md +[nng_pub_open]: ../sock/nng_pub_open.md +[nng_pull_open]: ../sock/nng_pull_open.md +[nng_push_open]: ../sock/nng_push_open.md +[nng_rep_open]: ../sock/nng_rep_open.md +[nng_req_open]: ../sock/nng_req_open.md +[nng_respondent_open]: ../sock/nng_respondent_open.md +[nng_socket_set]: ../sock/nng_socket_set.md +[nng_surveyor_open]: ../sock/nng_surveyor_open.md +[nng_sub_open]: ../sock/nng_sub_open.md +[nng_close]: ../sock/nng_close.md diff --git a/docs/reference/src/sock/index.md b/docs/reference/src/sock/index.md new file mode 100644 index 00000000..d90a4fb9 --- /dev/null +++ b/docs/reference/src/sock/index.md @@ -0,0 +1,9 @@ +# Sockets + +## See Also + +[nng_bus_open][nng_bus_open] +[nng_close][nng_close] +[nng_pub_open][nng_pub_open] + +{{#include ../refs.md}} diff --git a/docs/reference/src/sock/nng_bus_open.md b/docs/reference/src/sock/nng_bus_open.md new file mode 100644 index 00000000..8705ad6f --- /dev/null +++ b/docs/reference/src/sock/nng_bus_open.md @@ -0,0 +1,41 @@ +# nng_bus_open + +## NAME + +nng_bus_open --- create _BUS_ socket + +## SYNOPSIS + +```c +#include +#include + +int nng_bus0_open(nng_socket *s); + +int nng_bus0_open_raw(nng_socket *s); +``` + +## DESCRIPTION + +The `nng_bus0_open()` function creates a [_BUS_][bus] version 0 +[socket][socket] and returns it at the location pointed to by _s_. + +The `nng_bus0_open_raw()` function creates a [_BUS_][bus] version 0 +[socket][socket] in +[raw mode][raw], and returns it at the location pointed to by _s_. + +## RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_ENOMEM`: Insufficient memory is available. +- `NNG_ENOTSUP`: The protocol is not supported. + +## SEE ALSO + +[BUS protocol][bus], +[RAW mode][raw] + +{{#include ../refs.md}} diff --git a/docs/reference/src/sock/nng_close.md b/docs/reference/src/sock/nng_close.md new file mode 100644 index 00000000..649316bd --- /dev/null +++ b/docs/reference/src/sock/nng_close.md @@ -0,0 +1,43 @@ +# nng_close + +## NAME + +nng_close --- close socket + +## SYNOPSIS + +```c +#include + +int nng_close(nng_socket s); +``` + +## DESCRIPTION + +The `nng_close()` function closes the [socket][socket] _s_. +Messages that have been submitted for sending may be flushed or delivered, +depending upon the [transport][transport]. + +Further attempts to use the socket after this call returns will result +in `NNG_ECLOSED`. +Threads waiting for operations on the socket when this +call is executed may also return with an `NNG_ECLOSED` result. + +> [!NOTE] +> Closing the socket while data is in transmission will likely lead to loss +> of that data. +> There is no automatic linger or flush to ensure that the socket send buffers +> have completely transmitted. +> It is recommended to wait a brief period after calling +> [`nng_send()`][nng_send] or similar functions, before calling this +> function. + +## RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_ECLOSED`: The socket _s_ is already closed or was never opened. + +{{#include ../refs.md}} diff --git a/docs/reference/src/sock/nng_pub_open.md b/docs/reference/src/sock/nng_pub_open.md new file mode 100644 index 00000000..0100cfcb --- /dev/null +++ b/docs/reference/src/sock/nng_pub_open.md @@ -0,0 +1,41 @@ +# nng_pub_open + +## NAME + +nng_pub_open --- create _PUB_ socket + +## SYNOPSIS + +```c +#include +#include + +int nng_pub0_open(nng_socket *s); + +int nng_pub0_open_raw(nng_socket *s); +``` + +## DESCRIPTION + +The `nng_pub0_open()` function creates a [_PUB_][pub] version 0 +[socket][socket] and returns it at the location pointed to by _s_. + +The `nng_pub0_open_raw()` function creates a [_PUB_][pub] version 0 +[socket][socket] in +[raw mode][raw] and returns it at the location pointed to by _s_. + +## RETURN VALUES + +These functions return 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_ENOMEM`: Insufficient memory is available. +- `NNG_ENOTSUP`: The protocol is not supported. + +## SEE ALSO + +[PUB Protocol](../../protocols/pub.md), +[SUB Protocol](../../protocols/sub.md) + +{{#include ../refs.md}} -- cgit v1.2.3-70-g09d2