From 1bcf60a65ee56054e638c0859da1fe2418160bc6 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 31 Mar 2024 10:58:17 -0700 Subject: nng_recv* added --- docs/man/nng_recv.3.adoc | 91 ------------------------- docs/man/nng_recv_aio.3.adoc | 81 ---------------------- docs/man/nng_recvmsg.3.adoc | 71 -------------------- docs/man/nng_send.3.adoc | 100 ---------------------------- docs/man/nng_send_aio.3.adoc | 91 ------------------------- docs/man/nng_sendmsg.3.adoc | 94 -------------------------- docs/reference/src/SUMMARY.md | 3 + docs/reference/src/refs.md | 6 ++ docs/reference/src/sock/nng_recv.md | 83 +++++++++++++++++++++++ docs/reference/src/sock/nng_recv_aio.md | 65 ++++++++++++++++++ docs/reference/src/sock/nng_recvmsg.md | 68 +++++++++++++++++++ docs/reference/src/sock/nng_send.3.adoc | 90 +++++++++++++++++++++++++ docs/reference/src/sock/nng_send_aio.3.adoc | 81 ++++++++++++++++++++++ docs/reference/src/sock/nng_sendmsg.3.adoc | 84 +++++++++++++++++++++++ 14 files changed, 480 insertions(+), 528 deletions(-) delete mode 100644 docs/man/nng_recv.3.adoc delete mode 100644 docs/man/nng_recv_aio.3.adoc delete mode 100644 docs/man/nng_recvmsg.3.adoc delete mode 100644 docs/man/nng_send.3.adoc delete mode 100644 docs/man/nng_send_aio.3.adoc delete mode 100644 docs/man/nng_sendmsg.3.adoc create mode 100644 docs/reference/src/sock/nng_recv.md create mode 100644 docs/reference/src/sock/nng_recv_aio.md create mode 100644 docs/reference/src/sock/nng_recvmsg.md create mode 100644 docs/reference/src/sock/nng_send.3.adoc create mode 100644 docs/reference/src/sock/nng_send_aio.3.adoc create mode 100644 docs/reference/src/sock/nng_sendmsg.3.adoc diff --git a/docs/man/nng_recv.3.adoc b/docs/man/nng_recv.3.adoc deleted file mode 100644 index ef1f2756..00000000 --- a/docs/man/nng_recv.3.adoc +++ /dev/null @@ -1,91 +0,0 @@ -= nng_recv(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_recv - recv data - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_recv(nng_socket s, void *data, size_t *sizep, int flags); ----- - -== DESCRIPTION - -The `nng_recv()` receives a message. - -The _flags_ is a bit mask that may contain any of the following values: - -`NNG_FLAG_NONBLOCK`:: - The function returns immediately, even if no message is available. - Without this flag, the function will wait until a message is received - by the socket _s_, or any configured timer expires. - -`NNG_FLAG_ALLOC`:: - If this flag is present, then a ((zero-copy)) mode is used. - In this case the caller must set the value of _data_ to the location - of another pointer (of type `void *`), and the _sizep_ pointer must be set - to a location to receive the size of the message body. - The function will then allocate a message buffer - (as if by xref:nng_alloc.3.adoc[`nng_alloc()`]), fill it with - the message body, and store it at the address referenced by _data_, and update - the size referenced by _sizep_. - The caller is responsible for disposing of the received buffer either by - the xref:nng_free.3.adoc[`nng_free()`] function or passing the message (also - with the `NNG_FLAG_ALLOC` flag) in a call to xref:nng_send.3.adoc[`nng_send()`]. - -If the special flag `NNG_FLAG_ALLOC` (see above) is not specified, then the -caller must set _data_ to a buffer to receive the message body content, -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 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 -after a request has been sent, and a xref:nng_sub.7.adoc[_sub_] socket -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. - -== ERRORS - -[horizontal] -`NNG_EAGAIN`:: The operation would block, but `NNG_FLAG_NONBLOCK` was specified. -`NNG_ECLOSED`:: The socket _s_ is not open. -`NNG_EINVAL`:: An invalid set of _flags_ was specified. -`NNG_EMSGSIZE`:: The received message did not fit in the size provided. -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The protocol for socket _s_ does not support receiving. -`NNG_ESTATE`:: The socket _s_ cannot receive data in this state. -`NNG_ETIMEDOUT`:: The operation timed out. - -== SEE ALSO - -[.text-left] -xref:nng_alloc.3.adoc[nng_alloc(3)], -xref:nng_free.3.adoc[nng_free(3)], -xref:nng_recvmsg.3.adoc[nng_recvmsg(3)], -xref:nng_send.3.adoc[nng_send(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_recv_aio.3.adoc b/docs/man/nng_recv_aio.3.adoc deleted file mode 100644 index 4c970489..00000000 --- a/docs/man/nng_recv_aio.3.adoc +++ /dev/null @@ -1,81 +0,0 @@ -= nng_recv_aio(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_recv_aio - receive message asynchronously - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_recv_aio(nng_socket s, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_recv_aio()` receives a xref:nng_msg.5.adoc[message] using the -xref:nng_socket.5.adoc[socket] _s_ asynchronously. - -When a message is successfully received by the socket, it is -stored in the _aio_ by an internal call equivalent to -xref:nng_aio_set_msg.3.adoc[`nng_aio_set_msg()`], then the completion -callback on the _aio_ is executed. -In this case, xref:nng_aio_result.3.adoc[`nng_aio_result()`] will -return zero. -The callback function is responsible for retrieving the message -and disposing of it appropriately. - -IMPORTANT: Failing to accept and dispose of messages in this -case can lead to memory leaks. - -If for some reason the asynchronous receive cannot be completed -successfully (including by being canceled or timing out), then -the callback will still be executed, -but xref:nng_aio_result.3.adoc[`nng_aio_result()`] will be non-zero. - -NOTE: The semantics of what receiving a message means varies from protocol to -protocol, so examination of the protocol documentation is encouraged. -(For example, with a xref:nng_pub.7.adoc[_pub_] socket the data is broadcast, so that -any peers who have a suitable subscription will be able to receive it using -xref:nng_recv.3.adoc[`nng_recv()`] or a similar function.) -Furthermore, some protocols may not support receiving (such as -xref:nng_pub.7.adoc[_pub_]) or may require other conditions. -(For example, xref:nng_req.7.adoc[_req_] sockets cannot normally receive data, which -are replies to requests, until they have first sent a request.) - -== RETURN VALUES - -None. (The operation completes asynchronously.) - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was aborted. -`NNG_ECLOSED`:: The socket _s_ is not open. -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The protocol for socket _s_ does not support receiving. -`NNG_ESTATE`:: The socket _s_ cannot receive data in this state. -`NNG_ETIMEDOUT`:: The receive timeout expired. - -== SEE ALSO - -[.text-left] -xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg(3)], -xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg(3)], -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_recvmsg.3.adoc b/docs/man/nng_recvmsg.3.adoc deleted file mode 100644 index c502d650..00000000 --- a/docs/man/nng_recvmsg.3.adoc +++ /dev/null @@ -1,71 +0,0 @@ -= nng_recvmsg(3) -// -// Copyright 2021 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_recvmsg - receive a message - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_recvmsg(nng_socket s, nng_msg **msgp, int flags); ----- - -== DESCRIPTION - -The `nng_recvmsg()` receives a message on socket _s_, storing the -received message at the location pointed to by _msgp_. - -TIP: Using this function gives access to the message structure, and thus may -offer more functionality than the simpler xref:nng_recv.3.adoc[`nng_recv()`] function. - -The _flags_ may contain the following value: - -`NNG_FLAG_NONBLOCK`:: - The function returns immediately, even if no message is available. - Without this flag, the function will wait until a message is received - by the socket _s_, or any configured timer expires. - -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 an xref:nng_req.7.adoc[_req_] socket a message may only be received -after a request has been sent, and an xref:nng_sub.7.adoc[_sub_] socket -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_]. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EAGAIN`:: The operation would block, but `NNG_FLAG_NONBLOCK` was specified. -`NNG_ECLOSED`:: The socket _s_ is not open. -`NNG_EINVAL`:: An invalid set of _flags_ was specified. -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The protocol for socket _s_ does not support receiving. -`NNG_ESTATE`:: The socket _s_ cannot receive data in this state. -`NNG_ETIMEDOUT`:: The operation timed out. - -== SEE ALSO - -[.text-left] -xref:nng_msg_free.3.adoc[nng_msg_free(3)], -xref:nng_recv.3.adoc[nng_recv(3)], -xref:nng_sendmsg.3.adoc[nng_sendmsg(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_send.3.adoc b/docs/man/nng_send.3.adoc deleted file mode 100644 index 7037f547..00000000 --- a/docs/man/nng_send.3.adoc +++ /dev/null @@ -1,100 +0,0 @@ -= nng_send(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_send - send data - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_send(nng_socket s, void *data, size_t size, int flags); ----- - -== DESCRIPTION - -The `nng_send()` function sends a message containing the _data_ of -length _size_ using the xref:nng_socket.5.adoc[socket] _s_. - -NOTE: The semantics of what sending a message means vary from protocol to -protocol, so examination of the protocol documentation is encouraged. -(For example, with an xref:nng_pub.7.adoc[_pub_] socket the data is broadcast, so that -any peers who have a suitable subscription will be able to receive it using -xref:nng_recv.3.adoc[`nng_recv()`] or a similar function.) -Furthermore, some protocols may not support sending data (such as -xref:nng_sub.7.adoc[_sub_]) or may require other conditions. -(For example, xref:nng_rep.7.adoc[_rep_] sockets cannot normally send data, -which are responses to requests, until they have first received a request.) - -The _flags_ may contain either of (or neither of) the following values: - -`NNG_FLAG_NONBLOCK`:: - The function returns immediately, regardless of whether - the socket is able to accept the data or not. If the socket is unable - to accept the data (such as if backpressure exists because the peers - are consuming messages too slowly, or no peer is present), then the - function will return with `NNG_EAGAIN`. If this flag is not specified, - then the function will block if such a condition exists. - -`NNG_FLAG_ALLOC`:: - The _data_ was allocated using xref:nng_alloc.3.adoc[`nng_alloc()`], or was - obtained from a call to xref:nng_recv.3.adoc[`nng_recv()`] with - the `NNG_FLAG_ALLOC` flag. - If this function returns success, then the _data_ is "owned" by the - function, and it will assume responsibility for calling - xref:nng_free.3.adoc[`nng_free()`] when it is no longer needed. - 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: Regardless of the presence or absence of `NNG_FLAG_NONBLOCK`, there may -be queues between the sender and the receiver. -Furthermore, there is no guarantee that the message has actually been delivered. -Finally, with some protocols, the semantic is implicitly `NNG_FLAG_NONBLOCK`, -such as with xref:nng_pub.7.adoc[_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 trans-dimensional mutation of the program's author. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EAGAIN`:: The operation would block, but `NNG_FLAG_NONBLOCK` was specified. -`NNG_ECLOSED`:: The socket _s_ is not open. -`NNG_EINVAL`:: An invalid set of _flags_ was specified. -`NNG_EMSGSIZE`:: The value of _size_ is too large. -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The protocol for socket _s_ does not support sending. -`NNG_ESTATE`:: The socket _s_ cannot send data in this state. -`NNG_ETIMEDOUT`:: The operation timed out. - -== SEE ALSO - -[.text-left] -xref:nng_alloc.3.adoc[nng_alloc(3)], -xref:nng_free.3.adoc[nng_free(3)], -xref:nng_recv.3.adoc[nng_recv(3)], -xref:nng_sendmsg.3.adoc[nng_sendmsg(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_send_aio.3.adoc b/docs/man/nng_send_aio.3.adoc deleted file mode 100644 index e8fc2005..00000000 --- a/docs/man/nng_send_aio.3.adoc +++ /dev/null @@ -1,91 +0,0 @@ -= nng_send_aio(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_send_aio - send message asynchronously - -== SYNOPSIS - -[source, c] ----- -#include - -void nng_send_aio(nng_socket s, nng_aio *aio); ----- - -== DESCRIPTION - -The `nng_send_aio()` sends a xref:nng_msg.5.adoc[message] using the -xref:nng_socket.5.adoc[socket] _s_ asynchronously. - -The message to send must have previously been set on the _aio_ -using the xref:nng_aio_set_msg.3.adoc[`nng_aio_set_msg()`] function. -The function assumes ownership of the message. - -If the message was successfully queued for delivery to the socket, -then the _aio_ will be completed, and xref:nng_aio_result.3.adoc[`nng_aio_result()`] -will return zero. In this case the socket will dispose of the -message when it is finished with it. - -NOTE: The operation will be completed, and the callback associated -with the _aio_ executed, as soon as the socket accepts the message -for sending. -This does _not_ indicate that the message was actually delivered, as it -may still be buffered in the sending socket, buffered in the receiving -socket, or in flight over physical media. - -If the operation fails for any reason (including cancellation or timeout), -then the _aio_ callback will be executed and -xref:nng_aio_result.3.adoc[`nng_aio_result()`] -will return a non-zero error status. -In this case, the callback has a responsibility to retrieve the message from -the _aio_ with -xref:nng_aio_get_msg.3.adoc[`nng_aio_get_msg()`] and dispose of it appropriately. -(This may include retrying the send operation on the same or a different -socket, or deallocating the message with xref:nng_msg_free.3.adoc[`nng_msg_free()`].) - -NOTE: The semantics of what sending a message means varies from protocol to -protocol, so examination of the protocol documentation is encouraged. -(For example, with a xref:nng_pub.7.adoc[_pub_] socket the data is broadcast, so that -any peers who have a suitable subscription will be able to receive it using -xref:nng_recv.3.adoc[`nng_recv()`] or a similar function.) -Furthermore, some protocols may not support sending (such as -xref:nng_sub.7.adoc[_sub_]) or may require other conditions. -(For example, xref:nng_rep.7.adoc[_rep_] sockets cannot normally send data, which -are responses to requests, until they have first received a request.) - -== RETURN VALUES - -None. (The operation completes asynchronously.) - -== ERRORS - -[horizontal] -`NNG_ECANCELED`:: The operation was aborted. -`NNG_ECLOSED`:: The socket _s_ is not open. -`NNG_EMSGSIZE`:: The message is too large. -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The protocol for socket _s_ does not support sending. -`NNG_ESTATE`:: The socket _s_ cannot send data in this state. -`NNG_ETIMEDOUT`:: The send timeout expired. - -== SEE ALSO - -[.text-left] -xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg(3)], -xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg(3)], -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_aio.5.adoc[nng_aio(5)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_sendmsg.3.adoc b/docs/man/nng_sendmsg.3.adoc deleted file mode 100644 index 5b7a73ee..00000000 --- a/docs/man/nng_sendmsg.3.adoc +++ /dev/null @@ -1,94 +0,0 @@ -= nng_sendmsg(3) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_sendmsg - send message - -== SYNOPSIS - -[source, c] ----- -#include - -int nng_sendmsg(nng_socket s, nng_msg *msg, int flags); ----- - -== DESCRIPTION - -The `nng_sendmsg()` sends message _msg_ using the socket _s_. - -If the function returns zero, indicating it has accepted the message for -delivery, then the _msg_ is owned by the socket _s_, and the caller -must not make any further use of it. -The socket will free the message when it is finished. - -If the function returns non-zero, then it is the caller's responsibility -to dispose of the _msg_, which may include freeing it, sending it to -another socket, or simply trying again later. - -TIP: Using this function gives access to the message structure, and may -offer more functionality than the simpler xref:nng_send.3.adoc[`nng_send()`] function. - -NOTE: The semantics of what sending a message means vary from protocol to -protocol, so examination of the protocol documentation is encouraged. -(For example, with a xref:nng_pub.7.adoc[_pub_] socket the data is broadcast, so that -any peers who have a suitable subscription will be able to receive it using -xref:nng_recv.3.adoc[`nng_recv()`] or a similar function.) -Furthermore, some protocols may not support sending (such as -xref:nng_sub.7.adoc[_sub_]) or may require other conditions. -(For example, xref:nng_rep.7.adoc[_rep_] sockets cannot normally send data, which -are responses to requests, until they have first received a request.) - -The _flags_ may contain the following value: - -`NNG_FLAG_NONBLOCK`:: - The function returns immediately, regardless of whether - the socket is able to accept the data or not. - If the socket is unable to accept the data (such as if backpressure exists - because the peers are consuming messages too slowly, or no peer is present), - then the function will return with `NNG_EAGAIN`. - If this flag is not specified, then the function will block if such a - condition exists. - - -NOTE: Regardless of the presence or absence of `NNG_FLAG_NONBLOCK`, there may -be queues between the sender and the receiver. -Furthermore, there is no guarantee that the message has actually been delivered. -Finally, with some protocols, the semantic is implicitly `NNG_FLAG_NONBLOCK`, -such as with xref:nng_pub.7.adoc[_pub_] sockets, which are best-effort delivery only. - -== RETURN VALUES - -This function returns 0 on success, and non-zero otherwise. - -== ERRORS - -[horizontal] -`NNG_EAGAIN`:: The operation would block, but `NNG_FLAG_NONBLOCK` was specified. -`NNG_ECLOSED`:: The socket _s_ is not open. -`NNG_EINVAL`:: An invalid set of _flags_ was specified. -`NNG_EMSGSIZE`:: The value of _size_ is too large. -`NNG_ENOMEM`:: Insufficient memory is available. -`NNG_ENOTSUP`:: The protocol for socket _s_ does not support sending. -`NNG_ESTATE`:: The socket _s_ cannot send data in this state. -`NNG_ETIMEDOUT`:: The operation timed out. - -== SEE ALSO - -[.text-left] -xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)], -xref:nng_recvmsg.3.adoc[nng_recvmsg(3)], -xref:nng_send.3.adoc[nng_send(3)], -xref:nng_strerror.3.adoc[nng_strerror(3)], -xref:nng_msg.5.adoc[nng_msg(5)], -xref:nng_socket.5.adoc[nng_socket(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md index 40a02f7d..1a911e37 100644 --- a/docs/reference/src/SUMMARY.md +++ b/docs/reference/src/SUMMARY.md @@ -61,6 +61,9 @@ - [nng_pull_open](sock/nng_pull_open.md) - [nng_push_open](sock/nng_push_open.md) - [nng_respondent_open](sock/nng_respondent_open.md) + - [nng_recv](sock/nng_recv.md) + - [nng_recv_aio](sock/nng_recv_aio.md) + - [nng_recvmsg](sock/nng_recvmsg.md) - [nng_rep_open](sock/nng_rep_open.md) - [nng_req_open](sock/nng_req_open.md) - [nng_sub_open](sock/nng_sub_open.md) diff --git a/docs/reference/src/refs.md b/docs/reference/src/refs.md index cb5c74f1..98a3d153 100644 --- a/docs/reference/src/refs.md +++ b/docs/reference/src/refs.md @@ -54,6 +54,12 @@ [nng_surveyor_open]: ../sock/nng_surveyor_open.md [nng_close]: ../sock/nng_close.md [nng_device]: ../sock/nng_device.md +[nng_recv]: ../sock/nng_recv.md +[nng_recv_aio]: ../sock/nng_recv_aio.md +[nng_recvmsg]: ../sock/nng_recvmsg.md +[nng_send]: ../sock/nng_send.md +[nng_send_aio]: ../sock/nng_send_aio.md +[nng_sendmsg]: ../sock/nng_sendmsg.md diff --git a/docs/reference/src/sock/nng_recv.md b/docs/reference/src/sock/nng_recv.md new file mode 100644 index 00000000..178661f7 --- /dev/null +++ b/docs/reference/src/sock/nng_recv.md @@ -0,0 +1,83 @@ +# nng_recv + +## NAME + +nng_recv --- recv data + +## SYNOPSIS + +```c +#include + +int nng_recv(nng_socket s, void *data, size_t *sizep, int flags); +``` + +## DESCRIPTION + +The `nng_recv()` receives a message from the [socket][socket] _s_, +obtaining its body content. + +The _flags_ is a bit mask that may contain any of the following values: + +- `NNG_FLAG_NONBLOCK`:\ + The function returns immediately, even if no message is available. + Without this flag, the function will wait until a message is received + by the socket _s_, or any configured timer expires. + +- `NNG_FLAG_ALLOC`:\ + If this flag is present, then a {{i:zero-copy}} mode is used. + In this case the caller must set the value of _data_ to the location + of another pointer (of type `void *`), and the _sizep_ pointer must be set + to a location to receive the size of the message body. + The function will then allocate a message buffer + (as if by [`nng_alloc()`][nng_alloc]), fill it with + the message body, and store it at the address referenced by _data_, and update + the size referenced by _sizep_. + The caller is responsible for disposing of the received buffer either by + the [`nng_free()`][nng_free] function or passing the message (also + with the {{i:`NNG_FLAG_ALLOC`}} flag) in a call to [`nng_send()`][nng_send]. + +If the special flag `NNG_FLAG_ALLOC` (see above) is not specified, then the +caller must set _data_ to a buffer to receive the message body content, +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 semantics of what receiving a message means vary from protocol to +> protocol, so examination of the protocol documentation is encouraged. +> (For example, with a [_REQ_][req] socket a message may only be received +> after a request has been sent, and a [_SUB_][sub] socket +> may only receive messages corresponding to topics to which it has subscribed.) +> Furthermore, some protocols may not support receiving data at all, such as +> [_PUB_][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. However, the [`nng_recvmsg()`][nng_recvmsg] function is even better in this regard, and should be preferred over this +> function when possible. + +## RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_EAGAIN`: The operation would block, but `NNG_FLAG_NONBLOCK` was specified. +- `NNG_ECLOSED`: The socket _s_ is not open. +- `NNG_EINVAL`: An invalid set of _flags_ was specified. +- `NNG_EMSGSIZE`: The received message did not fit in the size provided. +- `NNG_ENOMEM`: Insufficient memory is available. +- `NNG_ENOTSUP`: The protocol for socket _s_ does not support receiving. +- `NNG_ESTATE`: The socket _s_ cannot receive data in this state. +- `NNG_ETIMEDOUT`: The operation timed out. + +## SEE ALSO + +[nng_alloc][nng_alloc], +[nng_free][nng_free], +[nng_recvmsg][nng_recvmsg], +[nng_send][nng_send] + +{{#include ../refs.md}} diff --git a/docs/reference/src/sock/nng_recv_aio.md b/docs/reference/src/sock/nng_recv_aio.md new file mode 100644 index 00000000..257ec691 --- /dev/null +++ b/docs/reference/src/sock/nng_recv_aio.md @@ -0,0 +1,65 @@ +# nng_recv_aio + +## NAME + +nng_recv_aio --- receive message asynchronously + +## SYNOPSIS + +```c +#include + +void nng_recv_aio(nng_socket s, nng_aio *aio); +``` + +## DESCRIPTION + +The `nng_recv_aio()` function receives a [message][msg] using the +[socket][socket] _s_ asynchronously. + +When a message is successfully received by the socket, it is +stored in the _aio_ by an internal call equivalent to +[`nng_aio_set_msg()`][nng_aio_set_msg], then the completion +callback on the _aio_ is executed. +In this case, [`nng_aio_result()`][nng_aio_result] will +return zero. +The callback function is responsible for retrieving the message +and disposing of it appropriately. + +> [!IMPORTANT] +> Failing to dispose of successfully received messages +> will leak the memory associated with it. + +If for some reason the asynchronous receive cannot be completed +successfully (including by being canceled or timing out), then +the callback will still be executed, +but `nng_aio_result()` will be non-zero. + +> [!NOTE] +> The semantics of what receiving a message means varies from protocol to +> protocol, so examination of the protocol documentation is encouraged. +> For example, with [_PUB_][pub] socket the data is broadcast, so that +> only peers who have a suitable subscription will be able to receive it. +> Furthermore, some protocols may not support receiving (such as +> _PUB_) or may require other conditions. +> (For example, [_REQ_][req] sockets cannot normally receive data +> until they have first sent a request.) + +## ERRORS + +- `NNG_ECANCELED`: The operation was aborted. +- `NNG_ECLOSED`: The socket _s_ is not open. +- `NNG_ENOMEM`: Insufficient memory is available. +- `NNG_ENOTSUP`: The protocol for socket _s_ does not support receiving. +- `NNG_ESTATE`: The socket _s_ cannot receive data in this state. +- `NNG_ETIMEDOUT`: The receive timeout expired. + +## SEE ALSO + +[Messages][msg], +[Sockets][socket], +[Asynchronous I/O][aio], +[nng_aio_get_msg][nng_aio_get_msg], +[nng_msg_alloc][nng_msg_alloc] + +{{#include ../refs.md}} diff --git a/docs/reference/src/sock/nng_recvmsg.md b/docs/reference/src/sock/nng_recvmsg.md new file mode 100644 index 00000000..3d3912c0 --- /dev/null +++ b/docs/reference/src/sock/nng_recvmsg.md @@ -0,0 +1,68 @@ +# nng_recvmsg + +## NAME + +nng_recvmsg --- receive a message + +## SYNOPSIS + +```c +#include + +int nng_recvmsg(nng_socket s, nng_msg **msgp, int flags); +``` + +## DESCRIPTION + +The `nng_recvmsg()` receives a [message][msg] on [socket][socket] _s_, storing the +received message at the location pointed to by _msgp_. + +This function gives access to the message structure, and thus may +offer more functionality than the simpler [`nng_recv()`][nng_recv] function.[^1] [^2] + +[^1]: It is also more efficient. +[^2]: An asynchronous form of this function is available as [`nng_recv_aio()`][nng_recv_aio]. + +The _flags_ may contain the following value: + +- {{i:`NNG_FLAG_NONBLOCK`}}: \ + The function returns immediately, even if no message is available. + Without this flag, the function will wait until a message is received + by the socket _s_, or any configured timer expires. + +After successfully receiving a message, the caller is responsible for +disposing of it when it is no longer needed. + +> [!IMPORTANT] +> Failing to dispose of the message will leak the memory associated with it. + +> [!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 [_REQ_][req] socket a message may only be received +> after a request has been sent). +> Furthermore, some protocols do not support receiving data at all. + +## RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +## ERRORS + +- `NNG_EAGAIN`: The operation would block, but `NNG_FLAG_NONBLOCK` was specified. +- `NNG_ECLOSED`: The socket _s_ is not open. +- `NNG_EINVAL`: An invalid set of _flags_ was specified. +- `NNG_ENOMEM`: Insufficient memory is available. +- `NNG_ENOTSUP`: The protocol for socket _s_ does not support receiving. +- `NNG_ESTATE`: The socket _s_ cannot receive data in this state. +- `NNG_ETIMEDOUT`: The operation timed out. + +## SEE ALSO + +[Messages][msg], +[Sockets][socket], +[nng_msg_free][nng_msg_free], +[nng_recv][nng_recv], +[nng_sendmsg][nng_sendmsg] + +{{#include ../refs.md}} diff --git a/docs/reference/src/sock/nng_send.3.adoc b/docs/reference/src/sock/nng_send.3.adoc new file mode 100644 index 00000000..4932712a --- /dev/null +++ b/docs/reference/src/sock/nng_send.3.adoc @@ -0,0 +1,90 @@ +# nng_send + +## NAME + +nng_send --- send data + +## SYNOPSIS + +``` +#include + +int nng_send(nng_socket s, void *data, size_t size, int flags); +``` + +## DESCRIPTION + +The `nng_send()` function sends a message containing the _data_ of +length _size_ using the xref:nng_socket.5.adoc[socket] _s_. + +NOTE: The semantics of what sending a message means vary from protocol to +protocol, so examination of the protocol documentation is encouraged. +(For example, with an xref:nng_pub.7.adoc[_pub_] socket the data is broadcast, so that +any peers who have a suitable subscription will be able to receive it using +xref:nng_recv.3.adoc[`nng_recv()`] or a similar function.) +Furthermore, some protocols may not support sending data (such as +xref:nng_sub.7.adoc[_sub_]) or may require other conditions. +(For example, xref:nng_rep.7.adoc[_rep_] sockets cannot normally send data, +which are responses to requests, until they have first received a request.) + +The _flags_ may contain either of (or neither of) the following values: + +`NNG_FLAG_NONBLOCK`:: + The function returns immediately, regardless of whether + the socket is able to accept the data or not. If the socket is unable + to accept the data (such as if backpressure exists because the peers + are consuming messages too slowly, or no peer is present), then the + function will return with `NNG_EAGAIN`. If this flag is not specified, + then the function will block if such a condition exists. + +`NNG_FLAG_ALLOC`:: + The _data_ was allocated using xref:nng_alloc.3.adoc[`nng_alloc()`], or was + obtained from a call to xref:nng_recv.3.adoc[`nng_recv()`] with + the `NNG_FLAG_ALLOC` flag. + If this function returns success, then the _data_ is "owned" by the + function, and it will assume responsibility for calling + xref:nng_free.3.adoc[`nng_free()`] when it is no longer needed. + 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: Regardless of the presence or absence of `NNG_FLAG_NONBLOCK`, there may +be queues between the sender and the receiver. +Furthermore, there is no guarantee that the message has actually been delivered. +Finally, with some protocols, the semantic is implicitly `NNG_FLAG_NONBLOCK`, +such as with xref:nng_pub.7.adoc[_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 trans-dimensional mutation of the program's author. + +## RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +## ERRORS + +* `NNG_EAGAIN`: The operation would block, but `NNG_FLAG_NONBLOCK` was specified. +* `NNG_ECLOSED`: The socket _s_ is not open. +* `NNG_EINVAL`: An invalid set of _flags_ was specified. +* `NNG_EMSGSIZE`: The value of _size_ is too large. +* `NNG_ENOMEM`: Insufficient memory is available. +* `NNG_ENOTSUP`: The protocol for socket _s_ does not support sending. +* `NNG_ESTATE`: The socket _s_ cannot send data in this state. +* `NNG_ETIMEDOUT`: The operation timed out. + +## SEE ALSO + +[nng_alloc][nng_alloc], +[nng_free][nng_free], +[nng_recv][nng_recv], +[nng_sendmsg][nng_sendmsg], +[nng_strerror][nng_strerror], +[nng_socket][nng_socket], +[nng][nng] + +{{#include ../refs.md}} diff --git a/docs/reference/src/sock/nng_send_aio.3.adoc b/docs/reference/src/sock/nng_send_aio.3.adoc new file mode 100644 index 00000000..4597619c --- /dev/null +++ b/docs/reference/src/sock/nng_send_aio.3.adoc @@ -0,0 +1,81 @@ +# nng_send_aio + +## NAME + +nng_send_aio --- send message asynchronously + +## SYNOPSIS + +``` +#include + +void nng_send_aio(nng_socket s, nng_aio *aio); +``` + +## DESCRIPTION + +The `nng_send_aio()` sends a xref:nng_msg.5.adoc[message] using the +xref:nng_socket.5.adoc[socket] _s_ asynchronously. + +The message to send must have previously been set on the _aio_ +using the xref:nng_aio_set_msg.3.adoc[`nng_aio_set_msg()`] function. +The function assumes ownership of the message. + +If the message was successfully queued for delivery to the socket, +then the _aio_ will be completed, and xref:nng_aio_result.3.adoc[`nng_aio_result()`] +will return zero. In this case the socket will dispose of the +message when it is finished with it. + +NOTE: The operation will be completed, and the callback associated +with the _aio_ executed, as soon as the socket accepts the message +for sending. +This does _not_ indicate that the message was actually delivered, as it +may still be buffered in the sending socket, buffered in the receiving +socket, or in flight over physical media. + +If the operation fails for any reason (including cancellation or timeout), +then the _aio_ callback will be executed and +xref:nng_aio_result.3.adoc[`nng_aio_result()`] +will return a non-zero error status. +In this case, the callback has a responsibility to retrieve the message from +the _aio_ with +xref:nng_aio_get_msg.3.adoc[`nng_aio_get_msg()`] and dispose of it appropriately. +(This may include retrying the send operation on the same or a different +socket, or deallocating the message with xref:nng_msg_free.3.adoc[`nng_msg_free()`].) + +NOTE: The semantics of what sending a message means varies from protocol to +protocol, so examination of the protocol documentation is encouraged. +(For example, with a xref:nng_pub.7.adoc[_pub_] socket the data is broadcast, so that +any peers who have a suitable subscription will be able to receive it using +xref:nng_recv.3.adoc[`nng_recv()`] or a similar function.) +Furthermore, some protocols may not support sending (such as +xref:nng_sub.7.adoc[_sub_]) or may require other conditions. +(For example, xref:nng_rep.7.adoc[_rep_] sockets cannot normally send data, which +are responses to requests, until they have first received a request.) + +## RETURN VALUES + +None. (The operation completes asynchronously.) + +## ERRORS + +* `NNG_ECANCELED`: The operation was aborted. +* `NNG_ECLOSED`: The socket _s_ is not open. +* `NNG_EMSGSIZE`: The message is too large. +* `NNG_ENOMEM`: Insufficient memory is available. +* `NNG_ENOTSUP`: The protocol for socket _s_ does not support sending. +* `NNG_ESTATE`: The socket _s_ cannot send data in this state. +* `NNG_ETIMEDOUT`: The send timeout expired. + +## SEE ALSO + +[nng_aio_get_msg][nng_aio_get_msg], +[nng_aio_set_msg][nng_aio_set_msg], +[nng_msg_alloc][nng_msg_alloc], +[nng_strerror][nng_strerror], +[nng_aio][nng_aio], +[nng_msg][nng_msg], +[nng_socket][nng_socket], +[nng][nng] + +{{#include ../refs.md}} diff --git a/docs/reference/src/sock/nng_sendmsg.3.adoc b/docs/reference/src/sock/nng_sendmsg.3.adoc new file mode 100644 index 00000000..004ae78d --- /dev/null +++ b/docs/reference/src/sock/nng_sendmsg.3.adoc @@ -0,0 +1,84 @@ +# nng_sendmsg + +## NAME + +nng_sendmsg --- send message + +## SYNOPSIS + +``` +#include + +int nng_sendmsg(nng_socket s, nng_msg *msg, int flags); +``` + +## DESCRIPTION + +The `nng_sendmsg()` sends message _msg_ using the socket _s_. + +If the function returns zero, indicating it has accepted the message for +delivery, then the _msg_ is owned by the socket _s_, and the caller +must not make any further use of it. +The socket will free the message when it is finished. + +If the function returns non-zero, then it is the caller's responsibility +to dispose of the _msg_, which may include freeing it, sending it to +another socket, or simply trying again later. + +TIP: Using this function gives access to the message structure, and may +offer more functionality than the simpler xref:nng_send.3.adoc[`nng_send()`] function. + +NOTE: The semantics of what sending a message means vary from protocol to +protocol, so examination of the protocol documentation is encouraged. +(For example, with a xref:nng_pub.7.adoc[_pub_] socket the data is broadcast, so that +any peers who have a suitable subscription will be able to receive it using +xref:nng_recv.3.adoc[`nng_recv()`] or a similar function.) +Furthermore, some protocols may not support sending (such as +xref:nng_sub.7.adoc[_sub_]) or may require other conditions. +(For example, xref:nng_rep.7.adoc[_rep_] sockets cannot normally send data, which +are responses to requests, until they have first received a request.) + +The _flags_ may contain the following value: + +`NNG_FLAG_NONBLOCK`:: + The function returns immediately, regardless of whether + the socket is able to accept the data or not. + If the socket is unable to accept the data (such as if backpressure exists + because the peers are consuming messages too slowly, or no peer is present), + then the function will return with `NNG_EAGAIN`. + If this flag is not specified, then the function will block if such a + condition exists. + + +NOTE: Regardless of the presence or absence of `NNG_FLAG_NONBLOCK`, there may +be queues between the sender and the receiver. +Furthermore, there is no guarantee that the message has actually been delivered. +Finally, with some protocols, the semantic is implicitly `NNG_FLAG_NONBLOCK`, +such as with xref:nng_pub.7.adoc[_pub_] sockets, which are best-effort delivery only. + +## RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +## ERRORS + +* `NNG_EAGAIN`: The operation would block, but `NNG_FLAG_NONBLOCK` was specified. +* `NNG_ECLOSED`: The socket _s_ is not open. +* `NNG_EINVAL`: An invalid set of _flags_ was specified. +* `NNG_EMSGSIZE`: The value of _size_ is too large. +* `NNG_ENOMEM`: Insufficient memory is available. +* `NNG_ENOTSUP`: The protocol for socket _s_ does not support sending. +* `NNG_ESTATE`: The socket _s_ cannot send data in this state. +* `NNG_ETIMEDOUT`: The operation timed out. + +## SEE ALSO + +[nng_msg_alloc][nng_msg_alloc], +[nng_recvmsg][nng_recvmsg], +[nng_send][nng_send], +[nng_strerror][nng_strerror], +[nng_msg][nng_msg], +[nng_socket][nng_socket], +[nng][nng] + +{{#include ../refs.md}} -- cgit v1.2.3-70-g09d2