diff options
Diffstat (limited to 'docs/ref')
| -rw-r--r-- | docs/ref/api/memory.md | 4 | ||||
| -rw-r--r-- | docs/ref/api/sock.md | 28 | ||||
| -rw-r--r-- | docs/ref/migrate/nanomsg.md | 2 | ||||
| -rw-r--r-- | docs/ref/migrate/nng1.md | 9 | ||||
| -rw-r--r-- | docs/ref/xref.md | 1 |
5 files changed, 13 insertions, 31 deletions
diff --git a/docs/ref/api/memory.md b/docs/ref/api/memory.md index c5ecb23a..d8c5ecf9 100644 --- a/docs/ref/api/memory.md +++ b/docs/ref/api/memory.md @@ -19,9 +19,7 @@ Note that the memory may have random data in it, just like with `malloc`. If memory cannot be allocated for any reason, then `NULL` will be returned. Applications that experience this should treat this like [`NNG_ENOMEM`]. -Memory returned by `nng_alloc` can be used to hold message buffers, in which -case it can be directly passed to [`nng_send`] using the flag `NNG_FLAG_ALLOC`. -Alternatively, it can be freed when no longer needed using [`nng_free`]. +Memory returned by `nng_alloc` should be freed when no longer needed using [`nng_free`]. > [!IMPORTANT] > Do not use the system `free` function (or the C++ `delete` operator) to release this memory. diff --git a/docs/ref/api/sock.md b/docs/ref/api/sock.md index 3ea056fb..ec6b20e1 100644 --- a/docs/ref/api/sock.md +++ b/docs/ref/api/sock.md @@ -177,13 +177,6 @@ made up of zero or more of the following values: If the socket cannot accept more data at this time, it does not block, but returns immediately with a status of [`NNG_EAGAIN`]. If this flag is absent, the function will wait until data can be sent. -- {{i:`NNG_FLAG_ALLOC`}}: <a name="NNG_FLAG_ALLOC"></a> - The _data_ was allocated using [`nng_alloc`] or was obtained from a call to [`nng_recv`] also with - the `NNG_FLAG_ALLOC` flag. If this function succeeds, then it will dispose of the _data_, deallocating it - once the transmission is complete. If this function returns a non-zero status, the caller retains the responsibility - of disposing the data. The benefit of this flag is that it can eliminate a data copy and allocation. Without the flag - the socket will make a duplicate copy of _data_ for use by the operation, before returning to the caller. - > [!NOTE] > Regardless of the presence or absence of `NNG_FLAG_NONBLOCK`, there may > be queues between the sender and the receiver. @@ -191,11 +184,6 @@ made up of zero or more of the following values: > Finally, with some protocols, the semantic is implicitly `NNG_FLAG_NONBLOCK`, > such as with [PUB][pub] sockets, which are best-effort delivery only. -> [!IMPORTANT] -> When using `NNG_FLAG_ALLOC`, it is important that the value of _size_ match the actual allocated size of the data. -> Using an incorrect size results in unspecified behavior, which may include heap corruption, program crashes, -> or other undesirable effects. - ### nng_sendmsg The `nng_sendmsg` function sends the _msg_ over the socket _s_. @@ -248,8 +236,7 @@ messages over the socket _s_. The differences in their behaviors are as follows. ### nng_recv The `nng_recv` function is the simplest to use, but is the least efficient. -It receives the content in _data_, as a message size (in bytes) of up to the value stored in _sizep_, -unless the `NNG_FLAG_ALLOC` flag is set in _flags_ (see below.) +It receives the content in _data_, as a message size (in bytes) of up to the value stored in _sizep_. Upon success, the size of the message received will be stored in _sizep_. @@ -259,17 +246,6 @@ The _flags_ is a bit mask made up of zero or more of the following values: If the socket has no messages pending for reception at this time, it does not block, but returns immediately with a status of [`NNG_EAGAIN`]. If this flag is absent, the function will wait until data can be received. -- {{i:`NNG_FLAG_ALLOC`}}: - Instead of receiving the message into _data_, a new buffer will be allocated exactly large enough to hold - the message. A pointer to that buffer will be stored at the location specified by _data_. This provides a form - of zero-copy operation. The caller should dispose of the buffer using [`nng_free`] or by sending using - [`nng_send`] with the [`NNG_FLAG_ALLOC`] flag. - -> [!IMPORTANT] -> When using `NNG_FLAG_ALLOC`, it is important that the value of _size_ match the actual allocated size of the data. -> Using an incorrect size results in unspecified behavior, which may include heap corruption, program crashes, -> or other undesirable effects. - ### nng_recvmsg The `nng_recvmsg` function receives a message and stores a pointer to the [`nng_msg`] for that message in _msgp_. @@ -279,7 +255,7 @@ has no messages available to receive. In such a case, it will return [`NNG_EAGAI > [!TIP] > This function is preferred over [`nng_recv`], as it gives access to the message structure and eliminates both -> a data copy and allocation, even when `nng_recv` is using `NNG_FLAG_ALLOC`. +> a data copy and allocation. ### nng_recv_aio 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 diff --git a/docs/ref/xref.md b/docs/ref/xref.md index 88958feb..2d98e1d4 100644 --- a/docs/ref/xref.md +++ b/docs/ref/xref.md @@ -282,7 +282,6 @@ [`NNG_UNIT_MESSAGES`]: /api/stats.md#statistic-units [`NNG_UNIT_MILLIS`]: /api/stats.md#statistic-units [`NNG_UNIT_EVENTS`]: /api/stats.md#statistic-units -[`NNG_FLAG_ALLOC`]: /TODO.md [`NNG_FLAG_NONBLOCK`]: /TODO.md [`NNG_OPT_LISTEN_FD`]: /api/streams.md#socket-activation [`NNG_OPT_MAXTTL`]: /TODO.md |