From edd3b6bc34f211bd3d58642d0c69ce1b5bb9dc3b Mon Sep 17 00:00:00 2001 From: gdamore Date: Thu, 9 Oct 2025 01:22:20 +0000 Subject: deploy: 9c834956456924df7c885ab8b79573721acaff5c --- ref/migrate/nanomsg.html | 108 +++++++++++++++++++++++------------------------ ref/migrate/nng1.html | 90 +++++++++++++++++++-------------------- 2 files changed, 99 insertions(+), 99 deletions(-) (limited to 'ref/migrate') diff --git a/ref/migrate/nanomsg.html b/ref/migrate/nanomsg.html index 28c9eae7..eabe1549 100644 --- a/ref/migrate/nanomsg.html +++ b/ref/migrate/nanomsg.html @@ -254,7 +254,7 @@ update it for this version of NNG.

Replace -lnanomsg with -lnng. It may be necessary to include additional system libraries, such as -lpthread, depending on your system.

Initialization

-

It is necessary to explicitly initialize the library, using the nng_init function. +

It is necessary to explicitly initialize the library, using the nng_init function. This must be called before any other function.

Types

Sockets, dialers, and listeners in libnanomsg are simple integers. @@ -265,87 +265,87 @@ headers.

NNG approach to messages. Likewise there is no struct nn_cmsghdr equivalent.

API Conversions

- + - - - - - - - - - - - - - + + + + + + + + + + + + + - - + + - + - - - + + +
Nanomsg APINNG EquivalentNotes
nn_strerrornng_strerror
nn_strerrornng_strerror
nn_errnoNoneErrors are returned directly rather than through errno.
nn_socketVariousUse the appropriate protocol constructor, such as nng_req0_open.
nn_closenng_socket_close
nn_bindnng_listen, nng_listener_createAllocating a listener with nng_lister_create and configuring it offers more capabilities.
nn_connectnng_dial, nng_dialer_createAllocating a dialer with nng_dialer_create and configuring it offers more capabilities.
nn_shutdownnng_listener_close, nng_dialer_close
nn_allocmsgnng_msg_allocThere are significant semantic differences.
nn_freemsgnng_msg_free
nn_reallocmsgnng_msg_realloc
nn_sendnng_send
nn_recvnng_recv
nn_sendmsgnng_sendmsg
nn_getsockoptnng_socket_getNNG has typed accessors for options, and also separate functions for dialers and listeners.
nn_setsockoptnng_socket_set
nn_devicenng_device
nn_closenng_socket_close
nn_bindnng_listen, nng_listener_createAllocating a listener with nng_lister_create and configuring it offers more capabilities.
nn_connectnng_dial, nng_dialer_createAllocating a dialer with nng_dialer_create and configuring it offers more capabilities.
nn_shutdownnng_listener_close, nng_dialer_close
nn_allocmsgnng_msg_allocThere are significant semantic differences.
nn_freemsgnng_msg_free
nn_reallocmsgnng_msg_realloc
nn_sendnng_send
nn_recvnng_recv
nn_sendmsgnng_sendmsg
nn_getsockoptnng_socket_getNNG has typed accessors for options, and also separate functions for dialers and listeners.
nn_setsockoptnng_socket_set
nn_devicenng_device
nn_pollNoneCan be constructed using nng_aio. Few if any applications ever used this API.
nn_termnng_finiThe nng_fini API can do this, but is not recommended except when debugging memory leaks.
nn_get_statisticnng_stats_getThe statistics in NNG are completely different, with different semantics and no stability guarantees.
nn_termnng_finiThe nng_fini API can do this, but is not recommended except when debugging memory leaks.
nn_get_statisticnng_stats_getThe statistics in NNG are completely different, with different semantics and no stability guarantees.
NN_POLLINNoneUsed only with nn_poll.
NN_POLLOUTNoneUsed only with nn_poll.
NN_MSGnng_sendmsg, nng_recvmsgThere are differences as a separate nng_msg structure is involved.
NN_MSGnng_sendmsg, nng_recvmsgThere are differences as a separate nng_msg structure is involved.
NN_CMSG_ALIGNNone
NN_CMSG_FIRSTHDRNone
NN_CMSG_NXTHDRNone
NN_CMSG_DATANone
NN_CMSG_LENNone
NN_CMSG_SPACENone
struct nn_iovecnng_iov
struct nn_msghdrnng_msg
struct nn_cmsghdrnng_msg and nng_msg_header
struct nn_iovecnng_iov
struct nn_msghdrnng_msg
struct nn_cmsghdrnng_msg and nng_msg_header

