plugins/rust/nbdkit-rust-plugin.pod

   1 =head1 NAME
   2
   3 nbdkit-rust-plugin - writing nbdkit plugins in Rust
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit /path/to/libplugin.so [arguments...]
   8
   9 =head1 DESCRIPTION
  10
  11 This manual page describes how to write nbdkit plugins in compiled
  12 Rust code.  Rust plugins are compiled to F<*.so> files (the same as
  13 plugins written in C) and are used in the same way.
  14
  15 =head1 WRITING A RUST NBDKIT PLUGIN
  16
  17 Broadly speaking, Rust nbdkit plugins work like C ones, so you should
  18 read L<nbdkit-plugin(3)> first.
  19
  20 You should also look at
  21 L<https://github.com/libguestfs/nbdkit/blob/master/plugins/rust/src/lib.rs>
  22 and
  23 L<https://github.com/libguestfs/nbdkit/blob/master/plugins/rust/examples/ramdisk.rs>
  24 in the nbdkit source tree.  The first describes the plugin interface
  25 for Rust plugins and the second provides a simple example.
  26
  27 We may change how Rust plugins are written in future to make them more
  28 idiomatic.  At the moment each callback corresponds directly to a C
  29 callback - in fact each is called directly from the server.
  30
  31 Your Rust code should define a public C<plugin_init> function which
  32 returns a pointer to a C<Plugin> struct.  This struct is exactly
  33 compatible with the C struct used by C plugins.
  34
  35  extern crate nbdkit;
  36  use nbdkit::*;
  37  use nbdkit::ThreadModel::*;
  38
  39  #[no_mangle]
  40  extern fn myplugin_thread_model () -> ThreadModel {
  41     SerializeAllRequests
  42  }
  43
  44  //... more functions
  45
  46  pub extern fn plugin_init () -> *const Plugin {
  47     // Plugin name.
  48     let name = "myplugin\0"
  49       as *const str as *const [c_char] as *const c_char;
  50
  51     // Create a mutable plugin, setting the 4 required fields.
  52     let mut plugin = Plugin::new (
  53         name,
  54         myplugin_open,
  55         myplugin_get_size,
  56         myplugin_pread
  57     );
  58     // Update any other fields as required.
  59     plugin.close = Some (myplugin_close);
  60     plugin.pwrite = Some (myplugin_pwrite);
  61     plugin.thread_model = Some (myplugin_thread_model);
  62
  63     // Return the pointer.
  64     let plugin = Box::new(plugin);
  65     return Box::into_raw(plugin);
  66 }
  67
  68 =head2 Compiling a Rust nbdkit plugin
  69
  70 Because you are building a C-compatible shared library, the crate type
  71 must be set to:
  72
  73  crate-type = ["cdylib"]
  74
  75 After compiling using C<cargo build> you can then use
  76 C<libmyplugin.so> as an nbdkit plugin (see L<nbdkit(1)>,
  77 L<nbdkit-plugin(3)>):
  78
  79  nbdkit ./libmyplugin.so [args ...]
  80
  81 =head2 Threads
  82
  83 One of the members in C<Plugin> returned by C<plugin_init> is
  84 C<thread_model>, which must return one of the values in the table
  85 below. For more information on thread models, see
  86 L<nbdkit-plugin(3)/THREADS>.  If this optional function is not
  87 provided, the thread model defaults to
  88 C<nbdkit::ThreadModel::Parallel>.
  89
  90 =over 4
  91
  92 =item C<nbdkit::ThreadModel::SerializeConnections>
  93
  94 =item C<nbdkit::ThreadModel::SerializeAllRequests>
  95
  96 =item C<nbdkit::ThreadModel::SerializeRequests>
  97
  98 =item C<nbdkit::ThreadModel::Parallel>
  99
 100 =back
 101
 102 =head2 Missing callbacks
 103
 104 =over 4
 105
 106 =item Missing: C<can_extents> and C<extents>
 107
 108 These are not yet supported.
 109
 110 =back
 111
 112 =head1 VERSION
 113
 114 Rust plugins first appeared in nbdkit 1.12.
 115
 116 =head1 SEE ALSO
 117
 118 L<nbdkit(1)>,
 119 L<nbdkit-plugin(3)>,
 120 L<cargo(1)>.
 121
 122 =head1 AUTHORS
 123
 124 Richard W.M. Jones
 125
 126 =head1 COPYRIGHT
 127
 128 Copyright (C) 2019 Red Hat Inc.