On Mon, Jul 08, 2019 at 10:04:57AM +0100, Richard W.M. Jones wrote:
>On Mon, Jul 08, 2019 at 10:49:55AM +0200, Martin Kletzander wrote:
>> On Mon, Jul 08, 2019 at 10:10:10AM +0200, Pino Toscano wrote:
>> >On Saturday, 6 July 2019 13:03:24 CEST Martin Kletzander wrote:
>> >>Just one thing, the Cargo.toml includes a version under which the crate would be
>> >>published.  I presume the version would be the same as the one of the project
>> >>itself, i.e. when releasing libguestfs-x.y.z, we publish guestfs-rs-x.y.z to
>> >>crates.io.
>> >
>> >Speaking of naming: it seems like libraries that interface/wrap a
>> >foreign C/C++/etc library are usually called foo-sys -- so should our
>> >binding be named guestfs-sys?
>> >
>>
>> So you've seen my RFC? =)
>>
>> Just to guestfs-sys would be a crate that does only two things:
>>
>> 1) exposes the C functions using `extern`
>>
>> 2) links to the library
>>
>> And then another crate (e.g. guestfs) would expose the higher-level, safe,
>> hopefully idiomatic API.  More information (reasoning etc.) see:
>>
>>  https://doc.rust-lang.org/cargo/reference/build-scripts.html#a-sys-packages
>
>For the Python guestfs bindings we originally planned to write an
>idiomatic (ie. OO in that case) API on top of the raw generated
>bindings, but never really got around to it.  I'm not convinced it's
>really a good idea because you end up chasing new APIs.  Remember the
>whole point of the generator is that new APIs are instantly available
>in all languages as soon as they are added upstream.
>

For the libnbd use-case I went with a middle ground.  That is libnbd-sys is a
crated with just the linkage and list of extern functions, but libnbd is
supposed to just expose this as methods on the Nbd struct, which take Rust types
(as opposed to C types), ensure safety and idiomatically handle errors.

No other extra redesign would be there, the code handles functions that are not
allowed in a particular state nicely, so that should be fine.  The only thing
what would be really nice to utilize in libnbd rust crate is the fact that the
states there can be encoded into the way the structs are used, so that you could
only call those APIs that are accessible at a current state (if that state is
controllable by the client, of course), so for example you could use the builder
pattern to create a handle prepared to be connected (or even connect it):

  let h = Nbd::new()
              .add_meta_context("base:allocation")
              .set.export_name("/")
              .set_debug(true)
              .connect_uri("nbd://")

And then you would be able to do, e.g.:

  h.pread();
  h.set_debug(false)

But not:

  h.set_export_name("/exp");

as the object `h` would not even support that function.

Anyway, even though it would be useful for libguestfs as well, thanks to the way
these projects handle errors it is just something I consider "nice-to-have".

Have a nice day,
Martin

>Rich.
>
>--
>Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
>Read my programming and virtualization blog: http://rwmj.wordpress.com
>virt-top is 'top' for virtual machines.  Tiny program with many
>powerful monitoring features, net stats, disk stats, logging, etc.
>http://people.redhat.com/~rjones/virt-top