Previous: 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)

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).

— Function: gpgme_ctx_t gpgme_cancel_async (gpgme_ctx_t ctx)

The function gpgme_cancel 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).