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. >> >> Signed-off-by: John Snow <js...@redhat.com> >> --- >> blockdev.c | 19 ++++++++++++++++--- >> qapi/block-core.json | 32 ++++++++++++++++++++++++++------ >> 2 files changed, 42 insertions(+), 9 deletions(-) >> > >> +++ b/qapi/block-core.json >> @@ -1177,6 +1177,16 @@ >> # @job-id: identifier for the newly-created block job. If >> # omitted, the device name will be used. (Since 2.7) >> # >> +# @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?" 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. 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. 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
