2008-06-27 Marcus Brinkmann <[email protected]>

	* gpgme.texi (Cancellation): Document gpgme_cancel_async.

gpgme/
2008-06-27  Marcus Brinkmann  <[email protected]>

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

2 files changed, 25 insertions, 7 deletions

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  <[email protected]>
+
+	* gpgme.texi (Cancellation): Document gpgme_cancel_async.
+
 2008-06-25  Werner Koch  <[email protected]>
 
 	* 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 **********************************************************