Patchwork [v2,03/45] block: fix documentation of block_job_cancel_sync

login
register
mail settings
Submitter Paolo Bonzini
Date Sept. 26, 2012, 3:56 p.m.
Message ID <1348675011-8794-4-git-send-email-pbonzini@redhat.com>
Download mbox | patch
Permalink /patch/187108/
State New
Headers show

Comments

Paolo Bonzini - Sept. 26, 2012, 3:56 p.m.
Do this in a separate commit before we move the functions to
blockjob.h.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
        v1->v2: split out of the next patch

 block_int.h | 4 ++--
 1 file modificato, 2 inserzioni(+), 2 rimozioni(-)
Kevin Wolf - Sept. 27, 2012, 12:03 p.m.
Am 26.09.2012 17:56, schrieb Paolo Bonzini:
> Do this in a separate commit before we move the functions to
> blockjob.h.
> 
> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
> ---
>         v1->v2: split out of the next patch
> 
>  block_int.h | 4 ++--
>  1 file modificato, 2 inserzioni(+), 2 rimozioni(-)
> 
> diff --git a/block_int.h b/block_int.h
> index ac4245c..7bb95b7 100644
> --- a/block_int.h
> +++ b/block_int.h
> @@ -425,10 +425,10 @@ 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
> + * Synchronously 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

I still don't agree with the s/Async/Sync/, in my opinion it contradicts
the rest of the comment. If it did cancel the job synchronously, then
the job would be immediately completed, and there would be no need to
wait for a quiescent state nor would the completion callback occur later.

Kevin
Paolo Bonzini - Sept. 27, 2012, 12:08 p.m.
Il 27/09/2012 14:03, Kevin Wolf ha scritto:
>> >  /**
>> > - * 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
>> > + * Synchronously 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
> I still don't agree with the s/Async/Sync/, in my opinion it contradicts
> the rest of the comment. If it did cancel the job synchronously, then
> the job would be immediately completed, and there would be no need to
> wait for a quiescent state nor would the completion callback occur later.

Now that I read it again, the comment is obsolete.

block_job_cancel_sync stalls until block_job_cancel_cb is called, and
that calls the completion callback.

Paolo
Kevin Wolf - Sept. 27, 2012, 12:13 p.m.
Am 27.09.2012 14:08, schrieb Paolo Bonzini:
> Il 27/09/2012 14:03, Kevin Wolf ha scritto:
>>>>  /**
>>>> - * 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
>>>> + * Synchronously 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
>> I still don't agree with the s/Async/Sync/, in my opinion it contradicts
>> the rest of the comment. If it did cancel the job synchronously, then
>> the job would be immediately completed, and there would be no need to
>> wait for a quiescent state nor would the completion callback occur later.
> 
> Now that I read it again, the comment is obsolete.
> 
> block_job_cancel_sync stalls until block_job_cancel_cb is called, and
> that calls the completion callback.

Okay. Best you rephrase the whole comment then instead of changing just
one word.

Kevin

Patch

diff --git a/block_int.h b/block_int.h
index ac4245c..7bb95b7 100644
--- a/block_int.h
+++ b/block_int.h
@@ -425,10 +425,10 @@  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
+ * Synchronously 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