1nbdkit-ocaml-plugin(3) NBDKIT nbdkit-ocaml-plugin(3)
2
6 nbdkit-ocaml-plugin - writing nbdkit plugins in OCaml
7
9 nbdkit /path/to/plugin.so [arguments...]
10 nbdkit plugin [arguments...]
12
14 This manual page describes how to write nbdkit plugins in natively
15 compiled OCaml code.
16 Note this requires OCaml ≥ 4.02.2, which has support for shared
18 libraries. See http://caml.inria.fr/mantis/view.php?id=6693
19
21 Broadly speaking, OCaml nbdkit plugins work like C ones, so you should
22 read nbdkit-plugin(3) first.
23 You should also look at "NBDKit.mli" which describes the plugin
25 interface for OCaml plugins.
26 Your OCaml code should call "NBDKit.register_plugin" like this:
28 let plugin = {
30 NBDKit.default_callbacks with
31 NBDKit.name = "myplugin";
32 version = "1.0";
33 open_connection = Some myplugin_open;
34 get_size = Some myplugin_get_size;
35 pread = Some myplugin_pread;
36 (* etc *)
37 }
38 let thread_model = NBDKit.THREAD_MODEL_SERIALIZE_CONNECTIONS
40 let () = NBDKit.register_plugin thread_model plugin
42 Your plugin can only call "register_plugin" once.
44 Compiling an OCaml nbdkit plugin
46 OCaml nbdkit plugins are natively compiled into shared object ("*.so")
47 files which nbdkit loads like regular C plugins.
48 After writing your OCaml plugin ("myplugin.ml"), compile and link it
50 using this command:
51 ocamlopt.opt -output-obj -runtime-variant _pic \
53 -o nbdkit-myplugin-plugin.so \
54 NBDKit.cmx myplugin.ml \
55 -cclib -lnbdkitocaml
56 You can then use "nbdkit-myplugin-plugin.so" as an nbdkit plugin (see
58 nbdkit(1), nbdkit-plugin(3)):
59 nbdkit ./nbdkit-myplugin-plugin.so [args ...]
61 or if the ".so" file is installed in the $plugindir directory:
63 nbdkit myplugin [args ...]
65 Handle
67 Your "open_connection" callback can return an OCaml value of any type.
68 The same value is passed back to the per-connection callbacks like
69 "get_size" and "pread".
70 Typically (although this is not a requirement) you define your own
72 handle struct in your plugin:
73 type handle = {
75 (* any per-connection data you want to store goes here *)
76 h_id : int; (* this is just an example field *)
77 h_readonly : bool;
78 }
79 let id = ref 0
81 let myplugin_open readonly =
82 (* return a newly allocated handle *)
83 incr id;
84 { h_id = !id; h_readonly = readonly }
85 let myplugin_get_size handle =
87 printf "handle ID = %d\n" handle.h_id;
88 (* ... *)
89 Errors
91 Plugins can return errors from methods by raising an exception.
92 If you need to control which errno is sent back to the client you have
94 to call "NBDKit.set_error" before raising the exception.
95 Note if you call some function in the OCaml "Unix" module or another
97 library which fails, then the errno of the failing system call will not
98 be returned to the client. You have to catch the exception and call
99 "NBDKit.set_error" before re-raising the exception if you need to
100 control this.
101 Threads
103 The first parameter of "NBDKit.register_plugin" is the thread model,
104 which can be one of the values in the table below. For more
105 information on thread models, see "THREADS" in nbdkit-plugin(3). Note
106 that because of the garbage collector lock in OCaml, callbacks are
107 never truly concurrent.
108 "NBDKit.THREAD_MODEL_SERIALIZE_CONNECTIONS"
110 "NBDKit.THREAD_MODEL_SERIALIZE_ALL_REQUESTS"
111 "NBDKit.THREAD_MODEL_SERIALIZE_REQUESTS"
112 "NBDKit.THREAD_MODEL_PARALLEL"
113 Debugging
115 You can add debugging messages which are printed only when nbdkit is in
116 verbose mode by calling:
117 NBDKit.debug fs [...]
119 This function works like "Printf.printf".
121
123 nbdkit(1), nbdkit-plugin(3), ocamlopt(1).
124
126 Richard W.M. Jones
127
129 Copyright (C) 2014 Red Hat Inc.
130
132 Redistribution and use in source and binary forms, with or without
133 modification, are permitted provided that the following conditions are
134 met:
135 · Redistributions of source code must retain the above copyright
137 notice, this list of conditions and the following disclaimer.
138 · Redistributions in binary form must reproduce the above copyright
140 notice, this list of conditions and the following disclaimer in the
141 documentation and/or other materials provided with the
142 distribution.
143 · Neither the name of Red Hat nor the names of its contributors may
145 be used to endorse or promote products derived from this software
146 without specific prior written permission.
147 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
149 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
150 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
151 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
152 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
153 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
154 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
155 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
156 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
157 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
158 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
159nbdkit-1.12.3 2019-05-21 nbdkit-ocaml-plugin(3)