1nbdkit-ocaml-plugin(3)              NBDKIT              nbdkit-ocaml-plugin(3)
2
3
4

NAME

6       nbdkit-ocaml-plugin - writing nbdkit plugins in OCaml
7

SYNOPSIS

9        nbdkit /path/to/plugin.so [arguments...]
10
11        nbdkit plugin [arguments...]
12

DESCRIPTION

14       This manual page describes how to write nbdkit plugins in natively
15       compiled OCaml code.  This requires OCaml ≥ 4.03.
16

WRITING AN OCAML NBDKIT PLUGIN

18       For an example plugin written in OCaml, see:
19       https://gitlab.com/nbdkit/nbdkit/blob/master/plugins/ocaml/example.ml
20
21       Broadly speaking, OCaml nbdkit plugins work like C ones, so you should
22       read nbdkit-plugin(3) first.
23
24       You should also look at NBDKit(3) which describes the plugin interface
25       for OCaml plugins.
26
27       Your OCaml code should call "NBDKit.register_plugin" like this when the
28       plugin is loaded:
29
30        NBDKit.register_plugin
31            ~name:            "myplugin"
32            ~version:         "1.0"
33            ~open_connection: myplugin_open
34            ~get_size:        myplugin_get_size
35            ~pread:           myplugin_pread
36            ~thread_model:
37                (fun () -> NBDKit.THREAD_MODEL_SERIALIZE_ALL_REQUESTS)
38            (* etc *)
39            ()
40
41       "~name", "~open_connection", "~get_size" and "~pread" are required.
42       All other parameters are optional.
43
44   Compiling an OCaml nbdkit plugin
45       OCaml nbdkit plugins are natively compiled into shared object ("*.so")
46       files which nbdkit loads like regular C plugins.
47
48       After writing your OCaml plugin ("myplugin.ml"), compile and link it
49       using this command:
50
51        ocamlopt.opt -output-obj -runtime-variant _pic \
52                     -o nbdkit-myplugin-plugin.so \
53                     unix.cmxa NBDKit.cmx myplugin.ml \
54                     -cclib -lnbdkitocaml
55
56       You can then use "nbdkit-myplugin-plugin.so" as an nbdkit plugin (see
57       nbdkit(1), nbdkit-plugin(3)):
58
59        nbdkit ./nbdkit-myplugin-plugin.so [args ...]
60
61       or if the ".so" file is installed in the $plugindir directory:
62
63        nbdkit myplugin [args ...]
64
65   Handle
66       Your "open_connection" callback can return an OCaml value of any type.
67       The same value is passed back to the per-connection callbacks like
68       "get_size" and "pread".
69
70       Typically (although this is not a requirement) you define your own
71       handle struct in your plugin:
72
73        type handle = {
74          (* any per-connection data you want to store goes here *)
75          h_id : int; (* this is just an example field *)
76          h_readonly : bool;
77        }
78
79        let id = ref 0
80        let myplugin_open readonly =
81          (* return a newly allocated handle *)
82          incr id;
83          { h_id = !id; h_readonly = readonly }
84
85        let myplugin_get_size handle =
86          printf "handle ID = %d\n" handle.h_id;
87          (* ... *)
88
89       If you don't need to store per-connection data, "open_connection" can
90       return "()".
91
92   Errors
93       Plugins can return errors from methods by raising an exception.
94
95       If you need to control which errno is sent back to the client you have
96       to call "NBDKit.set_error" before raising the exception.
97
98       Note if you call some function in the OCaml "Unix" module or another
99       library which fails, then the errno of the failing system call will not
100       be returned to the client.  You have to catch the exception and call
101       "NBDKit.set_error" before re-raising the exception if you need to
102       control this.
103
104   Threads
105       One of the optional parameters of "NBDKit.register_plugin" is
106       "~thread_model", which must return one of the values in the table
107       below:
108
109       "NBDKit.THREAD_MODEL_SERIALIZE_CONNECTIONS"
110       "NBDKit.THREAD_MODEL_SERIALIZE_ALL_REQUESTS"
111       "NBDKit.THREAD_MODEL_SERIALIZE_REQUESTS"
112       "NBDKit.THREAD_MODEL_PARALLEL"
113
114       If this optional parameter is not provided, the thread model defaults
115       to "NBDKit.THREAD_MODEL_PARALLEL".  The garbage collector lock is
116       acquired when calling into OCaml code and because of this callbacks are
117       never truly concurrent.
118
119       For more information on thread models, see "THREADS" in
120       nbdkit-plugin(3).
121
122   Debugging
123       You can add debugging messages which are printed only when nbdkit is in
124       verbose mode by calling:
125
126        NBDKit.debug fs [...]
127
128       This function works like "Printf.printf".
129
130   OCaml scripts
131       Using nbdkit-cc-plugin(1) it is possible to write OCaml plugins which
132       are compiled just before use, and so appear to work more like scripts.
133

VERSION

135       OCaml plugins first appeared in nbdkit 1.2.
136

SEE ALSO

138       NBDKit(3), nbdkit(1), nbdkit-plugin(3), ocamlopt(1).
139

AUTHORS

141       Richard W.M. Jones
142
144       Copyright (C) 2014-2021 Red Hat Inc.
145

LICENSE

147       Redistribution and use in source and binary forms, with or without
148       modification, are permitted provided that the following conditions are
149       met:
150
151       •   Redistributions of source code must retain the above copyright
152           notice, this list of conditions and the following disclaimer.
153
154       •   Redistributions in binary form must reproduce the above copyright
155           notice, this list of conditions and the following disclaimer in the
156           documentation and/or other materials provided with the
157           distribution.
158
159       •   Neither the name of Red Hat nor the names of its contributors may
160           be used to endorse or promote products derived from this software
161           without specific prior written permission.
162
163       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
164       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
165       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
166       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
167       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
168       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
169       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
170       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
171       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
172       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
173       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
174
175
176
177nbdkit-1.30.7                     2022-07-10            nbdkit-ocaml-plugin(3)
Impressum