NAME

nbdkit-rust-plugin - writing nbdkit plugins in Rust

SYNOPSIS

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

DESCRIPTION

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.

WRITING A RUST NBDKIT PLUGIN

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, ...});

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 cargo build you can then use libmyplugin.so as an nbdkit plugin (see nbdkit(1), nbdkit-plugin(3)):

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

Threads

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::SerializeConnections
nbdkit::ThreadModel::SerializeAllRequests
nbdkit::ThreadModel::SerializeRequests
nbdkit::ThreadModel::Parallel

Missing callbacks

All 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.

VERSION

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

SEE ALSO

nbdkit(1), nbdkit-plugin(3), cargo(1).

AUTHORS

Alan Somers

COPYRIGHT

Copyright (C) 2020 Axcient.

LICENSE

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

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.