From 695ec56ffbf3cf1cb4722f5fab33dd2bdb43a9af Mon Sep 17 00:00:00 2001 From: Marcus Brinkmann Date: Fri, 27 Jun 2008 16:07:33 +0000 Subject: 2008-06-27 Marcus Brinkmann * gpgme.texi (Cancellation): Document gpgme_cancel_async. gpgme/ 2008-06-27 Marcus Brinkmann * context.h: Include "sema.h". (struct gpgme_context): New members lock and canceled. * gpgme.c (gpgme_new): Initialize lock. (gpgme_release): Destroy lock. (gpgme_cancel_async): New function. * op-support.c (_gpgme_op_reset): Reset the canceled flag. * wait-global.c (gpgme_wait): Check cancel flag before processing any I/O callbacks. * wait-private.c (_gpgme_wait_on_condition): Likewise. * wait-user.c (_gpgme_user_io_cb_handler): Likewise. --- doc/ChangeLog | 4 ++++ doc/gpgme.texi | 28 +++++++++++++++++++++------- 2 files changed, 25 insertions(+), 7 deletions(-) (limited to 'doc') diff --git a/doc/ChangeLog b/doc/ChangeLog index a6adbdb6..8f5502a7 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,7 @@ +2008-06-27 Marcus Brinkmann + + * gpgme.texi (Cancellation): Document gpgme_cancel_async. + 2008-06-25 Werner Koch * gpgme.texi (Listing Keys): Updated example to the current API. diff --git a/doc/gpgme.texi b/doc/gpgme.texi index 2b96d873..50b82e23 100644 --- a/doc/gpgme.texi +++ b/doc/gpgme.texi @@ -5488,13 +5488,15 @@ private: @cindex aborting operations @cindex cancelling operations -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. +Sometimes you do not want to wait for an operation to finish. +@acronym{GPGME} provides two different functions to achieve that. The +function @code{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 @code{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). @deftypefun gpgme_ctx_t gpgme_cancel (@w{gpgme_ctx_t @var{ctx}}) The function @code{gpgme_cancel} attempts to cancel a pending @@ -5517,6 +5519,18 @@ The function returns an error code if the cancellation failed (in this case the state of @var{ctx} is not modified). @end deftypefun + +@deftypefun gpgme_ctx_t gpgme_cancel_async (@w{gpgme_ctx_t @var{ctx}}) +The function @code{gpgme_cancel} attempts to cancel a pending +operation in the context @var{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 @var{ctx} is not modified). +@end deftypefun + @c ********************************************************** @c ******************* Appendices ************************* @c ********************************************************** -- cgit v1.2.3