NAME

       nng_aio_defer - defer asynchronous I/O operation

SYNOPSIS

           #include <nng/nng.h>

           typedef void (*nng_aio_cancelfn)(nng_aio *aio, void *arg, int err);

           void nng_aio_defer(nng_aio *aio, nng_aio_cancelfn fn, void *arg);

DESCRIPTION

       The nng_aio_defer() function marks operation associated with aio as being deferred for
       asynchronous completion, and also registers a cancellation function fn and associated
       argument arg, thereby permitting the operation to be canceled.

       If the aio is being canceled, the cancellation routine fn will be called with the aio, the
       arg specified by nng_aio_defer(), and an error value in err, which is the reason that the
       operation is being canceled.

       The operation may not be cancelable; for example it may have already been completed, or be
       in a state where it is no longer possible to unschedule it. In this case, the cancelfn
       should just return without making any changes.

       If the cancellation routine successfully canceled the operation, it should ensure that
       nng_aio_finish() is called, with the error code specified by err.

           Important
           It is mandatory that I/O providers call nng_aio_finish() EXACTLY ONCE when they are
           finished with the operation.

           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.

           Note
           Care must be taken to ensure that cancellation and completion of the routine are
           multi-thread safe; this will usually involve the use of locks or other synchronization
           primitives.

           Tip
           For operations that complete synchronously, without any need to be deferred, the
           provider should not bother to call nng_aio_defer(), although it is harmless if it
           does.

RETURN VALUES

       None.

ERRORS

       None.

SEE ALSO

       nng_aio_alloc(3), nng_aio_cancel(3), nng_aio_finish(3), nng_aio_result(3), nng_aio(5),
       nng(7)

                                            2024-10-11                           NNG_AIO_DEFER(3)