nbdkit-rust-plugin - writing nbdkit plugins in Rust
nbdkit /path/to/libplugin.so [arguments...]This manual page describes how to write nbdkit plugins in compiled Rust code. Rust plugins are compiled to *.so files (the same as plugins written in C) and are used in the same way.
Broadly speaking, Rust nbdkit plugins work like C ones, so you should read nbdkit-plugin(3) first.
You should also look at https://gitlab.com/nbdkit/nbdkit/blob/master/plugins/rust/src/lib.rs and 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 Server trait, and register it using the plugin! macro.
use nbdkit::*;
#[derive(Default)]
struct MyPlugin {
// ...
}
impl Server for MyPlugin {
// ...
}
plugin!(MyPlugin {write_at, trim, ...});Because you are building a C-compatible shared library, the crate type must be set to:
crate-type = ["cdylib"]After compiling using cargo build you can then use libmyplugin.so as an nbdkit plugin (see nbdkit(1), nbdkit-plugin(3)):
nbdkit ./libmyplugin.so [args ...]One of the methods of Server is thread_model, which must return one of the values in the table below. For more information on thread models, see "THREADS" in nbdkit-plugin(3). If this optional function is not provided, the thread model defaults to nbdkit::ThreadModel::Parallel.
nbdkit::ThreadModel::SerializeConnectionsnbdkit::ThreadModel::SerializeAllRequestsnbdkit::ThreadModel::SerializeRequestsnbdkit::ThreadModel::ParallelAll NBDKit callbacks are supported. However, the Server trait has no close method. Instead, you should implement Drop if you need to clean up resources during destruction.
Rust plugins first appeared in nbdkit 1.12. The crate was completely rewritten for nbdkit 1.22.
nbdkit(1), nbdkit-plugin(3), cargo(1).
Alan Somers
Copyright (C) 2020 Axcient.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Red Hat nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.