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

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