Re: [Qemu-devel] [PATCH v2 2.1 3/3] docs/qmp: Fix documentation of BLOCK_JOB_READY to match code

[Kevin Wolf <kwolf@redhat.com>]

Am 02.07.2014 um 08:49 hat Markus Armbruster geschrieben:
> Eric Blake <eblake@redhat.com> writes:
> 
> > On 06/27/2014 11:24 AM, Markus Armbruster wrote:
> >> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> >> ---
> >>  docs/qmp/qmp-events.txt | 12 ++++++++++--
> >>  1 file changed, 10 insertions(+), 2 deletions(-)
> >> 
> >> diff --git a/docs/qmp/qmp-events.txt b/docs/qmp/qmp-events.txt
> >> index 22fea58..44be891 100644
> >> --- a/docs/qmp/qmp-events.txt
> >> +++ b/docs/qmp/qmp-events.txt
> >> @@ -157,12 +157,20 @@ Emitted when a block job is ready to complete.
> >>  
> >>  Data:
> >>  
> >> -- "device": device name (json-string)
> >> +- "type":     Job type (json-string; "stream" for image streaming
> >> +                                     "commit" for block commit)
> >> +- "device":   Device name (json-string)
> >> +- "len":      Maximum progress value (json-int)
> >> +- "offset":   Current progress value (json-int)
> >> +              On success this is equal to len.
> >> +              On failure this is less than len.
> >> +- "speed":    Rate limit, bytes per second (json-int)
> >>  
> >
> > Design question - if BLOCK_JOB_READY reports failure (that is, offset <
> > len), are we still guaranteed to get a BLOCK_JOB_COMPLETED that also
> > reports failure, or does 'query-blockjobs' completely forget about the
> > job?
> 
> Good one.  It's underspecified, as far as I can tell.  First step to fix
> that is to find out what the code does.

As far as I can see, BLOCK_JOB_READY implies success up to the point
where the event was emitted. Should we document that len = offset in all
cases? Perhaps add an assertion to block_job_event_ready(), too?

Kevin