diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/man/libnng.3.adoc | 2 | ||||
| -rw-r--r-- | docs/man/nng_close.3.adoc | 59 | ||||
| -rw-r--r-- | docs/man/nng_ctx_close.3.adoc | 2 | ||||
| -rw-r--r-- | docs/man/nng_dialer_close.3.adoc | 2 | ||||
| -rw-r--r-- | docs/man/nng_listener_close.3.adoc | 2 | ||||
| -rw-r--r-- | docs/ref/api/sock.md | 22 | ||||
| -rw-r--r-- | docs/ref/migrate/nanomsg.md | 2 | ||||
| -rw-r--r-- | docs/ref/migrate/nng1.md | 5 | ||||
| -rw-r--r-- | docs/ref/xref.md | 1 |
9 files changed, 33 insertions, 64 deletions
diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 36117614..9cef1e0f 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -47,7 +47,7 @@ The following common functions exist in _libnng_. The following functions operate on sockets. |=== -|xref:nng_close.3.adoc[nng_close()]|close socket +|xref:nng_socket_close.3.adoc[nng_socket_close()]|close socket |xref:nng_dial.3.adoc[nng_dial()]|create and start dialer |xref:nng_get.3.adoc[nng_get()]|get socket option |xref:nng_listen.3.adoc[nng_listen()]|create and start listener diff --git a/docs/man/nng_close.3.adoc b/docs/man/nng_close.3.adoc deleted file mode 100644 index 1867df07..00000000 --- a/docs/man/nng_close.3.adoc +++ /dev/null @@ -1,59 +0,0 @@ -= nng_close(3) -// -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// 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_close - close socket - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> - -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 -xref:nng_send.3.adoc[`nng_send()`] or similar functions, before calling this -function. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_ECLOSED`:: The socket _s_ is already closed or was never opened. - -== SEE ALSO - -[.text-left] -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_ctx_close.3.adoc b/docs/man/nng_ctx_close.3.adoc index cfc51bfa..ff43d0b3 100644 --- a/docs/man/nng_ctx_close.3.adoc +++ b/docs/man/nng_ctx_close.3.adoc @@ -34,7 +34,7 @@ Threads waiting for operations on the context when this call is executed may also return with an `NNG_ECLOSED` result. NOTE: Closing the socket associated with _ctx_ -(using xref:nng_close.3.adoc[`nng_close()`]) also closes this context. +(using xref:nng_socket_close.3.adoc[`nng_socket_close()`]) also closes this context. == RETURN VALUES diff --git a/docs/man/nng_dialer_close.3.adoc b/docs/man/nng_dialer_close.3.adoc index 6af73ae4..84308b9b 100644 --- a/docs/man/nng_dialer_close.3.adoc +++ b/docs/man/nng_dialer_close.3.adoc @@ -48,7 +48,7 @@ This function returns 0 on success, and non-zero otherwise. == SEE ALSO [.text-left] -xref:nng_close.3.adoc[nng_close(3)], +xref:nng_socket_close.3.adoc[nng_socket_close(3)], xref:nng_dial.3.adoc[nng_dial(3)], xref:nng_dialer_create.3.adoc[nng_dialer_create(3)] xref:nng_strerror.3.adoc[nng_strerror(3)], diff --git a/docs/man/nng_listener_close.3.adoc b/docs/man/nng_listener_close.3.adoc index 239fe26b..b5109f42 100644 --- a/docs/man/nng_listener_close.3.adoc +++ b/docs/man/nng_listener_close.3.adoc @@ -48,7 +48,7 @@ This function returns 0 on success, and non-zero otherwise. == SEE ALSO [.text-left] -xref:nng_close.3.adoc[nng_close(3)], +xref:nng_socket_close.3.adoc[nng_socket_close(3)], xref:nng_listen.3.adoc[nng_listen(3)], xref:nng_listener_create.3.adoc[nng_listener_create(3)] xref:nng_strerror.3.adoc[nng_strerror(3)], diff --git a/docs/ref/api/sock.md b/docs/ref/api/sock.md index 59570240..40190d33 100644 --- a/docs/ref/api/sock.md +++ b/docs/ref/api/sock.md @@ -127,6 +127,28 @@ The following functions open a socket in [raw] mode: - {{i:`nng_sub0_open_raw`}} - [SUB][sub] version 0, raw mode - {{i:`nng_surveyor0_open_raw`}} - [SURVEYOR][surveyor] version 0, raw mode +## Closing a Socket + +```c +int nng_socket_close(nng_socket s); +``` + +The {{i:`nng_socket_close`}} function closes a socket, releasing all resources +associated with it. Any operations that are in progress will be terminated with +a result of [`NNG_ECLOSED`]. + +> [!NOTE] +> Closing a socket also invalidates any [dialers][dialer], [listeners][listener], +> [pipes][pipe], or [contexts][context] associated with it. + +> [!NOTE] +> This function will wait for any outstanding operations to be aborted, or to complete, +> before returning. Consequently it is not safe to call this from contexts that cannot +> block. + +> [!NOTE] +> Closing the socket may be disruptive to transfers that are still in progress. + ## Polling Socket Events ```c diff --git a/docs/ref/migrate/nanomsg.md b/docs/ref/migrate/nanomsg.md index 66add9b2..f7c6b971 100644 --- a/docs/ref/migrate/nanomsg.md +++ b/docs/ref/migrate/nanomsg.md @@ -38,7 +38,7 @@ NNG approach to messages. Likewise there is no `struct nn_cmsghdr` equivalent. | `nn_strerror` | [`nng_strerror`] | | `nn_errno` | None | Errors are returned directly rather than through `errno`. | | `nn_socket` | Various | Use the appropriate protocol constructor, such as `nng_req0_open`. | -| `nn_close` | `nng_close` | +| `nn_close` | `nng_socket_close` | | `nn_bind` | `nng_listen`, `nng_listener_create` | Allocating a listener with `nng_lister_create` and configuring it offers more capabilities. | | `nn_connect` | `nng_dial`, `nng_dialer_create` | Allocating a dialer with `nng_dialer_create` and configuring it offers more capabilities. | | `nn_shutdown` | `nng_lister_close`, `nng_dialer_close` | diff --git a/docs/ref/migrate/nng1.md b/docs/ref/migrate/nng1.md index 62a27432..663bf002 100644 --- a/docs/ref/migrate/nng1.md +++ b/docs/ref/migrate/nng1.md @@ -13,6 +13,11 @@ See the [Migrating From libnanomsg](nanomsg.md) chapter for details. It is now required for applications to initialize the library explicitly before using it. This is done using the [`nng_init`] function. +## Socket Close Function Renamed + +The `nng_close` function has been renamed to [`nng_socket_close`] to make it clearer that +the object being closed is a socket. + ## New AIO Error Code NNG_ESTOPPED When an operation fails with [`NNG_ESTOPPED`], it means that the associated [`nni_aio`] object has diff --git a/docs/ref/xref.md b/docs/ref/xref.md index 12146752..0dae482c 100644 --- a/docs/ref/xref.md +++ b/docs/ref/xref.md @@ -96,6 +96,7 @@ [`nng_iov`]: /api/aio.md#scatter-gather-vectors [`nng_socket_id`]: /api/sock.md#socket-identity [`nng_socket_raw`]: /api/sock.md#socket-identity +[`nng_socket_close`]: /api/sock.md#closing-a-socket [`nng_socket_proto_id`]: /api/sock.md#socket-identity [`nng_socket_proto_name`]: /api/sock.md#socket-identity [`nng_socket_peer_id`]: /api/sock.md#socket-identity |