diff options
| author | Garrett D'Amore <garrett@damore.org> | 2025-01-01 17:06:39 -0800 |
|---|---|---|
| committer | Garrett D'Amore <garrett@damore.org> | 2025-01-01 17:06:39 -0800 |
| commit | f7bf24f429cbc488b861ab1b1e4cf1983af56295 (patch) | |
| tree | 2196361a906bd5db1148c0e177d69854a99b7b58 /docs/ref/migrate | |
| parent | ee5c8437f8c2a811c0eaef9b00c149b93c095391 (diff) | |
| download | nng-f7bf24f429cbc488b861ab1b1e4cf1983af56295.tar.gz nng-f7bf24f429cbc488b861ab1b1e4cf1983af56295.tar.bz2 nng-f7bf24f429cbc488b861ab1b1e4cf1983af56295.zip | |
api: Remove the NNG_FLAG_ALLOC
This flag failed to provide real zero copy that it was intended for,
and it also involved extra allocations. Further, the API for it was
brittle and error prone.
Modern code should just work directly with nng_msg structures.
Diffstat (limited to 'docs/ref/migrate')
| -rw-r--r-- | docs/ref/migrate/nanomsg.md | 2 | ||||
| -rw-r--r-- | docs/ref/migrate/nng1.md | 9 |
2 files changed, 10 insertions, 1 deletions
diff --git a/docs/ref/migrate/nanomsg.md b/docs/ref/migrate/nanomsg.md index 47f82a9c..78eed618 100644 --- a/docs/ref/migrate/nanomsg.md +++ b/docs/ref/migrate/nanomsg.md @@ -56,7 +56,7 @@ NNG approach to messages. Likewise there is no `struct nn_cmsghdr` equivalent. | `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_MSG` | [`nng_sendmsg`], [`nng_recvmsg`] | There are differences as a separate [`nng_msg`] structure is involved. | | `NN_CMSG_ALIGN` | None | | `NN_CMSG_FIRSTHDR` | None | | `NN_CMSG_NXTHDR` | None | diff --git a/docs/ref/migrate/nng1.md b/docs/ref/migrate/nng1.md index 65f1a81e..8e418468 100644 --- a/docs/ref/migrate/nng1.md +++ b/docs/ref/migrate/nng1.md @@ -40,6 +40,15 @@ be supplied should avoid surprises later as new versions of protocols are added. Additionally, the header files for protocols are now empty, as all of their content has been moved to `nng/nng.h`. Please remove `#include` references to protocol headers as we anticipate removing them in the future. +## NNG_FLAG_ALLOC 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_send_aio`], or [`nng_recv_aio`] to get the maximum performance benefit. +Working directly with [`nng_msg`] structures gives more control, reduces copies, and reduces allocation activity. + ## New AIO Error Code NNG_ESTOPPED When an operation fails with [`NNG_ESTOPPED`], it means that the associated [`nni_aio`] object has |