= nng_send_aio(3)
//
// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
// Copyright 2018 Capitar IT Group BV <info@capitar.com>
//
// 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 <nng/nng.h>

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)]