From abb4dcaf84b4224788c1d343fe557079e053ee5b Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 24 Mar 2024 13:36:51 -0700 Subject: subdir for compmat --- docs/reference/src/SUMMARY.md | 2 +- docs/reference/src/api/compat.md | 120 --------------------------------- docs/reference/src/api/compat/index.md | 120 +++++++++++++++++++++++++++++++++ 3 files changed, 121 insertions(+), 121 deletions(-) delete mode 100644 docs/reference/src/api/compat.md create mode 100644 docs/reference/src/api/compat/index.md (limited to 'docs/reference') diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md index 867007d2..c605fa3b 100644 --- a/docs/reference/src/SUMMARY.md +++ b/docs/reference/src/SUMMARY.md @@ -74,6 +74,6 @@ - [nng_bus_open](api/nng_bus_open.md) - [nng_close](api/nng_close.md) - - [Legacy Compatibility](api/compat.md) + - [Legacy Compatibility](api/compat/index.md) - [Index](./indexing.md) diff --git a/docs/reference/src/api/compat.md b/docs/reference/src/api/compat.md deleted file mode 100644 index 4ff75b3e..00000000 --- a/docs/reference/src/api/compat.md +++ /dev/null @@ -1,120 +0,0 @@ -# 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 `` instead refer to ``. -For example, instead of: - -```c -#include -#include -``` - -you would have this: - -```c -#include -#include -``` - -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. diff --git a/docs/reference/src/api/compat/index.md b/docs/reference/src/api/compat/index.md new file mode 100644 index 00000000..4ff75b3e --- /dev/null +++ b/docs/reference/src/api/compat/index.md @@ -0,0 +1,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 `` instead refer to ``. +For example, instead of: + +```c +#include +#include +``` + +you would have this: + +```c +#include +#include +``` + +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. -- cgit v1.2.3-70-g09d2