[libvirt] [PATCH 03/12] Clarify virDomainDetachDeviceFlags documentation

[Daniel P. Berrange]

On Mon, Jul 15, 2013 at 07:11:04PM +0200, Jiri Denemark wrote:
> ---
>  src/libvirt.c | 12 ++++++++++++
>  1 file changed, 12 insertions(+)
> 
> diff --git a/src/libvirt.c b/src/libvirt.c
> index 4dc91d7..860188b 100644
> --- a/src/libvirt.c
> +++ b/src/libvirt.c
> @@ -10825,6 +10825,18 @@ 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.
> + *
>   * Returns 0 in case of success, -1 in case of failure.
>   */
>  int

This will need rewording based on my proposal that we should
wait for completion.


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 :|