File: gpgme.info,  Node: Cancellation,  Prev: Using External Event Loops,  Up: Run Control

7.8.3 Cancellation
------------------

Sometimes you do not want to wait for an operation to finish.  GPGME
provides two different functions to achieve that.  The function
‘gpgme_cancel’ takes effect immediately.  When it returns, the operation
is effectively canceled.  However, it has some limitations and can not
be used with synchronous operations.  In contrast, the function
‘gpgme_cancel_async’ can be used with any context and from any thread,
but it is not guaranteed to take effect immediately.  Instead,
cancellation occurs at the next possible time (typically the next time
I/O occurs in the target context).

 -- Function: gpgme_ctx_t gpgme_cancel (gpgme_ctx_t CTX)
     SINCE: 0.4.5

     The function ‘gpgme_cancel’ attempts to cancel a pending operation
     in the context CTX.  This only works if you use the global event
     loop or your own event loop.

     If you use the global event loop, you must not call ‘gpgme_wait’
     during cancellation.  After successful cancellation, you can call
     ‘gpgme_wait’ (optionally waiting on CTX), and the context CTX will
     appear as if it had finished with the error code ‘GPG_ERR_CANCEL’.

     If you use an external event loop, you must ensure that no I/O
     callbacks are invoked for this context (for example by halting the
     event loop).  On successful cancellation, all registered I/O
     callbacks for this context will be unregistered, and a
     ‘GPGME_EVENT_DONE’ event with the error code ‘GPG_ERR_CANCEL’ will
     be signalled.

     The function returns an error code if the cancellation failed (in
     this case the state of CTX is not modified).

 -- Function: gpgme_ctx_t gpgme_cancel_async (gpgme_ctx_t CTX)
     SINCE: 1.1.7

     The function ‘gpgme_cancel_async’ attempts to cancel a pending
     operation in the context CTX.  This can be called by any thread at
     any time after starting an operation on the context, but will not
     take effect immediately.  The actual cancellation happens at the
     next time GPGME processes I/O in that context.

     The function returns an error code if the cancellation failed (in
     this case the state of CTX is not modified).