Previous: Using External Event Loops, Up: Run Control

7.7.3 Cancellation

Sometimes you do not want to wait for an operation to finish. If you use external I/O callbacks, you can cancel a pending operation. However, you must ensure that no other thread is currently using the context in which the operation you want to cancel runs. This includes callback handlers. So your external event loop must either be halted or otherwise it must be guaranteed that no installed I/O callbacks are run for this context.

— Function: gpgme_ctx_t gpgme_cancel (gpgme_ctx_t ctx)

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 or 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 your 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 signaled.

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