[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

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

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

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

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 ;)

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

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]