[Libguestfs] NOTE: Relaunching handles (don't do it!)

It's possible through the API to do a sequence of calls like this: g = guestfs_create (); guestfs_add_drive (g, "foo"); guestfs_launch (g); guestfs_shutdown (g); guestfs_launch (g); # relaunch the handle The question is, what should be the state of the handle at the second launch? Would the verbose flag still be set if it had been set earlier? (I think fairly obviously yes). Would drives added the first time be automatically added the second time? Since we added hotplugging the answer to the drives question has changed[1]. Previously, any drives added before the first launch are still there, and added implicitly before the second call to launch. Now, the list of drives held in the handle is completely cleared during shutdown, so in the code above, the second launch is called with no drives added[2]. The reason this changed is that hotplugging makes it much more difficult to track drives in the handle across multiple launches. Should drives which were hot-added after launch be added before the second launch? What about drives which have been removed from the list (guestfs_remove_drive) -- should we remember those and magically reinstate them? I should note that neither behaviour was/is documented. The best advice of all is: DO NOT CALL LAUNCH MORE THAN ONCE ON THE SAME HANDLE! Handles are very cheap to create (guestfs_create is basically a malloc). There is no reason not to close the handle after shutdown and start fresh with a new one. ie. to write: g = guestfs_create (); guestfs_add_drive (g, "foo"); guestfs_launch (g); guestfs_shutdown (g); guestfs_close (g); g = guestfs_create (); /* start with a fresh handle */ guestfs_add_drive (g, "foo"); guestfs_launch (g); /* etc. */ Because of our commitment to ABI compatibility (where the behaviour is documented), I'm not going to stop people from re-launching the handle. But it's still best to avoid it. Rich. [1] https://github.com/libguestfs/libguestfs/commit/ed7fda161e1f3d0beb02a368f... https://github.com/libguestfs/libguestfs/commit/33f49d85c2a82e66f33cedccb... [2] This may or may not cause an error depending on the backend -- with the libvirt backend you're now allowed to launch a handle with no drives. -- Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones Read my programming blog: http://rwmj.wordpress.com Fedora now supports 80 OCaml packages (the OPEN alternative to F#) http://cocan.org/getting_started_with_ocaml_on_red_hat_and_fedora