socket: rename nng_close to nng_socket_close

nanomsg · Dec 31, 2024 · b0874b1 · b0874b1
1 parent 2a4a146
commit b0874b1
Show file tree

Hide file tree

Showing 40 changed files with 185 additions and 214 deletions.
diff --git a/demo/async/client.c b/demo/async/client.c
@@ -42,7 +42,7 @@ client(const char *url, const char *msecstr)
 {
 	nng_socket sock;
 	int        rv;
-	nng_msg *  msg;
+	nng_msg   *msg;
 	nng_time   start;
 	nng_time   end;
 	unsigned   msec;
@@ -76,9 +76,9 @@ client(const char *url, const char *msecstr)
 	}
 	end = nng_clock();
 	nng_msg_free(msg);
-	nng_close(sock);
+	nng_socket_close(sock);
 
-	printf("Request took %u milliseconds.\n", (uint32_t)(end - start));
+	printf("Request took %u milliseconds.\n", (uint32_t) (end - start));
 	return (0);
 }
 

diff --git a/demo/raw/raw.c b/demo/raw/raw.c
@@ -47,9 +47,9 @@
 // use in poll.
 struct work {
 	enum { INIT, RECV, WAIT, SEND } state;
-	nng_aio *  aio;
+	nng_aio   *aio;
 	nng_socket sock;
-	nng_msg *  msg;
+	nng_msg   *msg;
 };
 
 void
@@ -63,7 +63,7 @@ void
 server_cb(void *arg)
 {
 	struct work *work = arg;
-	nng_msg *    msg;
+	nng_msg     *msg;
 	int          rv;
 	uint32_t     when;
 
@@ -163,7 +163,7 @@ client(const char *url, const char *msecstr)
 {
 	nng_socket sock;
 	int        rv;
-	nng_msg *  msg;
+	nng_msg   *msg;
 	nng_time   start;
 	nng_time   end;
 	unsigned   msec;
@@ -196,9 +196,9 @@ client(const char *url, const char *msecstr)
 	}
 	end = nng_clock();
 	nng_msg_free(msg);
-	nng_close(sock);
+	nng_socket_close(sock);
 
-	printf("Request took %u milliseconds.\n", (uint32_t)(end - start));
+	printf("Request took %u milliseconds.\n", (uint32_t) (end - start));
 	return (0);
 }
 

diff --git a/demo/reqrep/reqrep.c b/demo/reqrep/reqrep.c
@@ -173,7 +173,7 @@ client(const char *url)
 
 	// This assumes that buf is ASCIIZ (zero terminated).
 	nng_free(buf, sz);
-	nng_close(sock);
+	nng_socket_close(sock);
 	return (0);
 }
 

diff --git 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
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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

diff --git a/include/nng/nng.h b/include/nng/nng.h
@@ -208,10 +208,10 @@ typedef struct nng_iov {
 #define NNG_DURATION_DEFAULT (-2)
 #define NNG_DURATION_ZERO (0)
 
-// nng_close closes the socket, terminating all activity and
+// nng_socket_close closes the socket, terminating all activity and
 // closing any underlying connections and releasing any associated
 // resources.
-NNG_DECL int nng_close(nng_socket);
+NNG_DECL int nng_socket_close(nng_socket);
 
 // nng_socket_id returns the positive socket id for the socket, or -1
 // if the socket is not valid.
@@ -435,8 +435,9 @@ NNG_DECL void nng_recv_aio(nng_socket, nng_aio *);
 // without resorting to raw mode sockets.  See the protocol specific
 // documentation for further details.  (Note that at this time, only
 // asynchronous send/recv are supported for contexts, but its easy enough
-// to make synchronous versions with nng_aio_wait().)  Note that nng_close
-// of the parent socket will *block* as long as any contexts are open.
+// to make synchronous versions with nng_aio_wait().)  Note that
+// nng_socket_close of the parent socket will *block* as long as any contexts
+// are open.
 
 // nng_ctx_open creates a context.  This returns NNG_ENOTSUP if the
 // protocol implementation does not support separate contexts.

diff --git a/src/core/aio_test.c b/src/core/aio_test.c
@@ -155,7 +155,7 @@ test_consumer_cancel(void)
 	NUTS_TRUE(nng_aio_result(a) == NNG_ECANCELED);
 
 	nng_aio_free(a);
-	NUTS_TRUE(nng_close(s1) == 0);
+	NUTS_CLOSE(s1);
 }
 
 void
