[Libguestfs] Libguestfs gobject bindings

[Daniel P. Berrange]

On Fri, Jan 13, 2012 at 11:33:33AM +0000, Matthew Booth wrote:
> On 01/13/2012 10:58 AM, Daniel P. Berrange wrote:
> >On Thu, Jan 12, 2012 at 11:59:22AM +0000, Matthew Booth wrote:
> >>I'm currently working on gobject bindings for libguestfs. I haven't
> >>got as far as compiling anything yet, but I've attached the C header
> >>for initial review.
> >>typedef struct _GuestfsPV GuestfsPV;
> >>struct _GuestfsPV {
> >>   gchar *pv_name;
> >>   /* The next field is NOT nul-terminated, be careful when printing it: */
> >>   gchar pv_uuid[32];
> >
> >How about a:
> >
> >    #define GUESTFS_LVM_UUID_BUFLEN 32
> >
> >and use that throughout
> 
> I don't think this one is massively important, because you can
> always use sizeof pv_uuid as an equivalent constant. As the API is
> automatically generated, these are always going to be consistent.

sizeof() works fine for C, but not for languages. If you add
the constant, then it'll get exposed to the languages automatically.

> >For the vast majority of these, or at least, any which take non-trivial
> >execution time, I think it would be important to add _async variants,
> >following the GIO design pattern. eg
> >
> >   void guest_session_tune2fs_async(GuestfsSession *session, const gchar *device,
> >                                    GuestfsTune2FS *optargs,
> >                                    GCancellable *cancellable,
> >                                    GAsyncReadyCallback callback,
> >                                    gpointer user_data);
> >   gboolean guest_session_tune2fs_finish(GAsyncResult *result,
> >                                         GError **error);
> >
> >This is a style that is widely preferred by people writing modern GTK
> >applications, since it avoids the need to use threads in GUI apps.
> 
> Sounds like a good idea. Can I assume that I can safely add this at
> a later date without taking it into account at this stage? If so,
> I'll come back to this once I have a working binding.

Yes, it is easy to add in later.

The only issue would be if you wanted to add in 'GCancellable' to
the existing blocking APIs. I imagine there's no easy way to allow
cancellation of API calls at the libguestfs level, so it is probably
not worth it.

> Incidentally, I'm also playing with changes to functions with return
> or take array. I've decided to drop GSList in favour of a
> NULL-terminated array as returned by guestfs. For BufferIn and
> RBufferOut I've dropped the GByteArray in favour of a guint8 * with
> an additional length parameter.

Hmm, it is probably better to use GInputStream & GOutputStream for
any bulk I/O APIs. That way apps have the flexibility to give
you a GFileInputStream, or a GMemoryInputStream as they see fit,
rather than forcing them to have it all in memory.


> My concern is around memory handling in the bindings. An RStringList
> function returns a NULL-terminated char **. If I cast that to gchar
> ** and return it as-is, will bindings correctly garbage collect it?

Every parameter and return value as a 'transfer' annotation which
controls memory management. For objects it is either 'none' (receiver
of object must not free it), or 'full' (receiver of object must free
it).

For lists/hashes there is extra values, to cope with the scenario
where the receiver must free the List/Hash, but not the values
stored in it. See:

  https://live.gnome.org/GObjectIntrospection/Annotations

Daniel
-- 
|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org              -o-             http://virt-manager.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org       -o-       http://live.gnome.org/gtk-vnc :|