=head1 NAME

nbdkit-rust-plugin - writing nbdkit plugins in Rust

=head1 SYNOPSIS

 nbdkit /path/to/libplugin.so [arguments...]

=head1 DESCRIPTION

This manual page describes how to write nbdkit plugins in compiled
Rust code.  Rust plugins are compiled to F<*.so> files (the same as
plugins written in C) and are used in the same way.

=head1 WRITING A RUST NBDKIT PLUGIN

Broadly speaking, Rust nbdkit plugins work like C ones, so you should
read L<nbdkit-plugin(3)> first.

You should also look at
L<https://gitlab.com/nbdkit/nbdkit/blob/master/plugins/rust/src/lib.rs>
and
L<https://gitlab.com/nbdkit/nbdkit/blob/master/plugins/rust/examples/ramdisk.rs>
in the nbdkit source tree.  The first describes the plugin interface
for Rust plugins and the second provides a simple example.

Your Rust code should define a public implementation of the C<Server> trait,
and register it using the C<plugin!> macro.

 use nbdkit::*;

 #[derive(Default)]
 struct MyPlugin {
     // ...
 }

 impl Server for MyPlugin {
     // ...
 }

 plugin!(MyPlugin {write_at, trim, ...});

=head2 Compiling a Rust nbdkit plugin

Because you are building a C-compatible shared library, the crate type
must be set to:

 crate-type = ["cdylib"]

After compiling using C<cargo build> you can then use
C<libmyplugin.so> as an nbdkit plugin (see L<nbdkit(1)>,
L<nbdkit-plugin(3)>):

 nbdkit ./libmyplugin.so [args ...]

=head2 Threads

One of the methods of C<Server> is
C<thread_model>, which must return one of the values in the table
below. For more information on thread models, see
L<nbdkit-plugin(3)/THREADS>.  If this optional function is not
provided, the thread model defaults to
C<nbdkit::ThreadModel::Parallel>.

=over 4

=item C<nbdkit::ThreadModel::SerializeConnections>

=item C<nbdkit::ThreadModel::SerializeAllRequests>

=item C<nbdkit::ThreadModel::SerializeRequests>

=item C<nbdkit::ThreadModel::Parallel>

=back

=head2 Missing callbacks

All NBDKit callbacks are supported.  However, the C<Server> trait has no
C<close> method.  Instead, you should implement C<Drop> if you need to clean
up resources during destruction.

=head1 VERSION

Rust plugins first appeared in nbdkit 1.12.  The crate was completely
rewritten for nbdkit 1.22.

=head1 SEE ALSO

L<nbdkit(1)>,
L<nbdkit-plugin(3)>,
L<cargo(1)>.

=head1 AUTHORS

Alan Somers

=head1 COPYRIGHT

Copyright (C) 2020 Axcient.
