1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
|
=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.
|
