= nng_compat(3compat)
|
//
|
// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
|
// Copyright 2018 Capitar IT Group BV <info@capitar.com>
|
//
|
// This document is supplied under the terms of the MIT License, a
|
// copy of which should be located in the distribution where this
|
// file was obtained (LICENSE.txt). A copy of the license may also be
|
// found online at https://opensource.org/licenses/MIT.
|
//
|
|
== NAME
|
|
nng_compat - compatibility with nanomsg 1.0
|
|
== SYNOPSIS
|
|
[source, c]
|
----
|
#include <nanomsg/nn.h>
|
|
#include <nanomsg/bus.h>
|
#include <nanomsg/pair.h>
|
#include <nanomsg/pipeline.h>
|
#include <nanomsg/pubsub.h>
|
#include <nanomsg/reqrep.h>
|
#include <nanomsg/survey.h>
|
|
#include <nanomsg/inproc.h>
|
#include <nanomsg/ipc.h>
|
#include <nanomsg/tcp.h>
|
#include <nanomsg/ws.h>
|
----
|
|
== DESCRIPTION
|
|
(((compatibility layer)))
|
xref:nng.7.adoc[_NNG_] provides source-level compatibility for
|
most _libnanomsg_ 1.0 applications.
|
|
IMPORTANT: This is intended to facilitate converting ((legacy applications)) to
|
use _NNG_.
|
New applications should use the newer xref:nng.7.adoc[_NNG_] API instead.
|
|
Applications making use of this must take care
|
to link with xref:libnng.3.adoc[_libnng_] instead of _libnn_.
|
|
TIP: While not recommended for long term use, the value returned by
|
xref:nng_socket_id.3.adoc[`nng_socket_id()`] can be used with these functions
|
just like a value returned by xref:nn_socket.3compat.adoc[`nn_socket()`].
|
This can be way to facilitate incremental transition to the new API.
|
|
NOTE: Some capabilities, protocols, and transports, will not be accessible
|
using this API, as the compatible API has no provision for expression
|
of certain concepts introduced in the new API.
|
|
NOTE: While reasonable efforts have been made to provide for compatibility,
|
some things may behave differently, and some less common parts of the
|
_libnanomsg_ 1.0 API are not supported at this time, including certain
|
options and the statistics API.
|
See the <<Caveats>> section below.
|
|
=== Compiling
|
|
When compiling legacy _nanomsg_ applications, it will generally be
|
necessary to change the include search path to add the `compat` subdirectory
|
of the directory where headers were installed.
|
For example, if _NNG_ is installed in `$prefix`, then header files will
|
normally be located in `$prefix/include/nng`.
|
In this case, to build legacy _nanomsg_ apps against _NNG_ you would
|
add `$prefix/include/nng/compat` to your compiler's search path.
|
|
Alternatively, you can change your source code so that `#include` statements
|
referring to `<nanomsg>` instead refer to `<nng/compat/nanomsg>`.
|
For example, instead of:
|
|
[source,c]
|
----
|
#include <nanomsg/nn.h>
|
#include <nanomsg/reqrep.h>
|
----
|
|
you would have this:
|
|
[source,c]
|
----
|
#include <nng/compat/nanomsg/nn.h>
|
#include <nng/compat/nanomsg/reqrep.h>
|
----
|
|
Legacy applications built using these methods should be linked against _libnng_
|
instead of _libnn_, just like any other _NNG_ application.
|
|
=== Functions
|
|
The following functions are provided:
|
|
// For PDF, we don't have horizontal lists, so we have to conditionalize
|
// this and use tables there -- it looks ugly otherwise.
|
ifndef::backend-pdf[]
|
[horizontal]
|
xref:nn_socket.3compat.adoc[`nn_socket()`]:: create socket
|
xref:nn_getsockopt.3compat.adoc[`nn_getsockopt()`]:: get socket option
|
xref:nn_setsockopt.3compat.adoc[`nn_setsockopt()`]:: set socket option
|
xref:nn_bind.3compat.adoc[`nn_bind()`]:: accept connections from remote peers
|
xref:nn_connect.3compat.adoc[`nn_connect()`]:: connect to remote peer
|
xref:nn_send.3compat.adoc[`nn_send()`]:: send data
|
xref:nn_recv.3compat.adoc[`nn_recv()`]:: receive data
|
xref:nn_shutdown.3compat.adoc[`nn_shutdown()`]:: shut down endpoint
|
xref:nn_close.3compat.adoc[`nn_close()`]:: close socket
|
xref:nn_poll.3compat.adoc[`nn_poll()`]:: poll sockets
|
xref:nn_device.3compat.adoc[`nn_device()`]:: create forwarding device
|
xref:nn_recvmsg.3compat.adoc[`nn_recvmsg()`]:: receive message
|
xref:nn_sendmsg.3compat.adoc[`nn_sendmsg()`]:: send message
|
xref:nn_cmsg.3compat.adoc[`nn_cmsg()`]:: message control data
|
xref:nn_get_statistic.3compat.adoc[`nn_get_statistic()`]:: get statistic (stub)
|
xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`]:: allocate message
|
xref:nn_reallocmsg.3compat.adoc[`nn_reallocmsg()`]:: reallocate message
|
xref:nn_freemsg.3compat.adoc[`nn_freemsg()`]:: free message
|
xref:nn_errno.3compat.adoc[`nn_errno()`]:: return most recent error
|
xref:nn_strerror.3compat.adoc[`nn_strerror()`]:: return message for error
|
xref:nn_term.3compat.adoc[`nn_term()`]:: terminate library
|
endif::[]
|
ifdef::backend-pdf[]
|
// Add links for the following as they are written.
|
[.hdlist,width=90%, grid=rows,cols="1,2", align="center"]
|
|===
|
|xref:nn_socket.3compat.adoc[`nn_socket()`]|create socket
|
|xref:nn_getsockopt.3compat.adoc[`nn_getsockopt()`]|get socket option
|
|xref:nn_setsockopt.3compat.adoc[`nn_setsockopt()`]|set socket option
|
|xref:nn_bind.3compat.adoc[`nn_bind()`]|accept connections from remote peers
|
|xref:nn_connect.3compat.adoc[`nn_connect()`]|connect to remote peer
|
|xref:nn_send.3compat.adoc[`nn_send()`]|send data
|
|xref:nn_recv.3compat.adoc[`nn_recv()`]|receive data
|
|xref:nn_shutdown.3compat.adoc[`nn_shutdown()`]|shut down endpoint
|
|xref:nn_close.3compat.adoc[`nn_close()`]|close socket
|
|xref:nn_poll.3compat.adoc[`nn_poll()`]|poll sockets
|
|xref:nn_device.3compat.adoc[`nn_device()`]|create forwarding device
|
|xref:nn_recvmsg.3compat.adoc[`nn_recvmsg()`]|receive message
|
|xref:nn_sendmsg.3compat.adoc[`nn_sendmsg()`]|send message
|
|xref:nn_cmsg.3compat.adoc[`nn_cmsg()`]|message control data
|
|xref:nn_get_statistic.3compat.adoc[`nn_get_statistic()`]|get statistic (stub)
|
|xref:nn_allocmsg.3compat.adoc[`nn_allocmsg()`]|allocate message
|
|xref:nn_reallocmsg.3compat.adoc[`nn_reallocmsg()`]|reallocate message
|
|xref:nn_freemsg.3compat.adoc[`nn_freemsg()`]|free message
|
|xref:nn_errno.3compat.adoc[`nn_errno()`]|return most recent error
|
|xref:nn_strerror.3compat.adoc[`nn_strerror()`]|return message for error
|
|xref:nn_term.3compat.adoc[`nn_term()`]|terminate library
|
|===
|
endif::[]
|
|
=== Caveats
|
|
The following caveats apply when using the legacy API with _NNG_.
|
|
* Socket numbers can be quite large.
|
The legacy _libnanomsg_ attempted to reuse socket numbers, like
|
file descriptors in UNIX systems.
|
_NNG_ avoids this to prevent accidental reuse or
|
collision after a descriptor is closed.
|
Consequently, socket numbers can become quite large, and should
|
probably not be used for array indices.
|
|
* The following options (`nn_getsockopt`) are unsupported:
|
`NN_SNDPRIO`, `NN_RCVPRIO`, `NN_IPV4ONLY`.
|
The priority options may be supported in the future, when
|
the underlying capability is present in _NNG_.
|
|
* Access to statistics using this legacy API
|
(xref:nn_get_statistic.3compat.adoc[`nn_get_statistic()`]) is unsupported.
|
|
* Some transports can support longer URLs than legacy _libnanomsg_ can.
|
It is a good idea to use short pathnames in URLs if interoperability
|
is a concern.
|
|
* Only absolute paths are supported in `ipc://` URLs.
|
For example, `ipc:///tmp/mysocket` is acceptable, but `ipc://mysocket` is not.
|
|
* The WebSocket transport in this implementation (`ws://` URLs)
|
only supports BINARY frames.
|
|
* Some newer transports are unusable from this mode.
|
In particular, this legacy API offers no way to configure
|
TLS or ZeroTier parameters that may be required for use.
|
|
* ABI versioning of the compatibility layer is not supported,
|
and the `NN_VERSION_` macros are not present.
|
|
* Runtime symbol information is not implemented.
|
Specifically, there is no `nn_symbol()` function yet.
|
(This may be addressed later if there is a need.)
|
|
* The TCP transport (`tcp://` URLs) does not support specifying the local
|
address or interface when binding. (This could be fixed in the future,
|
but most likely this will be available only using the new API.)
|
|
* The values of `NN_RCVMAXSIZE` are constrained.
|
Specifically, values set larger than 2GB using the new API will be reported
|
as unlimited (`-1`) in the new API, and the value `0` will disable any
|
enforcement, just like `-1`.
|
(There is no practical reason to ever want to limit the receive size to
|
zero.)
|
|
* This implementation counts buffers in terms of messages rather than bytes.
|
As a result, the buffer sizes accessed with `NN_SNDBUF` and `NN_RCVBUF` are
|
rounded up to a whole number of kilobytes, then divided by 1024, in order
|
to approximate buffering assuming 1 KB messages.
|
Few applications should need to adjust the default values.
|
|
== SEE ALSO
|
|
[.text-left]
|
xref:libnng.3.adoc[libnng(3)],
|
xref:nng.7.adoc[nng(7)]
|
