6:07 a.m.
I've summarised how the GObject bindings work below, which should
hopefully help reviewing the generator/generated code.
There are a couple of points in here I'm still not 100% happy with.
Specifically the handling of FBuffer and the Cancellable flag. Both are
explained below. I'm interested in suggestions.
Return values:
**************
All functions which can return an error have as their final argument a
GError **. GI maps this to the appropriate error mechanism for each
target language.
RErr returns a gboolean, true = success, false = failure.
The following types return the value from libguestfs unchanged:
RInt
RInt64
RBool
RConstString (transfer none): gobject doesn't manage returned memory
RConstOptString (transfer none). Methods don't return an error (no
GError**)
RString
RStringList
RHashtable is converted to a GHashTable. The keys and values from
libguestfs are inserted directly into the GHashTable without copying.
The top level array returned by libguestfs is freed.
RStruct is converted to GObject boxed type for the target struct. It
returns a copy of the struct, which is copied field by field. Memory for
the returned struct is allocated using glib's slice allocator. The
original struct is freed with guestfs_free_<struct>().
RStructList is converted as an array of structs, which are individually
converted the same way as RStruct, i.e. everything is copied. The
returned array is a newly allocated NULL-terminated array. The
originally returned value is freed with guestfs_free_<struct>_list().
RBufferOut is returned as a guint8 array, whose length is specified by a
size_r field. GObject uses both these fields to construct a single array
object where language bindings allow. The value returned by RBufferOut
is not copied.
Structs:
********
A parallel struct is created for each libguestfs struct type. A boxed
type is created for each parallel struct. It's field types are all
mapped trivially to gobject basic types (e.g. gchar *, gint32) except
FBuffer. FBuffer is mapped as:
guint8 *<field>
guint32 <field>_size
Unfortunately I can see no way to attach annotation to these fields, so
the bindings do not appreciate that these fields are related. I'm not
happy with this at all, so I may try manual tweaking of the .gir to see
if we can turn these into a single returned array where possible.
Required arguments:
*******************
Required arguments to methods are all mapped trivially to gobject basic
types. They are all passed directly to libguestfs. StringList and
DeviceList both remain null-terminated arrays. BufferIn has separate
array and length components, which are combined into a single array
using annotations where language bindings permit.
Optional arguments:
*******************
Optional arguments are implemented as a separate gobject whose name is
is Guestfs<camel api name>. This gobject has defined properties for each
optional argument accepted by the api. All properties are initially
undefined. Property types are mapped as:
OBool -> GuestfsTristate
OInt, OInt64 -> gint/gint64. -1 is used internally as a magic value
to represent undefined.
OString -> gchar *. NULL represents undefined.
GuestfsTristate is a new boxed enum type with values FALSE, TRUE and
UNSET. In the javascript bindings at least, passing in 'true' or 'false'
here works as expected. To set the UNSET value, you have to explicitly
use GuestfsTristate.UNSET.
OInt and OInt64 have a similar problem to boolean, in that there's no
way to represent unset in the fundamental type. The -1 = undefined
scheme is an internal detail and need not be part of the API. I did
create a patch to make the undefined number explicit for each optional
argument which required it. However I decided to hold off on it until we
actually create an api where this would be a problem, as it makes the
api definition in the generator slightly uglier and more complex.
Where no optional arguments are required, the user can pass in the
binding language's equivalent of NULL. GObject has a placeholder for
default values, but there are not yet implemented. When they are, we can
define the default value of optargs to be null, meaning they can be
entirely omitted when not required.
Cancellation:
*************
Certain apis are cancellable. These all take a GCancellable as the final
argument before GError **. This can be passed NULL if cancellation is
not required. While I have written cancellation, I have not yet tested
it *at all* other than it compiles and works correctly when NULL is
passed in.
We recently made Cancellable an explicit flag whereas before it was
implicit if the api had a FileIn or FileOut argument. This means it is
now possible to break the GObject api without breaking the C api with
the addition of a Cancellable flag. What potential solutions are there
to this problem? I can see:
• Live with breaking the GObject api if it ever comes up.
• Never add Cancellable to an existing api.
• Automatically add a GCancellable argument to all GObject apis, just in
case.
Events API
**********
The libguestfs events API is not yet bound. I'll add this at a later stage.
Matt
--
Matthew Booth, RHCA, RHCSS
Red Hat Engineering, Virtualisation Team
GPG ID: D33C3490
GPG FPR: 3733 612D 2D05 5458 8A8A 1600 3441 EA19 D33C 3490