Options

The following options are changed.

- - - - - - + + + + + + - - + + - + - - - + + +
Nanomsg OptionNNG EqvaivalentNotes
NN_LINGERNoneNNG does not support tuning this.
NN_SNDBUFNNG_OPT_SENDBUFNNG value is given in messages, not bytes.
NN_RCVBUFNNG_OPT_RECVBUFNNG value is given in messages, not bytes.
NN_SNDTIMEONNG_OPT_SENDTIMEO
NN_RCVTIMEONNG_OPT_RECVTIMEO
NN_RECONNECT_IVLNNG_OPT_RECONNMINT
NN_RECONNECT_IVL_MAXNNG_OPT_RECONNMAXT
NN_SNDBUFNNG_OPT_SENDBUFNNG value is given in messages, not bytes.
NN_RCVBUFNNG_OPT_RECVBUFNNG value is given in messages, not bytes.
NN_SNDTIMEONNG_OPT_SENDTIMEO
NN_RCVTIMEONNG_OPT_RECVTIMEO
NN_RECONNECT_IVLNNG_OPT_RECONNMINT
NN_RECONNECT_IVL_MAXNNG_OPT_RECONNMAXT
NN_SNDPRIONoneNot supported in NNG yet.
NN_RCVPRIONoneNot supported in NNG yet.
NN_RCVFDnng_socket_get_recv_poll_fdNo longer an option, use a function call.
NN_SNDFDnng_socket_get_send_poll_fdNo longer an option, use a function call.
NN_RCVFDnng_socket_get_recv_poll_fdNo longer an option, use a function call.
NN_SNDFDnng_socket_get_send_poll_fdNo longer an option, use a function call.
NN_DOMAINNoneNNG options are not divided by domain or protocol.
NN_PROTOCOLnng_socket_proto_idNo longer an option. See also nng_socket_proto_name.
NN_PROTOCOLnng_socket_proto_idNo longer an option. See also nng_socket_proto_name.
NN_IPV4ONLYNoneUse URL such as tcp4:// to obtain this functionality.
NN_SOCKET_NAMENoneRemoved from NNG.
NN_MAXTTLNNG_OPT_MAXTTL
NN_SUB_SUBSCRIBEnng_sub0_socket_subscribeNo longer an option, use a function call.
NN_SUB_UNSUBSCRIBEnng_sub0_socket_unsubscribeNo longer an option, use a function call.
NN_MAXTTLNNG_OPT_MAXTTL
NN_SUB_SUBSCRIBEnng_sub0_socket_subscribeNo longer an option, use a function call.
NN_SUB_UNSUBSCRIBEnng_sub0_socket_unsubscribeNo longer an option, use a function call.

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 ErrorNNG ErrorNotes
EINTRNNG_EINTR
ENOMEMNNG_ENOMEM
EINVALNNG_EINVAL, NNG_EADDRINVAL, NNG_EBADTYPENNG discrimates between different types of errors.
EBUSYNNG_EBUSY
ETIMEDOUTNNG_ETIMEDOUT
ECONNREFUSEDNNG_ECONNREFUSED
EBADFNNG_ECLOSED, NNG_ECANCELEDCanceling an operation returns differently than using an invalid or closed object.
EAGAINNNG_EAGAIN
ENOTSUPNNG_ENOTSUP
EADDRINUSENNG_EADDRINUSE
EFSMNNG_ESTATENot a legal POSIX errno value.
ENOENTNNG_ENOENT
EPROTONNG_EPROTO
EHOSTUNREACHNNG_EUNREACHABLE
EACCCESNNG_EPERM, NNG_EWRITEONLY, NNG_EREADONLY, NNG_ECRYPTO, NNG_EPEERAUTHNNG has more fine grained reasons for access failures.
EMSGSIZENNG_EMSGSIZE
ECONNABORTEDNNG_ECONNABORTED
ECONNRESETNNG_ECONNRESET
EEXISTNNG_EEXIST
EMFILENNG_ENOFILES
ENOSPCNNG_ENOSPC
EINTRNNG_EINTR
ENOMEMNNG_ENOMEM
EINVALNNG_EINVAL, NNG_EADDRINVAL, NNG_EBADTYPENNG discrimates between different types of errors.
EBUSYNNG_EBUSY
ETIMEDOUTNNG_ETIMEDOUT
ECONNREFUSEDNNG_ECONNREFUSED
EBADFNNG_ECLOSED, NNG_ECANCELEDCanceling an operation returns differently than using an invalid or closed object.
EAGAINNNG_EAGAIN
ENOTSUPNNG_ENOTSUP
EADDRINUSENNG_EADDRINUSE
EFSMNNG_ESTATENot a legal POSIX errno value.
ENOENTNNG_ENOENT
EPROTONNG_EPROTO
EHOSTUNREACHNNG_EUNREACHABLE
EACCCESNNG_EPERM, NNG_EWRITEONLY, NNG_EREADONLY, NNG_ECRYPTO, NNG_EPEERAUTHNNG has more fine grained reasons for access failures.
EMSGSIZENNG_EMSGSIZE
ECONNABORTEDNNG_ECONNABORTED
ECONNRESETNNG_ECONNRESET
EEXISTNNG_EEXIST
EMFILENNG_ENOFILES
ENOSPCNNG_ENOSPC

