1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
|
# Legacy Compatibility Functions
{{hi:compatibility layer}}
_NNG_ provides source-level compatibility for most _libnanomsg_ 1.0 applications.
This is intended to facilitate converting {{i:legacy applications}} to use _NNG_.
New applications should use the newer _NNG_ APIs instead.
Applications making use of this must take care
to link with _libnng_ instead of _libnn_.
> [!TIP]
> While not recommended for long term use, the value returned by
> [`nng_socket_id()`](nng_socket_id.md) can be used with these functions
> just like a value returned by [`nn_socket()`](nn_socket.md).
> This can be way to facilitate incremental transition to the new API.
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.
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](#caveats) section below.
### Availability
The availability of this legacy API depends on whether the library was
configured to include it.
> [!NOTE]
> Future versions of _NNG_ may not include this compatibility layer
> by default, or even at all. Modernizing applications to use the new
> API is strongly recommended.
### 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:
```c
#include <nanomsg/nn.h>
#include <nanomsg/reqrep.h>
```
you would have this:
```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.
### 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`.
- Access to statistics using this legacy API
[`nn_get_statistic()`](nn_get_statistic.md) 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.
- 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.
|
