From b22e9c5158861937e5d9228854b93165615f52ba Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Fri, 3 Jan 2025 09:03:00 -0800 Subject: stable: docs: note deprecation of NNG_FLAG_ALLOC --- docs/man/nng_recv.3.adoc | 10 +++++----- docs/man/nng_send.3.adoc | 7 ++++--- 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/man/nng_recv.3.adoc b/docs/man/nng_recv.3.adoc index ef1f2756..5b64fa8c 100644 --- a/docs/man/nng_recv.3.adoc +++ b/docs/man/nng_recv.3.adoc @@ -1,6 +1,6 @@ = nng_recv(3) // -// Copyright 2018 Staysail Systems, Inc. +// Copyright 2025 Staysail Systems, Inc. // Copyright 2018 Capitar IT Group BV // // This document is supplied under the terms of the MIT License, a @@ -52,6 +52,10 @@ and must store the size of that buffer at the location pointed to by _sizep_. When the function returns, if it is successful, the size at _sizep_ will be updated with the actual message body length copied into _data_. +NOTE: The `NNG_FLAG_ALLOC` flag is deprecated and may be removed in a future release. +Applications should use xref:nng_recvmsg.3.adoc[`nng_recvmsg()`] for zero copy performance +improvements. + NOTE: The semantics of what receiving a message means vary from protocol to protocol, so examination of the protocol documentation is encouraged. (For example, with a xref:nng_req.7.adoc[_req_] socket a message may only be received @@ -60,10 +64,6 @@ may only receive messages corresponding to topics to which it has subscribed.) Furthermore, some protocols may not support receiving data at all, such as xref:nng_pub.7.adoc[_pub_]. -TIP: The `NNG_FLAG_ALLOC` flag can be used to reduce data copies, thereby -increasing performance, particularly if the buffer is reused to send -a response using the same flag. - == RETURN VALUES This function returns 0 on success, and non-zero otherwise. diff --git a/docs/man/nng_send.3.adoc b/docs/man/nng_send.3.adoc index 7037f547..49c9b767 100644 --- a/docs/man/nng_send.3.adoc +++ b/docs/man/nng_send.3.adoc @@ -1,6 +1,6 @@ = nng_send(3) // -// Copyright 2018 Staysail Systems, Inc. +// Copyright 2025 Staysail Systems, Inc. // Copyright 2018 Capitar IT Group BV // // This document is supplied under the terms of the MIT License, a @@ -57,8 +57,9 @@ The _flags_ may contain either of (or neither of) the following values: In the absence of this flag, the _data_ is copied by the implementation before the function returns to the caller. -TIP: The `NNG_FLAG_ALLOC` flag can be used to reduce data copies, thereby -increasing performance. +NOTE: The `NNG_FLAG_ALLOC` flag is deprecated and may be removed in a future release. +Applications should use xref:nng_sendmsg.3.adoc[`nng_sendmsg()`] for zero copy performance +improvements. NOTE: Regardless of the presence or absence of `NNG_FLAG_NONBLOCK`, there may be queues between the sender and the receiver. -- cgit v1.2.3-70-g09d2