[libvirt] [PATCH 2/2] virsh: man: Document asynchronous behaviour of detach-device-alias

[Peter Krempa]

On Mon, Mar 18, 2019 at 13:24:35 +0100, Michal Privoznik wrote:
> On 3/18/19 8:19 AM, Peter Krempa wrote:
> > This command is fully async. Note that users can use virsh event to be
> > notified of the guest actually removing the device.
> > 
> > Signed-off-by: Peter Krempa <pkrempa at redhat.com>
> > ---
> >   tools/virsh.pod | 5 ++++-
> >   1 file changed, 4 insertions(+), 1 deletion(-)
> > 
> > diff --git a/tools/virsh.pod b/tools/virsh.pod
> > index 39ff8cd7c9..2889e17531 100644
> > --- a/tools/virsh.pod
> > +++ b/tools/virsh.pod
> > @@ -3290,7 +3290,10 @@ I<--persistent>.
> >   =item B<detach-device-alias> I<domain> I<alias>
> >   [[[I<--live>] [I<--config>] | [I<--current>]]]]
> > 
> > -Detach a device with given I<alias> from the I<domain>.
> > +Detach a device with given I<alias> from the I<domain>. This command returns
> > +successfully after the unplug request was sent to the hypervisor. The actual
> > +removal of the device is notified asynchronously via libvirt events
> > +(see virsh event).
> 
> This is not enterly true. Under the hood both detach-device and
> detach-device-alias call qemuDomainDetachDeviceLive() which takes
> virDomainDeviceDefPtr and which calls qemuDomainWaitForDeviceRemoval() after
> talking to the monitor.

detach-device-alias sets the @async parameter of
qemuDomainDetachDeviceLive to true which very specifically skips
qemuDomainWaitForDeviceRemoval in any subsequent worker thus no
synchronous behaviour is done.

Note that e.g. in case of memory unplug if the guest is quick enough
detach-device can even report an error when the device unplug is
rejected. detach-device-alias can't do that as it does not call
qemuDomainWaitForDeviceRemoval contrary to what you claim above.

> 
> I'm failing to see why this note is here for detach-device-alias and not for
> plain detach-device.

Because the aynchronous behaviour is not expected for
detach-device and thus it requires more explanation whereas detach-device-alias
was properly designed as fully async.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20190318/84498e09/attachment-0001.sig>