diff options
Diffstat (limited to 'docs/ref')
| -rw-r--r-- | docs/ref/SUMMARY.md | 5 | ||||
| -rw-r--r-- | docs/ref/migrate/index.md | 7 | ||||
| -rw-r--r-- | docs/ref/migrate/nanomsg.md | 115 | ||||
| -rw-r--r-- | docs/ref/migrate/nng1.md | 56 |
4 files changed, 183 insertions, 0 deletions
diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md index dabdcf1f..9cb0de6a 100644 --- a/docs/ref/SUMMARY.md +++ b/docs/ref/SUMMARY.md @@ -55,4 +55,9 @@ - [BSD Socket (Experimental)](./tran/socket.md) - [UDP Transport (Experimental)](./tran/udp.md) +- [Migration Guides](./migrate/index.md) + + - [Migrating from NNG 1.x](./migrate/nng1.md) + - [Migrating from libnanomsg](./migrate/nanomsg.md) + [Index](./indexing.md) diff --git a/docs/ref/migrate/index.md b/docs/ref/migrate/index.md new file mode 100644 index 00000000..29d2d893 --- /dev/null +++ b/docs/ref/migrate/index.md @@ -0,0 +1,7 @@ +# Migration Guides + +This section provides some guides to aid in migrating software from +earlier versions _NNG_ or _libnanomsg_. + +- [Migrating from NNG 1.x](./migrate/nng1.md) +- [Migrating from libnanomsg](./migrate/nanomsg.md) diff --git a/docs/ref/migrate/nanomsg.md b/docs/ref/migrate/nanomsg.md new file mode 100644 index 00000000..e4c7b184 --- /dev/null +++ b/docs/ref/migrate/nanomsg.md @@ -0,0 +1,115 @@ +# Migrating from libnanomsg + +Previous version of NNG offered direct API compatibility with _libnanomsg_, +but that support is no longer offered in this version. + +If your application is still using legacy _libnanomsg_ APIs, you will need to +update it for this version of NNG. + +## Header Files + +Most applications can replace all `#include <nn/*.h>` statements with `#include <nng/nng.h>`. + +## Link Libraries + +Replace `-lnanomsg` with `-lnng`. +It may be necessary to include additional system libraries, such as `-lpthread`, depending on your system. + +## Types + +Sockets, dialers, and listeners in _libnanomsg_ are simple integers. +In NNG, these are `struct` types. + +Messages are quite different in NNG, with the absence of the POSIX message control +headers. + +The `struct nn_msghdr` structure has no equivalent. See `nng_msg` for the +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` | No equivalent. Errors are redirectly rather than through `errno`. | +| `nn_socket` | Use the appropriate protocol constructor, such as `nng_req0_open`. | +| `nn_close` | `nng_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` | + +## Options + +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_SNDPRIO` | None | Not supported in NNG yet. | +| `NN_RCVPRIO` | None | Not supported in NNG yet. | +| `NN_RCVFD` | `NNG_OPT_RECVFD` | +| `NN_SNDFD` | `NNG_OPT_SENDFD` | +| `NN_DOMAIN` | None | NNG options are not divided by domain or protocol. | +| `NN_PROTOCOL` | `NNG_OPT_PROTO` | See also `NNG_OPT_PROTONAME`. | +| `NN_IPV4ONLY` | None | Use URL such as `tcp4://` to obtain this functionality. | +| `NN_SOCKET_NAME` | `NNG_OPT_SOCKNAME` | +| `NN_MAXTTL` | `NNG_OPT_MAXTTL` | + +## Error Codes + +Most of the error codes have similar names in NNG, just prefixed with `NNG_`. +There are some exceptions. Be aware that the numeric values are _not_ the same. + +| Nanomsg Error | NNG Error | Notes | +| -------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | +| `EINTR` | `NNG_EINTR` | | +| `ENOMEM` | `NNG_ENOMEM` | | +| `EINVAL` | `NNG_EINVAL`, `NNG_EADDRINVAL`, `NNG_EBADTYPE`, `NNG_EAMBIGUOUS` | NNG discrimates between different types of errors. | +| `EBUSY` | `NNG_EBUSY` | | +| `ETIMEDOUT` | `NNG_ETIMEDOUT` | | +| `ECONNREFUSED` | `NNG_ECONNREFUSED` | | +| `EBADF` | `NNG_ECLOSED`, `NNG_ECANCELED` | Canceling an operation returns differently than using an invalid or closed object. | +| `EAGAIN` | `NNG_EAGAIN` | +| `ENOTSUP` | `NNG_ENOTSUP` | +| `EADDRINUSE` | `NNG_EADDRINUSE` | +| `EFSM` | `NNG_ESTATE` | Not a legal POSIX _errno_ value. | +| `ENOENT` | `NNG_ENOENT` | +| `EPROTO` | `NNG_EPROTO` | +| `EHOSTUNREACH` | `NNG_EUNREACHABLE` | +| `EACCCES` | `NNG_EPERM`, `NNG_EWRITEONLY`, `NNG_EREADONLY`, `NNG_ECRYPTO`, `NNG_EPEERAUTH` | NNG has more fine grained reasons for access failures. | +| `EMSGSIZE` | `NNG_EMSGSIZE` | +| `ECONNABORTED` | `NNG_ECONNABORTED` | +| `ECONNRESET` | `NNG_ECONNRESET` | +| `EEXIST` | `NNG_EEXIST` | +| `EMFILE` | `NNG_ENOFILES` | +| `ENOSPC` | `NNG_ENOSPC` | diff --git a/docs/ref/migrate/nng1.md b/docs/ref/migrate/nng1.md new file mode 100644 index 00000000..6cf605f3 --- /dev/null +++ b/docs/ref/migrate/nng1.md @@ -0,0 +1,56 @@ +# Migrating from NNG 1.x + +There are some incompatibities from NNG 1.x. +This guide should help in migrating applications to use NNG 2.0. + +## Nanomsg Compatibility + +Applications using the legacy `libnanomsg` API will have to be updated to native _NNG_ interfaces. +See the [Migrating From libnanomsg](nanomsg.md) chapter for details. + +## Transport Specific Functions + +Transports have not needed to be registered for a long time now, +and the functions for doing so have been removed. These functions +can be simply removed from your application: + +- `nng_inproc_register` +- `nng_ipc_register` +- `nng_tls_register` +- `nng_tcp_register` +- `nng_ws_register` +- `nng_wss_register` +- `nng_zt_register` + +Additionally, the header files containing these functions have been removed, such as +`nng/transport/ipc/ipc.h`. Simply remove `#include` references to those files. + +(Special exception: The options for ZeroTier are still located in the +`nng/transport/zerotier/zerotier.h`.) + +The `NNG_OPT_WSS_REQUEST_HEADERS` and `NNG_OPT_WSS_RESPONSE_HEADERS` aliases for +`NNG_OPT_WS_OPT_WS_REQUEST_HEADERS` and `NNG_OPT_WS_RESPONSE_HEADERS` have been removed. +Just convert any use of them to `NNG_OPT_WS_REQUST_HEADERS` or +`NNG_OPT_WS_RESPOSNE_HEADERS` as appropriate. + +## Option Functions + +The previously deprecated `nng_pipe_getopt_xxx` family of functions is removed. +Applications should use `nng_pipe_get` and related functions instead. + +The socket option function families for `nng_getopt` and `nng_setopt` have been removed as well. +In this case, use the `nng_socket_get` and `nng_socket_set` functions as appropriate. + +## Transport Options + +A number of transport options can no longer be set on the socket. Instead these +options must be set on the endpoint (dialer or listener) using the appropriate +`nng_dialer_set` or `nng_listener_set` option. This likely means that it is necessary +to allocate and configure the endpoint before attaching it to the socket. This will +also afford a much more fine-grained level of control over transport options. + +## Statistics Use Constified Pointers + +A number of the statistics functions take, or return, `const nng_stat *` instead +of plain `nng_stat *`. The ABI has not changed, but it may be necessary to declare +certain methods variables `const` to avoid warnings about misuse of `const`. |