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.

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