Local Addresses for Dialing

diff --git a/ref/migrate/nng1.html b/ref/migrate/nng1.html index cf8f81ca..7c96bbe2 100644 --- a/ref/migrate/nng1.html +++ b/ref/migrate/nng1.html @@ -264,7 +264,7 @@ between releases or builds of NNG 2.

See the Migrating From libnanomsg chapter for details.

Library Initialization

It is now required for applications to initialize the library explicitly before using it. -This is done using the nng_init function.

+This is done using the nng_init function.

Removed Headers

The following header files are removed, and the declarations they provided are now provided by including <nng/nng.h>. Simply remove any references to them.

@@ -294,9 +294,9 @@ Simply remove any references to them.

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 NameNew Name
nng_closenng_socket_close
nng_recv_aionng_socket_recv
nng_send_aionng_socket_send
nng_closenng_socket_close
nng_recv_aionng_socket_recv
nng_send_aionng_socket_send

Removed Protocol Aliases

@@ -316,13 +316,13 @@ The old names are available by defining the macro NNG1_TRANSITION i

Just add either 0 or 1 (in the case of PAIRv1) to get the protocol desired. (Forcing the version number to be supplied should avoid surprises later as new versions of protocols are added.)

NNG_FLAG_ALLOC Removed

-

The NNG_FLAG_ALLOC flag that allowed a zero copy semantic with nng_send and nng_recv is removed. +

The NNG_FLAG_ALLOC flag that allowed a zero copy semantic with nng_send and nng_recv is removed. 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_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.

+

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.

Error Code Changes

-

When an operation fails with NNG_ESTOPPED, it means that the associated [nni_aio] object has +

When an operation fails with NNG_ESTOPPED, it means that the associated [nni_aio] object has been permanently stopped and must not be reused. Applications must watch for this error code, and not resubmit an operation that returns it. This is particularly important for callbacks that automatically resubmit operations. Failure to observe this rule will lead to an infinite loop @@ -331,9 +331,9 @@ as any further operations on the object will fail immediately with NNG_EST

AIO Provider API changes

The API used for providers for asynchronous I/O operations has changed slightly.

The following API calls have changed so that they are void returns, and cannot fail. They may silently truncate data.

The HTTP handler objects may not be modified once in use. Previously this would fail with NNG_EBUSY. These checks are removed now, but debug builds will assert if an application tries to do so.

@@ -566,7 +566,7 @@ support for security descriptors altogether in NNG.

Command Line Argument Parser Changes

The supplemental function nng_opts_parse and supporting definitions have moved. This functionality is now supplied by a header only library, available in nng/args.h. -See nng_args_parse for more information.

+See nng_args_parse for more information.

ZeroTier Support Removed

The Layer 2 special ZeroTier transport has been removed. It is possible to use NNG with ZeroTier using TCP/IP, and a future update -- cgit v1.2.3-70-g09d2