[libvirt] [PATCH] 514532 Fix man page, most operation are synchronous
As pointed in https://bugzilla.redhat.com/show_bug.cgi?id=514532 we were historically warning about operation being asynchronous in the man page but actually most operations are synchronous. I still kept a warning about domain creation and shutdown, maybe we should add a few more, but as is this is mostly correct and better than the current description IMHO Maybe we should flag formally in the description all APIs which have an asynchronous behaviour. 514532 Fix man page, most operation are synchronous * tools/virsh.pod: the man page was stating that most operations are asynchronous while in fact most of them are synchronous except domain creation and shutdown diff --git a/tools/virsh.pod b/tools/virsh.pod index 55ec64a..2986c34 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -40,12 +40,11 @@ Most B<virsh> commands require root privileges to run due to the communications channels used to talk to the hypervisor. Running as non root will return an error. -Most B<virsh> commands act asynchronously, so just because the B<virsh> -program returned, doesn't mean the action is complete. This is -important, as many operations on domains, like create and shutdown, -can take considerable time (30 seconds or more) to bring the machine -into a fully compliant state. If you want to know when one of these -actions has finished you must poll through virsh list periodically. +Most B<virsh> commands act synchronously, except maybe shutdown +and domain creation. In those case the fact that the B<virsh> +program returned, may not mean the action is complete and you +must poll through virsh list periodically to detect that the +operation completed. =head1 GENERIC COMMANDS -- Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/ daniel@veillard.com | Rpmfind RPM search engine http://rpmfind.net/ http://veillard.com/ | virtualization library http://libvirt.org/
On Wed, Nov 18, 2009 at 02:31:12PM +0100, Daniel Veillard wrote:
-Most B<virsh> commands act asynchronously, so just because the B<virsh> -program returned, doesn't mean the action is complete. This is -important, as many operations on domains, like create and shutdown, -can take considerable time (30 seconds or more) to bring the machine -into a fully compliant state. If you want to know when one of these -actions has finished you must poll through virsh list periodically. +Most B<virsh> commands act synchronously, except maybe shutdown +and domain creation. In those case the fact that the B<virsh> +program returned, may not mean the action is complete and you +must poll through virsh list periodically to detect that the +operation completed.
Shutdown is async, but domain creation is certainly supposed to be synchronous. Of course the guest may immediately crash so appear inactive again just after create returns Thinking about it, I believe virDomainShutdown/Reboot, and the SetMemory and SetVcpus are the only two APIs that are allowed to be async, because they merely update the guest, but don't wait for it to react. Daniel -- |: Red Hat, Engineering, London -o- http://people.redhat.com/berrange/ :| |: http://libvirt.org -o- http://virt-manager.org -o- http://ovirt.org :| |: http://autobuild.org -o- http://search.cpan.org/~danberr/ :| |: GnuPG: 7D3B9505 -o- F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|
On Thu, Nov 19, 2009 at 04:34:12PM +0000, Daniel P. Berrange wrote:
On Wed, Nov 18, 2009 at 02:31:12PM +0100, Daniel Veillard wrote:
-Most B<virsh> commands act asynchronously, so just because the B<virsh> -program returned, doesn't mean the action is complete. This is -important, as many operations on domains, like create and shutdown, -can take considerable time (30 seconds or more) to bring the machine -into a fully compliant state. If you want to know when one of these -actions has finished you must poll through virsh list periodically. +Most B<virsh> commands act synchronously, except maybe shutdown +and domain creation. In those case the fact that the B<virsh> +program returned, may not mean the action is complete and you +must poll through virsh list periodically to detect that the +operation completed.
Shutdown is async, but domain creation is certainly supposed to be synchronous. Of course the guest may immediately crash so appear inactive again just after create returns
Well I was also thinking that Create like Shutdown, the process is at best started in the Domain OS but completion can't be asserted just because the command started. I think the idea of creating the guess is also implicitely tied with the OS booting th the mind of users, and well their domain won't respond to requests for a little bit even if the create succeeded.
Thinking about it, I believe virDomainShutdown/Reboot, and the SetMemory and SetVcpus are the only two APIs that are allowed to be async, because they merely update the guest, but don't wait for it to react.
Okay I was wondering for all our storage operations, some of thse can certainly take a very long time. Network operations should be more or less instant. Daniel -- Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/ daniel@veillard.com | Rpmfind RPM search engine http://rpmfind.net/ http://veillard.com/ | virtualization library http://libvirt.org/
On Thu, Nov 19, 2009 at 06:02:26PM +0100, Daniel Veillard wrote:
On Thu, Nov 19, 2009 at 04:34:12PM +0000, Daniel P. Berrange wrote:
On Wed, Nov 18, 2009 at 02:31:12PM +0100, Daniel Veillard wrote:
-Most B<virsh> commands act asynchronously, so just because the B<virsh> -program returned, doesn't mean the action is complete. This is -important, as many operations on domains, like create and shutdown, -can take considerable time (30 seconds or more) to bring the machine -into a fully compliant state. If you want to know when one of these -actions has finished you must poll through virsh list periodically. +Most B<virsh> commands act synchronously, except maybe shutdown +and domain creation. In those case the fact that the B<virsh> +program returned, may not mean the action is complete and you +must poll through virsh list periodically to detect that the +operation completed.
Shutdown is async, but domain creation is certainly supposed to be synchronous. Of course the guest may immediately crash so appear inactive again just after create returns
Well I was also thinking that Create like Shutdown, the process is at best started in the Domain OS but completion can't be asserted just because the command started. I think the idea of creating the guess is also implicitely tied with the OS booting th the mind of users, and well their domain won't respond to requests for a little bit even if the create succeeded.
Thinking about it, I believe virDomainShutdown/Reboot, and the SetMemory and SetVcpus are the only two APIs that are allowed to be async, because they merely update the guest, but don't wait for it to react.
Okay, fixed the pod accordingly and pushed, thanks ! Daniel -- Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/ daniel@veillard.com | Rpmfind RPM search engine http://rpmfind.net/ http://veillard.com/ | virtualization library http://libvirt.org/
participants (2)
-
Daniel P. Berrange -
Daniel Veillard