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

[Richard W.M. Jones]

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/ed7fda161e1f3d0beb02a368fcbcf5ed95dcdac1
    https://github.com/libguestfs/libguestfs/commit/33f49d85c2a82e66f33cedccb2dbd14faa6070dd

[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