Skip to content

Latest commit

 

History

History
164 lines (110 loc) · 4.37 KB

nbdkit-ocaml-plugin.pod

File metadata and controls

164 lines (110 loc) · 4.37 KB
Raw

NAME

nbdkit-ocaml-plugin - writing nbdkit plugins in OCaml

SYNOPSIS

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

nbdkit plugin [arguments...]

DESCRIPTION

This manual page describes how to write nbdkit plugins in natively compiled OCaml code.

Note this requires OCaml ≥ 4.02.2, which has support for shared libraries. See http://caml.inria.fr/mantis/view.php?id=6693

COMPILING AN OCAML NBDKIT PLUGIN

After writing your OCaml plugin (myplugin.ml), link it using this command:

ocamlopt.opt \
  -output-obj -runtime-variant _pic \
  -o nbdkit-myplugin-plugin.so \
  NBDKit.cmx myplugin.ml \
  -cclib -lnbdkitocaml

You can then use nbdkit-myplugin-plugin.so as if it were a regular nbdkit plugin (see nbdkit(1), nbdkit-plugin(3)):

nbdkit ./nbdkit-myplugin-plugin.so [args ...]

or if the .so file is installed in the $plugindir directory:

nbdkit myplugin [args ...]

WRITING AN OCAML NBDKIT PLUGIN

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

You should also look at NBDKit.mli which describes the plugin interface for OCaml plugins.

Your OCaml code should call NBDKit.register_plugin like this:

let plugin = {
  NBDKit.default_callbacks with
    NBDKit.name     = "myplugin";
    version         = "1.0";
    open_connection = Some myplugin_open;
    get_size        = Some myplugin_get_size;
    pread           = Some myplugin_pread;
    (* etc *)
}

let thread_model = NBDKit.THREAD_MODEL_SERIALIZE_CONNECTIONS

let () = NBDKit.register_plugin thread_model plugin

Your plugin can only call register_plugin once.

HANDLE

Your open_connection callback can return an OCaml value of any type. The same value is passed back to the per-connection callbacks like get_size and pread.

Typically (although this is not a requirement) you define your own handle struct in your plugin:

type handle = {
  (* any per-connection data you want to store goes here *)
  h_id : int; (* this is just an example field *)
  h_readonly : bool;
}

let id = ref 0
let myplugin_open readonly =
  (* return a newly allocated handle *)
  incr id;
  { h_id = !id; h_readonly = readonly }

let myplugin_get_size handle =
  printf "handle ID = %d\n" handle.h_id;
  (* ... *)

THREADS

The first parameter of NBDKit.register_plugin is the thread model, which can be one of the values in the table below. For more information on thread models, see "THREADS" in nbdkit-plugin(3). Note that because of the garbage collector lock in OCaml, callbacks are never truly concurrent.

NBDKit.THREAD_MODEL_SERIALIZE_CONNECTIONS
NBDKit.THREAD_MODEL_SERIALIZE_ALL_REQUESTS
NBDKit.THREAD_MODEL_SERIALIZE_REQUESTS
NBDKit.THREAD_MODEL_PARALLEL

SEE ALSO

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

AUTHORS

Richard W.M. Jones

COPYRIGHT

Copyright (C) 2014 Red Hat Inc.

LICENSE

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.