@@ -207,8 +207,8 @@ test_traffic(void)
 
 	nng_aio_free(rx_aio);
 	nng_aio_free(tx_aio);
-	NUTS_PASS(nng_close(s1));
-	NUTS_PASS(nng_close(s2));
+	NUTS_CLOSE(s1);
+	NUTS_CLOSE(s2);
 }
 
 void
@@ -226,7 +226,7 @@ test_explicit_timeout(void)
 	NUTS_TRUE(done == 1);
 	NUTS_FAIL(nng_aio_result(a), NNG_ETIMEDOUT);
 	nng_aio_free(a);
-	NUTS_PASS(nng_close(s));
+	NUTS_CLOSE(s);
 }
 
 void
@@ -247,7 +247,7 @@ test_explicit_expiration(void)
 	NUTS_TRUE(done == 1);
 	NUTS_FAIL(nng_aio_result(a), NNG_ETIMEDOUT);
 	nng_aio_free(a);
-	NUTS_PASS(nng_close(s));
+	NUTS_CLOSE(s);
 }
 
 void
@@ -265,7 +265,7 @@ test_inherited_timeout(void)
 	NUTS_TRUE(done == 1);
 	NUTS_FAIL(nng_aio_result(a), NNG_ETIMEDOUT);
 	nng_aio_free(a);
-	NUTS_PASS(nng_close(s));
+	NUTS_CLOSE(s);
 }
 
 void
@@ -283,7 +283,7 @@ test_zero_timeout(void)
 	NUTS_TRUE(done == 1);
 	NUTS_FAIL(nng_aio_result(a), NNG_ETIMEDOUT);
 	nng_aio_free(a);
-	NUTS_PASS(nng_close(s));
+	NUTS_CLOSE(s);
 }
 
 static void

diff --git a/src/core/buf_size_test.c b/src/core/buf_size_test.c
@@ -43,7 +43,7 @@ test_buffer_options(void)
 		// Buffer sizes are limited to sane levels
 		NUTS_FAIL(nng_socket_set_int(s1, opt, 0x100000), NNG_EINVAL);
 	}
-	NUTS_PASS(nng_close(s1));
+	NUTS_CLOSE(s1);
 }
 
 NUTS_TESTS = {

diff --git a/src/core/socket.c b/src/core/socket.c
@@ -698,7 +698,7 @@ nni_sock_shutdown(nni_sock *sock)
 
 	// At this point, there are no threads blocked inside of us
 	// that are referencing socket state.  User code should call
-	// nng_close to release the last resources.
+	// nng_socket_close to release the last resources.
 	return (0);
 }
 

diff --git a/src/nng.c b/src/nng.c
@@ -26,7 +26,7 @@
 #include <string.h>
 
 int
-nng_close(nng_socket s)
+nng_socket_close(nng_socket s)
 {
 	int       rv;
 	nni_sock *sock;

diff --git a/src/sp/nonblock_test.c b/src/sp/nonblock_test.c
@@ -114,10 +114,10 @@ test_nonblocking(void)
 	}
 
 	nng_msleep(15000);
-	nng_close(rep);
+	nng_socket_close(rep);
 	nng_thread_destroy(server);
 	for (int i = 0; i < NCLIENTS; i++) {
-		nng_close(reqs[i]);
+		nng_socket_close(reqs[i]);
 		nng_thread_destroy(clients[i]);
 	}
 }

diff --git a/src/sp/pipe_test.c b/src/sp/pipe_test.c
@@ -143,8 +143,8 @@ init_cases(char *addr, struct testcase *push, struct testcase *pull)
 static void
 fini_cases(struct testcase *push, struct testcase *pull)
 {
-	nng_close(push->s);
-	nng_close(pull->s);
+	nng_socket_close(push->s);
+	nng_socket_close(pull->s);
 	nng_cv_free(push->cv);
 	nng_cv_free(pull->cv);
 	nng_mtx_free(push->lk);

diff --git a/src/sp/protocol/bus0/bus_test.c b/src/sp/protocol/bus0/bus_test.c
@@ -378,7 +378,7 @@ test_bus_cooked(void)
 	NUTS_PASS(nng_bus0_open(&s));
 	NUTS_PASS(nng_socket_raw(s, &b));
 	NUTS_TRUE(!b);
-	NUTS_PASS(nng_close(s));
+	NUTS_CLOSE(s);
 
 	// raw pub only differs in the option setting
 	NUTS_PASS(nng_bus0_open_raw(&s));