1= nng_aio_alloc(3)
2//
3// Copyright 2021 Staysail Systems, Inc. <info@staysail.tech>
4// Copyright 2018 Capitar IT Group BV <info@capitar.com>
5//
6// This document is supplied under the terms of the MIT License, a
7// copy of which should be located in the distribution where this
8// file was obtained (LICENSE.txt).  A copy of the license may also be
9// found online at https://opensource.org/licenses/MIT.
10//
11
12== NAME
13
14nng_aio_alloc - allocate asynchronous I/O handle
15
16== SYNOPSIS
17
18[source, c]
19----
20#include <nng/nng.h>
21
22int nng_aio_alloc(nng_aio **aiop, void (*callb)(void *), void *arg);
23----
24
25== DESCRIPTION
26
27The `nng_aio_alloc()` function allocates a handle for ((asynchronous I/O))
28operations, and stores a pointer to it in __aiop__.
29The handle is initialized with a completion ((callback)) of _callb_,
30which will be executed when an associated asynchronous operation finishes.
31It will be called with the argument _arg_.
32
33NOTE: The callback _callb_ must not perform any blocking operations, and
34must complete its execution quickly.  If _callb_ does block, this can
35lead ultimately to an apparent "hang" or deadlock in the application.
36This also means you should avoid operations such as allocating new objects,
37which also means opening or closing sockets, dialers, and so forth.
38
39TIP: If more complex or blocking work needs to be performed by _callb_, a separate
40thread can be used, along with a xref:nng_cv_alloc.3.adoc[condition variable]
41which can be signaled by the callback.
42
43Asynchronous I/O operations all take an xref:nng_aio.5.adoc[`nng_aio`]
44handle such as allocated by this function.
45Such operations are usually started by a function that returns immediately.
46The operation is then run asynchronously, and completes sometime later.
47When that operation is complete, the callback supplied here is called,
48and that callback is able to determine the result of the operation using
49xref:nng_aio_result.3.adoc[`nng_aio_result()`],
50xref:nng_aio_count.3.adoc[`nng_aio_count()`],
51and xref:nng_aio_get_output.3.adoc[`nng_aio_get_output()`].
52
53It is possible to wait synchronously for an otherwise asynchronous operation
54by using the function xref:nng_aio_wait.3.adoc[`nng_aio_wait()`].
55In that case, it is permissible for _callb_ and _arg_ to both be `NULL`.
56Note that if these are `NULL`, then it will not be possible to determine when the
57operation is complete except by calling the aforementioned
58xref:nng_aio_wait.3.adoc[`nng_aio_wait()`].
59
60== RETURN VALUES
61
62This function returns 0 on success, and non-zero otherwise.
63
64== ERRORS
65
66[horizontal]
67`NNG_ENOMEM`:: Insufficient free memory to perform the operation.
68
69== SEE ALSO
70
71[.text-left]
72xref:nng_aio_abort.3.adoc[nng_aio_abort(3)],
73xref:nng_aio_cancel.3.adoc[nng_aio_cancel(3)],
74xref:nng_aio_count.3.adoc[nng_aio_count(3)],
75xref:nng_aio_free.3.adoc[nng_aio_free(3)],
76xref:nng_aio_get_input.3.adoc[nng_aio_get_input(3)],
77xref:nng_aio_get_msg.3.adoc[nng_aio_get_msg(3)],
78xref:nng_aio_get_output.3.adoc[nng_aio_get_output(3)],
79xref:nng_aio_result.3.adoc[nng_aio_result(3)],
80xref:nng_aio_set_input.3.adoc[nng_aio_set_input(3)],
81xref:nng_aio_set_iov.3.adoc[nng_aio_set_iov(3)],
82xref:nng_aio_set_msg.3.adoc[nng_aio_set_msg(3)],
83xref:nng_aio_set_timeout.3.adoc[nng_aio_set_timeout(3)],
84xref:nng_aio_stop.3.adoc[nng_aio_stop(3)],
85xref:nng_aio_wait.3.adoc[nng_aio_wait(3)],
86xref:nng_strerror.3.adoc[nng_strerror(3)],
87xref:nng_aio.5.adoc[nng_aio(5)],
88xref:nng.7.adoc[nng(7)]
89