From 57e736b5be2052484eec44889586bd89a2724c71 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Fri, 3 Jan 2025 12:46:33 -0800 Subject: api: rename nng_send_aio and nng_recv_aio to nng_socket_send and nng_socket_recv This aligns more closely with the nng_ctx functions. --- docs/ref/api/ctx.md | 2 +- docs/ref/api/sock.md | 26 +++++++++++++------------- docs/ref/migrate/nng1.md | 13 +++++++++---- docs/ref/xref.md | 4 ++-- 4 files changed, 25 insertions(+), 20 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/api/ctx.md b/docs/ref/api/ctx.md index f1157def..b64ed3a1 100644 --- a/docs/ref/api/ctx.md +++ b/docs/ref/api/ctx.md @@ -150,7 +150,7 @@ The `nng_ctx_recvmsg` function receives a message and stores a pointer to the [` The _flags_ can contain the value [`NNG_FLAG_NONBLOCK`], indicating that the function should not wait if the socket has no messages available to receive. In such a case, it will return [`NNG_EAGAIN`]. -### nng_recv_aio +### nng_socket_recv The `nng_ctx_send` function receives a message asynchronously, using the [`nng_aio`] _aio_, over the context _ctx_. On success, the received message can be retrieved from the _aio_ using the [`nng_aio_get_msg`] function. diff --git a/docs/ref/api/sock.md b/docs/ref/api/sock.md index 61a88ab5..4ebd8051 100644 --- a/docs/ref/api/sock.md +++ b/docs/ref/api/sock.md @@ -154,10 +154,10 @@ a result of [`NNG_ECLOSED`]. ```c int nng_send(nng_socket s, void *data, size_t size, int flags); int nng_sendmsg(nng_socket s, nng_msg *msg, int flags); -void nng_send_aio(nng_socket s, nng_aio *aio); +void nng_socket_send(nng_socket s, nng_aio *aio); ``` -These functions ({{i:`nng_send`}}, {{i:`nng_sendmsg`}}, and {{i:`nng_send_aio`}}) send +These functions ({{i:`nng_send`}}, {{i:`nng_sendmsg`}}, and {{i:`nng_socket_send`}}) send messages over the socket _s_. The differences in their behaviors are as follows. > [!NOTE] @@ -198,9 +198,9 @@ cannot accept more data for sending. In such a case, it will return [`NNG_EAGAIN > This function is preferred over [`nng_send`], as it gives access to the message structure and eliminates both > a data copy and allocation. -### nng_send_aio +### nng_socket_send -The `nng_send_aio` function sends a message asynchronously, using the [`nng_aio`] _aio_, over the socket _s_. +The `nng_socket_send` function sends a message asynchronously, using the [`nng_aio`] _aio_, over the socket _s_. The message to send must have been set on _aio_ using the [`nng_aio_set_msg`] function. If the operation completes successfully, then the socket will have disposed of the message. @@ -220,10 +220,10 @@ For example, the message may be sitting in queue, or located in TCP buffers, or ```c int nng_recv(nng_socket s, void *data, size_t *sizep, int flags); int nng_recvmsg(nng_socket s, nng_msg **msgp, int flags); -void nng_recv_aio(nng_socket s, nng_aio *aio); +void nng_socket_recv(nng_socket s, nng_aio *aio); ``` -These functions ({{i:`nng_recv`}}, {{i:`nng_recvmsg`}}, and {{i:`nng_recv_aio`}}) receive +These functions ({{i:`nng_recv`}}, {{i:`nng_recvmsg`}}, and {{i:`nng_socket_recv`}}) receive messages over the socket _s_. The differences in their behaviors are as follows. > [!NOTE] @@ -257,9 +257,9 @@ has no messages available to receive. In such a case, it will return [`NNG_EAGAI > This function is preferred over [`nng_recv`], as it gives access to the message structure and eliminates both > a data copy and allocation. -### nng_recv_aio +### nng_socket_recv -The `nng_send_aio` function receives a message asynchronously, using the [`nng_aio`] _aio_, over the socket _s_. +The `nng_socket_send` function receives a message asynchronously, using the [`nng_aio`] _aio_, over the socket _s_. On success, the received message can be retrieved from the _aio_ using the [`nng_aio_get_msg`] function. > [!NOTE] @@ -371,7 +371,7 @@ nng_socket s = NNG_SOCKET_INITIALIZER; ### Example 2: Publishing a Timestamp -This example demonstrates the use of [`nng_aio`], [`nng_send_aio`], and [`nng_sleep_aio`] to +This example demonstrates the use of [`nng_aio`], [`nng_socket_send`], and [`nng_sleep_aio`] to build a service that publishes a timestamp at one second intervals. Error handling is elided for the sake of clarity. @@ -403,7 +403,7 @@ void callback(void *arg) { now = nng_clock(); nng_msg_append(msg, &now, sizeof (now)); // note: native endian nng_aio_set_msg(state->aio, msg); - nng_send_aio(state->s, state->aio); + nng_socket_send(state->s, state->aio); } else { state->sleeping = true; nng_sleep_aio(1000, state->aio); // 1000 ms == 1 second @@ -426,7 +426,7 @@ int main(int argc, char **argv) { ### Example 3: Watching a Periodic Timestamp -This example demonstrates the use of [`nng_aio`], [`nng_recv_aio`], to build a client to +This example demonstrates the use of [`nng_aio`], [`nng_socket_recv`], to build a client to watch for messages received from the service created in Example 2. Error handling is elided for the sake of clarity. @@ -457,7 +457,7 @@ void callback(void *arg) { printf("Timestamp is %lu\n", (unsigned long)now); nng_msg_free(msg); nng_aio_set_msg(state->aio, NULL); - nng_recv_aio(state->s, state->aio); + nng_socket_recv(state->s, state->aio); } int main(int argc, char **argv) { @@ -467,7 +467,7 @@ int main(int argc, char **argv) { nng_sub0_open(&state.s); nng_sub0_socket_subscribe(state.s, NULL, 0); // subscribe to everything nng_dial(state.s, url, NULL, 0); - nng_recv_aio(state.s, state.aio); // kick it off right away + nng_socket_recv(state.s, state.aio); // kick it off right away for(;;) { nng_msleep(0x7FFFFFFF); // infinite, could use pause or sigsuspend } diff --git a/docs/ref/migrate/nng1.md b/docs/ref/migrate/nng1.md index 8306e71f..74350ec0 100644 --- a/docs/ref/migrate/nng1.md +++ b/docs/ref/migrate/nng1.md @@ -15,9 +15,14 @@ This is done using the [`nng_init`] function. ## Renamed Functions -The `nng_close` function has been renamed to [`nng_socket_close`] to make it clearer that -the object being closed is a socket. A compatible `nng_close` macro is available by defining `NNG1_TRANSITION` -in your compilation environment. +The following functions have been renamed as described by the following table. +The old names are available by defining the macro `NNG1_TRANSITION` in your compilation environment. + +| Old Name | New Name | +| -------------- | -------------------- | +| `nng_close` | [`nng_socket_close`] | +| `nng_recv_aio` | [`nng_socket_recv`] | +| `nng_send_aio` | [`nng_socket_send`] | ## Removed Protocol Aliases @@ -46,7 +51,7 @@ The `NNG_FLAG_ALLOC` flag that allowed a zero copy semantic with [`nng_send`] an This was implemented mostly to aid legacy nanomsg applications, and it was both error prone and still a bit suboptimal in terms of performance. -Modern code should use one of [`nng_sendmsg`], [`nng_recvmsg`], [`nng_send_aio`], or [`nng_recv_aio`] to get the maximum performance benefit. +Modern code should use one of [`nng_sendmsg`], [`nng_recvmsg`], [`nng_socket_send`], or [`nng_socket_recv`] to get the maximum performance benefit. Working directly with [`nng_msg`] structures gives more control, reduces copies, and reduces allocation activity. ## New AIO Error Code NNG_ESTOPPED diff --git a/docs/ref/xref.md b/docs/ref/xref.md index 62f09540..f117edf7 100644 --- a/docs/ref/xref.md +++ b/docs/ref/xref.md @@ -223,10 +223,10 @@ [`nng_socket_get_size`]: /api/sock.md#socket-options [`nng_send`]: /api/sock.md#nng_send [`nng_sendmsg`]: /api/sock.md#nng_sendmsg -[`nng_send_aio`]: /api/sock.md#nng_send_aio +[`nng_socket_send`]: /api/sock.md#nng_socket_send [`nng_recv`]: /api/sock.md#nng_recv [`nng_recvmsg`]: /api/sock.md#nng_recvmsg -[`nng_recv_aio`]: /api/sock.md#nng_recv_aio +[`nng_socket_recv`]: /api/sock.md#nng_socket_recv [`nng_ctx_open`]: /api/ctx.md#creating-a-context [`nng_ctx_id`]: /api/ctx.md#context-identity [`nng_ctx_close`]: /api/ctx.md#closing-a-context -- cgit v1.2.3-70-g09d2