diff options
Diffstat (limited to 'docs/ref')
| -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 |
4 files changed, 29 insertions, 1 deletions
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 |