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