Previously with Python it was impossible to set a boolean or integer
optarg to -1 because that was used as a special sentinel value to
indicate that the optarg was not set.
Instead, use None as the sentinel value, since that cannot be a
boolean or integer type.
In C, a function called 'func' which has once_had_no_optargs=true will
(because of the previous commit) generate 'func_opts' and a
backwards-compatibility function called 'func'.
This commit changes some of the non-C bindings so that they also
generate 'func_opts' which is merely a wrapper that calls 'func'.
This avoids incompatibility when we rename 'mkfs_opts' etc back to
plain 'mkfs', and it also makes it easier to translate between other
language bindings and C code.
NB: Some bindings do not include aliases:
PHP: There's no way to easily alias methods in PHP < 5.3, and we
can't assume everyone has this minimum version.
GObject: Very complex to add aliases, but we should probably do this
at some point.
Haskell: No support for optargs in these bindings. Unfortunately
this means that we can no longer bind 'Guestfs.add_drive'
(since it will be changed to add optional arguments) making
the Haskell bindings even less useful than they were already.
This field, which is generated internally by the generator, is the
name of the C function corresponding to each action.
For actions that have NO optional arguments, it's just "guestfs_<name>".
For actions that have any optional arguments, it is
"guestfs_<name>_argv" (since any binding has to construct the optional
argument struct explicitly).
In a future commit, this mapping may become more complex.
This commit also "fixes" the C# bindings which didn't handle optional
arguments properly at all. In fact, it doesn't fix this, it just
changes it enough that it probably now compiles. We should either
compile and test the bindings routinely with Mono, or drop them, since
they are starting to bit-rot.
In the GObject bindings, I have added a space between the C function
name and the first paren.
Apart from the C# and GObject changes, this is just code motion. It
was verified by diffing the output of the generator before and after.
Each action changes from a tuple like this:
("cat", (RString "content", [Pathname "path"], []), 4,
[ProtocolLimitWarning],
[InitISOFS, Always, TestOutput (
[["cat"; "/known-2"]], "abcdef\n")],
"list the contents of a file",
"[...]");
to a slightly longer but more readable struct:
{ defaults with
name = "cat";
style = RString "content", [Pathname "path"], [];
proc_nr = Some 4;
protocol_limit_warning = true;
tests = [
InitISOFS, Always, TestOutput (
[["cat"; "/known-2"]], "abcdef\n")
];
shortdesc = "list the contents of a file";
longdesc = "[...]" };
["defaults" is a struct which contains the defaults for every field,
allowing us to use the "{ defaults with ... }" syntax to just update
the fields we want to be different from the defaults.]
This is a mechanical change and there is no change to the output of
the generator. I checked the output before and after with diff to
verify this. There are no changes in the output apart from UUIDs
which are expected to change with each run.
Previously, optional arguments had the same type as regular arguments, but were
constrained by various runtime tests to be only Bool, Int, Int64 or String. This
change makes the type of optional arguments stronger by giving them their own
type.
A convenience function, optargs_to_args is defined to convert optargs in the few
places where they are genuinely treated identically to mandatory arguments.
It also allows for future changes to optional arguments which do not affect
mandatory arguments.
RWMJ:
- removed redundant parens
- readded the check for > 64 optargs, but changed it to > 63
- changed the new function to args_of_optargs
These fixes allow libguestfs bindings to work with Python 3 (tested
with Python 3.2)
You can select which Python you compile against by doing:
PYTHON=python ./configure && make && make check
or:
PYTHON=python3 ./configure && make && make check
Release the Python global interpreter lock while running libguestfs
calls.
We don't release it around guestfs_create() because that is a short
call that just allocates memory. We do release it around
guestfs_close() since that is a potentially long-running (it can call
wait(2) amongst other things). We also release it around all the
other generated Python calls.
We don't yet support callbacks into Python code (ie. the new event
API). But when we do in future, we will need to also handle the GIL
around those callbacks.
This code is adapted from libvirt's python/typewrappers.h. Thanks to
Dan Berrange for showing us how to do this properly.
There was a lot of repeated code to map return types (eg. RErr)
to error cases (eg. -1 or NULL).
This commit introduces an error code type and two functions to
map return types to error codes and error codes to strings.
This allows generic "foo *bar" pointers to be passed to
library functions (not to daemon functions).
In the language bindings (except Perl) these are handled
as generic int64s with the assumption being that any
pointer can be converted to and from this. There is room
to add specific support for some pointer types in future
by specializing the match cases. However this is inherently
tricky because it depends on the implementation details of
other bindings (eg. to support virDomainPtr in OCaml depends
on the implementation details of the ocaml-libvirt project).
Perl is slightly different in that you have to supply a
typemap. Again this would depend on the implementation
detail of an external library unless you supplied a generic
typemap for int64.
This large commit changes the generator so that optional arguments
can be supported for functions.
The model for arguments (known as the "style") is changed from
(ret, args) to (ret, args, optargs) where optargs is a more limited
list of arguments.
One function has been added which takes optional arguments, it is
"add-drive-opts", modelled as:
(RErr, [String "filename"], #required
[Bool "readonly"; String "format"; String "iface"]) #optional
Note that this function is processed in the library (does not go over
the RPC protocol to the daemon). This has allowed us to simplify
the current implementation by omitting changes related to RPC or the
daemon, although we plan to add these at some point in the future.
From C this function can be called in 3 different ways as in these
examples:
guestfs_add_drive_opts (g, filename,
GUESTFS_ADD_DRIVE_OPTS_READONLY, 1,
GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
-1);
(the argument(s) between 'filename' and '-1' are the optional ones).
guestfs_add_drive_opts_va (g, filename, args);
where 'args' is a va_list. This works like the first version.
struct guestfs_add_drive_opts_argv optargs = {
.bitmask = GUESTFS_ADD_DRIVE_OPTS_READONLY_BITMASK,
.readonly = 1,
}
guestfs_add_drive_opts_argv (g, filename, &optargs);
This last form lets you construct lists of optional arguments, and
is used by guestfish and the language bindings.
In guestfish optional arguments are used like this:
add-drive-opts filename readonly:true
In OCaml these are mapped naturally to OCaml optional arguments, eg:
g#add_drive_opts ~readonly:true filename;
In Perl these are mapped to extra arguments, eg:
$g->add_drive_opts ($filename, readonly => 1);
In Python these are mapped to optional arguments, eg:
g.add_drive_opts ("file", readonly = 1, format = "qcow2")
In Ruby these are mapped to a final hash argument, eg:
g.add_drive_opts("file", {})
g.add_drive_opts("file", :readonly => 1)
g.add_drive_opts("file", :readonly => 1, :iface => "virtio")
In PHP these are mapped to extra parameters. This is not quite
accurate since you cannot omit arbitrary optional parameters, but
there's not much than can be done within the limitations of PHP
as a language.
Unimplemented in: Haskell, C#, Java.
'src/generator.ml' is no more. Instead the generator is logically
split up over many different source files.
Read generator/README for help and tips.
We compile the generator down to bytecode, not native code. This
means it will run more slowly, but is done for maximum portability.
