[Libguestfs] [PATCH 1/2] availability: Add guestfs_available.

[Matthew Booth]

On 20/11/09 15:12, Richard W.M. Jones wrote:
>> From e24b0b7fb4160af4c82107c55176353abc07b69a Mon Sep 17 00:00:00 2001
> From: Richard Jones<rjones at 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