From 5fb0d00d9e69e80fe8dc65270316bfc416a0e0d3 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Tue, 31 Dec 2024 14:25:50 -0800 Subject: docs: nanomsg transition guide - set up links Most of these links don't go anywhere yet (waiting to be fleshed out), but at least they are filled out by the xrefs.md file. --- docs/ref/migrate/nanomsg.md | 82 ++++++++++++++++++++++----------------------- docs/ref/xref.md | 21 ++++++++++++ 2 files changed, 62 insertions(+), 41 deletions(-) diff --git a/docs/ref/migrate/nanomsg.md b/docs/ref/migrate/nanomsg.md index f7c6b971..47f82a9c 100644 --- a/docs/ref/migrate/nanomsg.md +++ b/docs/ref/migrate/nanomsg.md @@ -33,39 +33,39 @@ NNG approach to messages. Likewise there is no `struct nn_cmsghdr` equivalent. ## API Conversions -| Nanomsg API | NNG Equivalent | Notes | -| ------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------- | -| `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_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` | -| `nn_allocmsg` | [`nng_msg_alloc`] | There are significant semantic differences. | -| `nn_freemsg` | [`nng_msg_free`] | -| `nn_reallocmsg` | [`nng_msg_realloc`] | -| `nn_send` | `nng_send` | -| `nn_recv` | `nng_recv` | -| `nn_sendmsg` | `nng_sendmsg` | -| `nn_getsockopt` | `nng_socket_get` | NNG has typed accessors for options, and also separate functions for dialers and listeners. | -| `nn_setsockopt` | `nng_socket_set` | -| `nn_device` | `nng_device` | -| `nn_poll` | None | Can be constructed using `nng_aio`. Few if any applications ever used this API. | -| `nn_term` | None | The `nng_fini` API can do this, but is not recommended except when debugging memory leaks. | -| `nn_get_statistic` | `nng_stats_get` | The statistics in NNG are completely different, with different semantics and no stability guarantees. | -| `NN_POLLIN` | None | Used only with `nn_poll`. | -| `NN_POLLOUT` | None | Used only with `nn_poll`. | -| `NN_MSG` | `NNG_FLAG_ALLOC` | See `nng_send` and `nng_recv` for details. | -| `NN_CMSG_ALIGN` | None | -| `NN_CMSG_FIRSTHDR` | None | -| `NN_CMSG_NXTHDR` | None | -| `NN_CMSG_DATA` | None | -| `NN_CMSG_LEN` | None | -| `NN_CMSG_SPACE` | None | -| `struct nn_iovec` | `nng_iov` | -| `struct nn_msghdr` | [`nng_msg`] | -| `struct nn_cmsghdr` | [`nng_msg`] and [`nng_msg_header`] | +| Nanomsg API | NNG Equivalent | Notes | +| ------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------- | +| `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_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_listener_close`], [`nng_dialer_close`] | +| `nn_allocmsg` | [`nng_msg_alloc`] | There are significant semantic differences. | +| `nn_freemsg` | [`nng_msg_free`] | +| `nn_reallocmsg` | [`nng_msg_realloc`] | +| `nn_send` | [`nng_send`] | +| `nn_recv` | [`nng_recv`] | +| `nn_sendmsg` | [`nng_sendmsg`] | +| `nn_getsockopt` | [`nng_socket_get`] | NNG has typed accessors for options, and also separate functions for dialers and listeners. | +| `nn_setsockopt` | [`nng_socket_set`] | +| `nn_device` | [`nng_device`] | +| `nn_poll` | None | Can be constructed using `nng_aio`. Few if any applications ever used this API. | +| `nn_term` | [`nng_fini`] | The `nng_fini` API can do this, but is not recommended except when debugging memory leaks. | +| `nn_get_statistic` | [`nng_stats_get`] | The statistics in NNG are completely different, with different semantics and no stability guarantees. | +| `NN_POLLIN` | None | Used only with `nn_poll`. | +| `NN_POLLOUT` | None | Used only with `nn_poll`. | +| `NN_MSG` | [`NNG_FLAG_ALLOC`] | See `nng_send` and `nng_recv` for details. | +| `NN_CMSG_ALIGN` | None | +| `NN_CMSG_FIRSTHDR` | None | +| `NN_CMSG_NXTHDR` | None | +| `NN_CMSG_DATA` | None | +| `NN_CMSG_LEN` | None | +| `NN_CMSG_SPACE` | None | +| `struct nn_iovec` | [`nng_iov`] | +| `struct nn_msghdr` | [`nng_msg`] | +| `struct nn_cmsghdr` | [`nng_msg`] and [`nng_msg_header`] | ## Options @@ -74,12 +74,12 @@ The following options are changed. | Nanomsg Option | NNG Eqvaivalent | Notes | | ---------------------- | ------------------------------- | ------------------------------------------------------- | | `NN_LINGER` | None | NNG does not support tuning this. | -| `NN_SNDBUF` | `NNG_OPT_SENDBUF` | NNG value is given in messages, not bytes. | -| `NN_RCVBUF` | `NNG_OPT_RECVBUF` | NNG value is given in messages, not bytes. | -| `NN_SNDTIMEO` | `NNG_OPT_SENDTIMEO` | -| `NN_RCVTIMEO` | `NNG_OPT_RECVTIMEO` | -| `NN_RECONNECT_IVL` | `NNG_OPT_RECONNMINT` | -| `NN_RECONNECT_IVL_MAX` | `NNG_OPT_RECONNMAXT` | +| `NN_SNDBUF` | [`NNG_OPT_SENDBUF`] | NNG value is given in messages, not bytes. | +| `NN_RCVBUF` | [`NNG_OPT_RECVBUF`] | NNG value is given in messages, not bytes. | +| `NN_SNDTIMEO` | [`NNG_OPT_SENDTIMEO`] | +| `NN_RCVTIMEO` | [`NNG_OPT_RECVTIMEO`] | +| `NN_RECONNECT_IVL` | [`NNG_OPT_RECONNMINT`] | +| `NN_RECONNECT_IVL_MAX` | [`NNG_OPT_RECONNMAXT`] | | `NN_SNDPRIO` | None | Not supported in NNG yet. | | `NN_RCVPRIO` | None | Not supported in NNG yet. | | `NN_RCVFD` | [`nng_socket_get_recv_poll_fd`] | No longer an option, use a function call. | @@ -88,7 +88,7 @@ The following options are changed. | `NN_PROTOCOL` | [`nng_socket_proto_id`] | No longer an option. See also `nng_socket_proto_name`. | | `NN_IPV4ONLY` | None | Use URL such as `tcp4://` to obtain this functionality. | | `NN_SOCKET_NAME` | None | Removed from NNG. | -| `NN_MAXTTL` | `NNG_OPT_MAXTTL` | +| `NN_MAXTTL` | [`NNG_OPT_MAXTTL`] | | `NN_SUB_SUBSCRIBE` | [`nng_sub0_socket_subscribe`] | No longer an option, use a function call. | | `NN_SUB_UNSUBSCRIBE` | [`nng_sub0_socket_unsubscribe`] | No longer an option, use a function call. | @@ -123,7 +123,7 @@ There are some exceptions. Be aware that the numeric values are _not_ the same. ## Local Addresses for Dialing -The ability to specify the source address in the UROL,to use when +The ability to specify the source address in the URL,to use when using `nn_dial` inside the URL is not present in NNG. The correct way to specify the local address is using the `NNG_OPT_LOCADDR` option on the dialer before starting to dial. diff --git a/docs/ref/xref.md b/docs/ref/xref.md index 0dae482c..b790dcbd 100644 --- a/docs/ref/xref.md +++ b/docs/ref/xref.md @@ -158,6 +158,18 @@ [`nng_tls_config_own_cert`]: /TODO.md [`nng_listener_set_security_descriptor`]: /TODO.md [`nng_device`]: /TODO.md +[`nng_dial`]: /TODO.md +[`nng_dialer_create`]: /TODO.md +[`nng_dialer_close`]: /TODO.md +[`nng_listen`]: /TODO.md +[`nng_listener_create`]: /TODO.md +[`nng_listener_close`]: /TODO.md +[`nng_socket_set`]: /TODO.md +[`nng_socket_get`]: /TODO.md +[`nng_send`]: /TODO.md +[`nng_recv`]: /TODO.md +[`nng_sendmsg`]: /TODO.md +[`nng_recvmsg`]: /TODO.md @@ -213,6 +225,15 @@ [`NNG_UNIT_MESSAGES`]: /api/stats.md#statistic-units [`NNG_UNIT_MILLIS`]: /api/stats.md#statistic-units [`NNG_UNIT_EVENTS`]: /api/stats.md#statistic-units +[`NNG_FLAG_ALLOC`]: /TODO.md +[`NNG_FLAG_NONBLOCK`]: /TODO.md +[`NNG_OPT_MAXTTL`]: /TODO.md +[`NNG_OPT_RECONNMAXT`]: /TODO.md +[`NNG_OPT_RECONNMINT`]: /TODO.md +[`NNG_OPT_SENDTIMEO`]: /TODO.md +[`NNG_OPT_RECVTIMEO`]: /TODO.md +[`NNG_OPT_SENDBUF`]: /TODO.md +[`NNG_OPT_RECVBUF`]: /TODO.md -- cgit v1.2.3-70-g09d2