[libvirt] [PATCH 0/3] Improve block job handling docs
Modernize documentation for our APIs and clean up some old cruft. Some of those may be slightly controversial. Peter Krempa (3): qemu: Don't reject making domain persistent if block copy is running lib: Clarify that any block job may block VM save or device detach lib: domain: Emphasise that users should wait for block job READY state via events src/libvirt-domain.c | 33 +++++++++++++-------------------- src/qemu/qemu_driver.c | 6 ------ 2 files changed, 13 insertions(+), 26 deletions(-) -- 2.20.1
Add documentation that the 'VIR_DOMAIN_BLOCK_COPY_TRANSIENT_JOB' flag is auto-assumed if the block copy job is started while the VM is transient and remove the restriction to define the domain when copy is running. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- src/libvirt-domain.c | 13 ++----------- src/qemu/qemu_driver.c | 6 ------ 2 files changed, 2 insertions(+), 17 deletions(-) diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c index 75c9014c0e..c155b36e16 100644 --- a/src/libvirt-domain.c +++ b/src/libvirt-domain.c @@ -6137,11 +6137,6 @@ virDomainGetBlockInfo(virDomainPtr domain, const char *disk, * virDomainUndefine(). A previous definition for this domain would be * overridden if it already exists. * - * Some hypervisors may prevent this operation if there is a current - * block copy operation on a transient domain with the same id as the - * domain being defined; in that case, use virDomainBlockJobAbort() to - * stop the block copy first. - * * virDomainFree should be used to free the resources after the * domain object is no longer needed. * @@ -6185,11 +6180,6 @@ virDomainDefineXML(virConnectPtr conn, const char *xml) * virDomainUndefine(). A previous definition for this domain would be * overridden if it already exists. * - * Some hypervisors may prevent this operation if there is a current - * block copy operation on a transient domain with the same id as the - * domain being defined; in that case, use virDomainBlockJobAbort() to - * stop the block copy first. - * * virDomainFree should be used to free the resources after the * domain object is no longer needed. * @@ -10316,7 +10306,8 @@ virDomainBlockRebase(virDomainPtr dom, const char *disk, * * If @flags contains VIR_DOMAIN_BLOCK_COPY_TRANSIENT_JOB the job will not be * recoverable if the VM is turned off while job is active. This flag will - * remove the restriction of copy jobs to transient domains. + * remove the restriction of copy jobs to transient domains. Note that this flag + * is automatically implied if the VM is transient at the time it's started. * * The @disk parameter is either an unambiguous source name of the * block device (the <source file='...'/> sub-element, such as diff --git a/src/qemu/qemu_driver.c b/src/qemu/qemu_driver.c index 90319261ff..567d39ea35 100644 --- a/src/qemu/qemu_driver.c +++ b/src/qemu/qemu_driver.c @@ -7713,12 +7713,6 @@ qemuDomainDefineXMLFlags(virConnectPtr conn, goto cleanup; def = NULL; - if (qemuDomainHasBlockjob(vm, true)) { - virReportError(VIR_ERR_BLOCK_COPY_ACTIVE, "%s", - _("domain has active block job")); - virDomainObjAssignDef(vm, NULL, false, NULL); - goto cleanup; - } vm->persistent = 1; if (virDomainSaveConfig(cfg->configDir, driver->caps, -- 2.20.1
The documentation was only referring to a copy job, but in fact any running blockjob will have the same results. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- src/libvirt-domain.c | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c index c155b36e16..92a095f00b 100644 --- a/src/libvirt-domain.c +++ b/src/libvirt-domain.c @@ -883,8 +883,8 @@ virDomainSave(virDomainPtr domain, const char *to) * virDomainSaveImageGetXMLDesc() and virDomainSaveImageDefineXML(). * * Some hypervisors may prevent this operation if there is a current - * block copy operation; in that case, use virDomainBlockJobAbort() - * to stop the block copy first. + * block job running; in that case, use virDomainBlockJobAbort() + * to stop the block job first. * * Returns 0 in case of success and -1 in case of failure. */ @@ -8297,8 +8297,8 @@ virDomainDetachDevice(virDomainPtr domain, const char *xml) * persisted device allocation. * * Some hypervisors may prevent this operation if there is a current - * block copy operation on the device being detached; in that case, - * use virDomainBlockJobAbort() to stop the block copy first. + * block job running operation on the device being detached; in that case, + * use virDomainBlockJobAbort() to stop the block job first. * * Beware that depending on the hypervisor and device type, detaching a device * from a running domain may be asynchronous. That is, calling -- 2.20.1
The transition to the ready state is best observed by events as it's ansynchronous and does not hint users to do polling. As currently only the qemu driver supports block copy and block commit and the ready state event was introduced by qemu 1.3 we can fully switch to the new approach. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- src/libvirt-domain.c | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c index 92a095f00b..408a442abc 100644 --- a/src/libvirt-domain.c +++ b/src/libvirt-domain.c @@ -10291,8 +10291,10 @@ virDomainBlockRebase(virDomainPtr dom, const char *disk, * source file; progress in this phase can be tracked via the * virDomainBlockJobInfo() command, with a job type of * VIR_DOMAIN_BLOCK_JOB_TYPE_COPY. The job transitions to the second - * phase when the job info states cur == end, and remains alive to mirror - * all further changes to both source and destination. The user must + * phase when the block job event with state VIR_DOMAIN_BLOCK_JOB_READY is + * emitted for the given device. This information is also it's visible in the + * live XML as 'ready="yes"' attribute of the corresponding <mirror> element. + * All further changes are saved to both source and destination. The user must * call virDomainBlockJobAbort() to end the mirroring while choosing * whether to revert to source or pivot to the destination. An event is * issued when the job ends, and depending on the hypervisor, an event may @@ -10406,9 +10408,9 @@ virDomainBlockCopy(virDomainPtr dom, const char *disk, * of VIR_DOMAIN_BLOCK_JOB_TYPE_ACTIVE_COMMIT, and operates in two phases. * In the first phase, the contents are being committed into @base, and the * job can only be canceled. The job transitions to the second phase when - * the job info states cur == end, and remains alive to keep all further - * changes to @top synchronized into @base; an event with status - * VIR_DOMAIN_BLOCK_JOB_READY is also issued to mark the job transition. + * the block job event with state VIR_DOMAIN_BLOCK_JOB_READY is + * emitted for the given device. This information is also it's visible in the + * live XML as 'ready="yes"' attribute of the corresponding <mirror> element. * Once in the second phase, the user must choose whether to cancel the job * (keeping @top as the active image, but now containing only the changes * since the time the job ended) or to pivot the job (adjusting to @base as -- 2.20.1
On Mon, Jan 21, 2019 at 04:26:45PM +0100, Peter Krempa wrote:
The transition to the ready state is best observed by events as it's ansynchronous and does not hint users to do polling. As currently only the qemu driver supports block copy and block commit and the ready state event was introduced by qemu 1.3 we can fully switch to the new approach.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- src/libvirt-domain.c | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-)
diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c index 92a095f00b..408a442abc 100644 --- a/src/libvirt-domain.c +++ b/src/libvirt-domain.c @@ -10291,8 +10291,10 @@ virDomainBlockRebase(virDomainPtr dom, const char *disk, * source file; progress in this phase can be tracked via the * virDomainBlockJobInfo() command, with a job type of * VIR_DOMAIN_BLOCK_JOB_TYPE_COPY. The job transitions to the second - * phase when the job info states cur == end, and remains alive to mirror - * all further changes to both source and destination. The user must + * phase when the block job event with state VIR_DOMAIN_BLOCK_JOB_READY is + * emitted for the given device. This information is also it's visible in the
is also visible
+ * live XML as 'ready="yes"' attribute of the corresponding <mirror> element. + * All further changes are saved to both source and destination. The user must * call virDomainBlockJobAbort() to end the mirroring while choosing * whether to revert to source or pivot to the destination. An event is * issued when the job ends, and depending on the hypervisor, an event may @@ -10406,9 +10408,9 @@ virDomainBlockCopy(virDomainPtr dom, const char *disk, * of VIR_DOMAIN_BLOCK_JOB_TYPE_ACTIVE_COMMIT, and operates in two phases. * In the first phase, the contents are being committed into @base, and the * job can only be canceled. The job transitions to the second phase when - * the job info states cur == end, and remains alive to keep all further - * changes to @top synchronized into @base; an event with status - * VIR_DOMAIN_BLOCK_JOB_READY is also issued to mark the job transition. + * the block job event with state VIR_DOMAIN_BLOCK_JOB_READY is + * emitted for the given device. This information is also it's visible in the
same here Jano
+ * live XML as 'ready="yes"' attribute of the corresponding <mirror> element. * Once in the second phase, the user must choose whether to cancel the job * (keeping @top as the active image, but now containing only the changes * since the time the job ended) or to pivot the job (adjusting to @base as -- 2.20.1
-- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
On Mon, Jan 21, 2019 at 04:26:42PM +0100, Peter Krempa wrote:
Modernize documentation for our APIs and clean up some old cruft.
Some of those may be slightly controversial.
Peter Krempa (3): qemu: Don't reject making domain persistent if block copy is running lib: Clarify that any block job may block VM save or device detach lib: domain: Emphasise that users should wait for block job READY state via events
src/libvirt-domain.c | 33 +++++++++++++-------------------- src/qemu/qemu_driver.c | 6 ------ 2 files changed, 13 insertions(+), 26 deletions(-)
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
participants (2)
-
Ján Tomko -
Peter Krempa