Re: [Qemu-devel] [RFC v4 19/21] blockjobs: Expose manual property

[Eric Blake]

On 02/27/2018 03:57 PM, John Snow wrote:
> On 02/27/2018 03:16 PM, Eric Blake wrote:
> > On 02/23/2018 05:51 PM, John Snow wrote:
> > > Expose the "manual" property via QAPI for the backup-related jobs.
> > > As of this commit, this allows the management API to request the
> > > "concluded" and "dismiss" semantics for backup jobs.

> > > +# @manual: True to use an expanded, more explicit job control flow.
> > > +#          Jobs may transition from a running state to a pending state,
> > > +#          where they must be instructed to complete manually via
> > > +#          block-job-finalize.
> > > +#          Jobs belonging to a transaction must either all or all not
> > > use this
> > > +#          setting. Once a transaction reaches a pending state,
> > > issuing the
> > > +#          finalize command to any one job in the transaction is
> > > sufficient
> > > +#          to finalize the entire transaction.
> >
> > The previous commit message talked about mixed-manual transactions, but
> > this seems to imply it is not possible.  I'm fine if we don't support
> > mixed-manual transactions, but wonder if it means any changes to the
> > series.
> >
> > Otherwise looks reasonable from the UI point of view.
>
> More seriously, this documentation I wrote doesn't address the totality
> of the expanded flow. I omitted dismiss here by accident as well. This
> is at best a partial definition of the 'manual' property.
>
> I'd like to use _this_ patch to ask the question: "What should the
> proper noun for the QEMU 2.12+ Expanded Block Job Management Flow
> Mechanism be?"

"Manual" actually doesn't sound too bad; I could also see "Explicit job 
flow", as in, "within a transaction, all jobs should have the same 
setting for the choice of Explicit Job Flow" (but then the name 'manual' 
would have to be changed to match).  The idea of a central document, 
that gets referred to from multiple spots in the QAPI docs, rather than 
duplicating information throughout the QAPI docs, is reasonable.

> I'm not too sure, but "Manual mode" leaves a lot to be desired.
>
> I keep calling it something like "2.12+ Job Management" but that's not
> really descriptive.

That, and if someone ever backports the enhanced state machine to a 2.11 
branch, it becomes a misnomer.

> I conceptualize the feature as the addition of a
> purposefully more "needy" and less automatic completion mechanism, hence
> the "manual"
>
> Anyway, I'd like to figure out a good "documentation name" for it so I
> can point all instances of the creation property (for drive-backup,
> drive-mirror, and everyone else) to a central location that explains the
> STM and what exactly the differences between manual=on/off are. I'd then
> like to expose this property via query and link the documentation there
> to this description, too.

"Explicit" and "Manual" are the two best options coming to me as I type 
this email.

> It'd be nice-- under the same arguments that prompted 'dismiss'-- to say
> that if a client crashes it can reconnect and discover what kind of
> attention certain jobs will need by asking for the manual property back.
>
> --js

--
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org