nng_send*mdbook

1 files changed, 75 insertions, 0 deletions

diff --git a/docs/reference/src/sock/nng_send_aio.md b/docs/reference/src/sock/nng_send_aio.md
new file mode 100644
index 00000000..9f6b43c8
--- /dev/null
+++ b/docs/reference/src/sock/nng_send_aio.md
@@ -0,0 +1,75 @@
+# nng_send_aio
+
+## NAME
+
+nng_send_aio --- send message asynchronously
+
+## SYNOPSIS
+
+```
+#include <nng/nng.h>
+
+void nng_send_aio(nng_socket s, nng_aio *aio);
+```
+
+## DESCRIPTION
+
+The `nng_send_aio()` sends a [message][msg] using the
+[socket][socket] _s_ asynchronously.
+
+The message to send must have previously been set on the _aio_
+using the [`nng_aio_set_msg()`][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 complete[^1], and [`nng_aio_result()`][nng_aio_result]
+will return zero. In this case the socket will dispose of the
+message when it is finished with it.
+
+[^1]:
+    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_ {{i:callback}} will be executed and
+`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
+[`nng_aio_get_msg()`][nng_aio_get_msg] and dispose of it appropriately. [^2]
+(This may include retrying the send operation on the same or a different
+socket, or deallocating the message with [`nng_msg_free()`][nng_msg_free].)
+
+[^2]: Failure to do so will leak the memory associated with the message.
+
+> [!NOTE]
+> The semantics of what sending a message means varies from protocol to
+> protocol, so examination of the protocol documentation is encouraged.
+> Furthermore, some protocols may not support sending,
+> or may only permit sending when other conditions are met.
+
+## 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
+
+[Asynchronous I/O][aio],
+[Messages][msg],
+[Sockets][socket],
+[nng_aio_get_msg][nng_aio_get_msg],
+[nng_aio_set_msg][nng_aio_set_msg],
+[nng_msg_alloc][nng_msg_alloc]
+
+{{#include ../refs.md}}