Patchwork [15/30] block: fix documentation of block_job_cancel_sync

login
register
mail settings
Submitter Kevin Wolf
Date Sept. 28, 2012, 5:56 p.m.
Message ID <1348855033-17174-16-git-send-email-kwolf@redhat.com>
Download mbox | patch
Permalink /patch/187860/
State New
Headers show

Comments

Kevin Wolf - Sept. 28, 2012, 5:56 p.m.
From: Paolo Bonzini <pbonzini@redhat.com>

Do this in a separate commit before we move the functions to
blockjob.h.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Signed-off-by: Kevin Wolf <kwolf@redhat.com>
---
 block_int.h |   12 +++++-------
 1 files changed, 5 insertions(+), 7 deletions(-)

Patch

diff --git a/block_int.h b/block_int.h
index 56164a7..6b6b3ab 100644
--- a/block_int.h
+++ b/block_int.h
@@ -425,15 +425,13 @@  void block_job_cancel(BlockJob *job);
 bool block_job_is_cancelled(BlockJob *job);
 
 /**
- * block_job_cancel:
+ * block_job_cancel_sync:
  * @job: The job to be canceled.
  *
- * Asynchronously cancel the job and wait for it to reach a quiescent
- * state.  Note that the completion callback will still be called
- * asynchronously, hence it is *not* valid to call #bdrv_delete
- * immediately after #block_job_cancel_sync.  Users of block jobs
- * will usually protect the BlockDriverState objects with a reference
- * count, should this be a concern.
+ * Synchronously cancel the job.  The completion callback is called
+ * before the function returns.  The job may actually complete
+ * instead of canceling itself; the circumstances under which this
+ * happens depend on the kind of job that is active.
  *
  * Returns the return value from the job if the job actually completed
  * during the call, or -ECANCELED if it was canceled.