= nng_aio_begin(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_aio_begin - begin asynchronous I/O operation

== SYNOPSIS

[source, c]
----
#include <nng/nng.h>

bool nng_aio_begin(nng_aio *aio);
----

== DESCRIPTION

The `nng_aio_begin()` function is called by the I/O provider to indicate that
it is going to process the operation.

The function may return `false`, indicating that the _aio_ has been closed
by the caller asynchronously.
In this case the provider should abandon the operation and do nothing else.

This operation should be called at the start of any I/O operation, and must
be called not more than once for a given I/O operation on a given _aio_.

Once this function is called, if `true` is returned, then the provider MUST
guarantee that xref:nng_aio_finish.3.adoc[`nng_aio_finish()`] is called for the _aio_
exactly once, when the operation is complete or canceled.

NOTE: This function is only for I/O providers (those actually performing
the operation such as HTTP handler functions or transport providers); ordinary
users of the _aio_ should not call this function.

== RETURN VALUES

[horizontal]
`true`:: The operation has been started.
`false`:: The operation cannot be started.

== ERRORS

None.

== SEE ALSO

[.text-left]
xref:nng_aio_alloc.3.adoc[nng_aio_alloc(3)],
xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)],
xref:nng_aio_defer.3.adoc[nng_aio_defer(3)],
xref:nng_aio_finish.3.adoc[nng_aio_finish(3)],
xref:nng_aio_result.3.adoc[nng_aio_result(3)],
xref:nng_aio.5.adoc[nng_aio(5)],
xref:nng.7.adoc[nng(7)]