[PATCH 0/2] Implement guestfs_available API.
These two patches are the implementation of the guestfs_available API. Rich. -- 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
-- Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones libguestfs lets you edit virtual machines. Supports shell scripting, bindings from many languages. http://et.redhat.com/~rjones/libguestfs/ See what it can do: http://et.redhat.com/~rjones/libguestfs/recipes.html
On 20/11/09 15:12, Richard W.M. Jones wrote:
From e24b0b7fb4160af4c82107c55176353abc07b69a Mon Sep 17 00:00:00 2001 From: Richard Jones<rjones@redhat.com> Date: Fri, 20 Nov 2009 13:06:49 +0000 Subject: [PATCH 1/2] availability: Add guestfs_available.
Start a new API allowing groups of functions to be tested for availability.
There are two reasons for this:
(1) If libguestfs is built with missing dependencies (eg. no Augeas lib) then the corresponding functions are disabled in the appliance. Up till now there has been no way to test for this except to speculatively issue commands and check for errors.
(2) When we port the daemon to Win32 it is likely that major pieces of functionality won't be available (eg. LVM support). This API gives a way to test for that.
There is no change for existing clients: you still have to check for errors from individual API calls.
For new clients, you will be able to test for availability of particular APIs.
Usage scenario (A): An LVM editing tool which requires both the LVM API and inotify in order to function at all:
char *apis[] = { "inotify", "lvm2", NULL }; r = guestfs_available (g, apis); if (r == -1) { /* print an error and exit */ }
Usage scenario (B): A general purpose tool which optionally provides configuration file editing, but this can be disabled, the result merely being reduced functionality:
char *apis[] = { "augeas", NULL }; r = guestfs_available (g, apis); enable_config_edit_menus = r == 0;
We've been over much of this on IRC, but I think this is the wrong API. Depending on how you choose to manage groups, there are 2 possible reasons why this is the wrong API: 1. Groups remain static ----------------------- In the static group management policy an API group remains constant forever. New APIs are either omitted or added to a new group. This policy has the advantage of having a well-defined meaning. i.e. you can look at the documentation and be sure that if guestfs_available("augeas") returns true then a certain set of augeas APIs are definitely implemented. The problem with this policy is that the groups become unmanageable as new APIs are added. So in a year's time I want to required the full range of augeas apis. I have to remember to check 'augeas', 'augeas_new', 'augeas_newer' and 'augeas_newer_still'. What's more, the mapping to these things is arbitrary because the base has a huge wadge of stuff in it, whereas the incrementals are very small and I can't remember what falls in which bucket. Unless I use this API day in, day out, I will need to head over to the documentation every time to look up the group mappings I need. We end up with a proliferation of unmemorable groups. On the other hand, if we changed the API to instead test individual APIs, the mappings would be both obvious and managable. This is the wrong model because it will be unusable soon after release. 2. Groups are updated to include new APIs ----------------------------------------- In this model, a new augeas call would be added to the augeas group. This policy can no longer be called 'availability' because it does not determine the availability of an API. For example, augeas_new is introduced in libguestfs version X, and the augeas group is updated. The problem now is that if the code is run agains libguestfs version X-1, the test for 'augeas' returns true, despite the fact that my API is not available. For completeness, we also discussed the possibility of versioning groups. We discounted this on the basis that version numbers have little meaning in the face of backports. As I see it, there is no group policy which would make this API usable, except dropping the concept of groups entirely and testing APIs directly. To avoid me having to expound 2 independent arguments, if you can clarify which group management policy you favour, I will gladly expand further on why it is a bad idea. In case it's not obvious, I wouldn't have approved this API ;) Matt -- Matthew Booth, RHCA, RHCSS Red Hat Engineering, Virtualisation Team M: +44 (0)7977 267231 GPG ID: D33C3490 GPG FPR: 3733 612D 2D05 5458 8A8A 1600 3441 EA19 D33C 3490
On Mon, Nov 23, 2009 at 04:54:55PM +0000, Matthew Booth wrote:
To avoid me having to expound 2 independent arguments, if you can clarify which group management policy you favour, I will gladly expand further on why it is a bad idea.
Let's have some definitions first: function: An individual guestfs function, eg. guestfs_pread group: Some broad feature of libguestfs, at the moment limited to defining just a set of functions. Groups of functions can overlap. You can already test whether libguestfs.so contains individual function calls, using dlopen. In the example below I linked a program dynamically against a recent version of libguestfs.so which has the symbol guestfs_dd. I then ran the program against the recent libguestfs.so and against an older libguestfs.so which lacked this symbol. As you can see, the presence or absence of the function was detected. $ gcc -I ~/d/libguestfs/src -L ~/d/libguestfs/src/.libs -Wall test-dd.c -lguestfs -ldl -o test-dd $ ./test-dd this libguestfs.so does NOT have guestfs_dd function $ LD_LIBRARY_PATH=~/d/libguestfs/src/.libs ./test-dd this libguestfs.so has guestfs_dd function (Program attached). However the fact that a function is available in libguestfs.so doesn't mean that it is available in the appliance (for two reasons: you might be using an older appliance, or the appliance itself might not have implemented the function). Therefore the only way to truly know if a function is available and will work is to try to run the function and test if it returns an error. This advice hasn't changed, and the guestfs_available call documentation clearly states that you have to do this. So you may be wondering what guestfs_available is for if it can't test for availability of function(s). guestfs_available is designed for two scenarios (outlined in [1]). Either you can use it to fail early when a group of functions that you need is definitely not available in the appliance at runtime. You can fail early with a clear error message. Or you can use it to disable part of a tool's functionality. [1] http://git.annexia.org/?p=libguestfs.git;a=commit;h=8fd7f255d611d2092a244c4a... There are two drivers for doing this at all: Firstly a Windows-based appliance would never be able to implement certain features (eg. LVM2). Secondly some distros right now ship a version of libguestfs that lacks working features (eg. guestfs_zerofree is not available in RHEL because zerofree is not packaged, and there are many more examples).
1. Groups remain static -----------------------
In the static group management policy an API group remains constant forever. New [functions] are either omitted or added to a new group.
This policy has the advantage of having a well-defined meaning. i.e. you can look at the documentation and be sure that if guestfs_available("augeas") returns true then a certain set of augeas APIs are definitely implemented.
The problem with this policy is that the groups become unmanageable as new APIs are added. So in a year's time I want to required the full range of augeas apis. I have to remember to check 'augeas', 'augeas_new', 'augeas_newer' and 'augeas_newer_still'. What's more, the mapping to these things is arbitrary because the base has a huge wadge of stuff in it, whereas the incrementals are very small and I can't remember what falls in which bucket. Unless I use this API day in, day out, I will need to head over to the documentation every time to look up the group mappings I need. We end up with a proliferation of unmemorable groups.
There is documentation and I think it's pretty clear, but the larger incorrect assumptions here are: (a) that we'll incrementally add new groups as you've described, and (b) that you have to use guestfs_available to check for all these new groups. On point (a): Let's say that Augeas adds a compelling new function called augeas_new, which we wish to add to the libguestfs API (guestfs_augeas_new). If this function becomes quickly available in the base appliances that we care about [currently: RHEL/CentOS 5.4+, Fedora 11+, Debian; in future: Windows] then we don't need to add another group at all. The only purpose of the new group would be to distinguish between platforms that have augeas_new and those that don't. If this function becomes available in the Linux platforms that we care about, but Augeas itself is still completely unavailable in Windows, then we'll add guestfs_augeas_new to the existing "augeas" group. The only case where we have to add a new group is if (eg) RHEL 5.4 sticks with the old Augeas and everyone else upgrades to the new Augeas, and therefore we'd want to distinguish between 3 cases (no Augeas at all for Windows, original Augeas for RHEL 5.4, new Augeas for everyone else). To distinguish 3 cases you need two groups. On point (b): You won't be using guestfs_available as the final test anyway. Because the advice remains: the only way to truly know if a function is available and will work is to try to run the function and test if it returns an error. guestfs_available gives you the ability to fail early with a nice error message. But it doesn't test whether a function finally works. So your existing code still works: r = guestfs_available (g, ["augeas"]); if (r == -1) { fail "sorry folks, this program is never gonna work"; } //... r = guestfs_augeas_new (g); if (r == -1) { fail "augeas_new: failed"; } OK, so the error message is ever so slightly less useful because you didn't fail early. But because you're still checking the error returns for each function *which you have to do, always* you still fail with an error and Bad Stuff doesn't happen. We're not doing always '1. Groups remain static' I guess we must be doing ...
2. Groups are updated to include new APIs -----------------------------------------
In this model, a new augeas call would be added to the augeas group.
This policy can no longer be called 'availability' because it does not determine the availability of an API. For example, augeas_new is introduced in libguestfs version X, and the augeas group is updated. The problem now is that if the code is run agains libguestfs version X-1, the test for 'augeas' returns true, despite the fact that my API is not available.
You should avoid the linking error using the attached code. That's more of a problem with C itself, and it affects every C program that calls a new API and then is linked against an old *.so file. Once you've avoided the C error, by checking error codes you're in the situation outlined immediately above. Rich. -- Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones virt-p2v converts physical machines to virtual machines. Boot with a live CD or over the network (PXE) and turn machines into Xen guests. http://et.redhat.com/~rjones/virt-p2v
-- Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones virt-p2v converts physical machines to virtual machines. Boot with a live CD or over the network (PXE) and turn machines into Xen guests. http://et.redhat.com/~rjones/virt-p2v
participants (2)
-
Matthew Booth -
Richard W.M. Jones