[libvirt] [PATCH v2 4/8] Clarify virDomainDetachDeviceFlags documentation

[Daniel P. Berrange]

On Thu, Jul 18, 2013 at 12:03:46PM +0200, Jiri Denemark wrote:
> ---
> 
> Notes:
>     Version 2:
>     - document limited waiting to make most async removal synchronous
> 
>  src/libvirt.c | 16 ++++++++++++++++
>  1 file changed, 16 insertions(+)
> 
> diff --git a/src/libvirt.c b/src/libvirt.c
> index 0cdac0d..1f44a28 100644
> --- a/src/libvirt.c
> +++ b/src/libvirt.c
> @@ -10889,6 +10889,22 @@ error:
>   * block copy operation on the device being detached; in that case,
>   * use virDomainBlockJobAbort() to stop the block copy first.
>   *
> + * Beware that depending on the hypervisor and device type, detaching a device
> + * from a running domain may be asynchronous. That is, calling
> + * virDomainDetachDeviceFlags may just request device removal while the device
> + * is actually removed later (in cooperation with a guest OS). Previously,
> + * this fact was ignored and the device could have been removed from domain
> + * configuration before it was actually removed by the hypervisor causing
> + * various failures on subsequent operations. To check whether the device was
> + * successfully removed, either recheck domain configuration using
> + * virDomainGetXMLDesc() or add handler for VIR_DOMAIN_EVENT_ID_DEVICE_REMOVED
> + * event. In case the device is already gone when virDomainDetachDeviceFlags
> + * returns, the event is delivered before this API call ends. To help existing
> + * clients work better in most cases, this API will try to transform an
> + * asynchronous device removal that finishes shortly after the request into
> + * a synchronous removal. In other words, this API may wait a bit for the
> + * removal to complete in case it was not synchronous.
> + *
>   * Returns 0 in case of success, -1 in case of failure.
>   */
>  int

ACK


Daniel
-- 
|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org              -o-             http://virt-manager.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org       -o-       http://live.gnome.org/gtk-vnc :|