nbdkit-ruby-plugin(3)

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

NAME

6       nbdkit-ruby-plugin - nbdkit ruby plugin
7

SYNOPSIS

9        nbdkit ruby /path/to/plugin.rb [arguments...]
10

WARNING

12       The Ruby language is fundamentally broken when it comes to embedding in
13       a program which uses pthreads.  This means you may see random "stack
14       overflows" when using this plugin on some versions of Ruby but not
15       others.
16
17       For the whole sorry saga, see:
18       https://redmine.ruby-lang.org/issues/2294
19

DESCRIPTION

21       "nbdkit-ruby-plugin" is an embedded Ruby interpreter for nbdkit(1),
22       allowing you to write nbdkit plugins in Ruby.
23
24   If you have been given an nbdkit Ruby plugin
25       Assuming you have a Ruby script which is an nbdkit plugin, you run it
26       like this:
27
28        nbdkit ruby /path/to/ruby.rb
29
30       You may have to add further "key=value" arguments to the command line.
31       Read the Ruby script to see if it requires any.
32

WRITING A RUBY NBDKIT PLUGIN

34       For an example plugin written in Ruby, see:
35       https://gitlab.com/nbdkit/nbdkit/blob/master/plugins/ruby/example.rb
36
37       Broadly speaking, Ruby nbdkit plugins work like C ones, so you should
38       read nbdkit-plugin(3) first.
39
40       To write a Ruby nbdkit plugin, you create a Ruby file which contains at
41       least the following required functions:
42
43        def open(readonly)
44          # see below
45        end
46        def get_size(h)
47          # see below
48        end
49        def pread(h, count, offset)
50          # see below
51        end
52
53       Note that the subroutines must have those literal names (like "open"),
54       because the C part looks up and calls those functions directly.  You
55       may want to include documentation and globals (eg. for storing global
56       state).  Any other top level statements are run when the script is
57       loaded, just like ordinary Ruby.
58
59   Executable script
60       If you want you can make the script executable and include a "shebang"
61       at the top:
62
63        #!/usr/sbin/nbdkit ruby
64
65       See also "Shebang scripts" in nbdkit(1).
66
67       These scripts can also be installed in the $plugindir.  See "WRITING
68       PLUGINS IN OTHER PROGRAMMING LANGUAGES" in nbdkit-plugin(3).
69
70   Methods
71       Your script has access to the "Nbdkit" module, with the following
72       singleton methods:
73
74        Nbdkit.set_error(err)
75
76       Record "err" as the reason you are about to raise an exception. "err"
77       should either be a class that defines an "Errno" constant (all of the
78       subclasses of "SystemCallError" in module "Errno" have this property),
79       an object that defines an "errno" method with no arguments (all
80       instances of "SystemCallError" have this property), or an integer value
81       corresponding to the usual errno values.
82
83   Exceptions
84       Ruby callbacks should throw exceptions to indicate errors. Remember to
85       use "Nbdkit.set_error" if you need to control which error is sent back
86       to the client; if omitted, the client will see an error of "EIO".
87
88   Ruby callbacks
89       This just documents the arguments to the callbacks in Ruby, and any way
90       that they differ from the C callbacks.  In all other respects they work
91       the same way as the C callbacks, so you should go and read
92       nbdkit-plugin(3).
93
94       "dump_plugin"
95           (Optional)
96
97           There are no arguments or return value.
98
99       "config"
100           (Optional)
101
102            def config(key, value)
103              # no return value
104            end
105
106       "config_complete"
107           (Optional)
108
109           There are no arguments or return value.
110
111       "open"
112           (Required)
113
114            def open(readonly)
115              # return handle
116            end
117
118           You can return any non-nil Ruby value as the handle.  It is passed
119           back in subsequent calls.
120
121       "close"
122           (Optional)
123
124            def close(h)
125              # no return value
126            end
127
128       "get_size"
129           (Required)
130
131            def get_size(h)
132              # return the size of the disk
133            end
134
135       "can_write"
136           (Optional)
137
138            def can_write(h)
139              # return a boolean
140            end
141
142       "can_flush"
143           (Optional)
144
145            def can_flush(h)
146              # return a boolean
147            end
148
149       "is_rotational"
150           (Optional)
151
152            def is_rotational(h)
153              # return a boolean
154            end
155
156       "can_trim"
157           (Optional)
158
159            def can_trim(h)
160              # return a boolean
161            end
162
163       "pread"
164           (Required)
165
166            def pread(h, count, offset)
167              # construct a string of length count bytes and return it
168            end
169
170           The body of your "pread" function should construct a string of
171           length (at least) "count" bytes.  You should read "count" bytes
172           from the disk starting at "offset".
173
174           NBD only supports whole reads, so your function should try to read
175           the whole region (perhaps requiring a loop).  If the read fails or
176           is partial, your function should throw an exception, optionally
177           using "Nbdkit.set_error" first.
178
179       "pwrite"
180           (Optional)
181
182            def pwrite(h, buf, offset)
183              length = buf.length
184              # no return value
185            end
186
187           The body of your "pwrite" function should write the "buf" string to
188           the disk.  You should write "count" bytes to the disk starting at
189           "offset".
190
191           NBD only supports whole writes, so your function should try to
192           write the whole region (perhaps requiring a loop).  If the write
193           fails or is partial, your function should throw an exception,
194           optionally using "Nbdkit.set_error" first.
195
196       "flush"
197           (Optional)
198
199            def flush(h)
200              # no return value
201            end
202
203           The body of your "flush" function should do a sync(2) or
204           fdatasync(2) or equivalent on the backing store.
205
206           If the flush fails, your function should throw an exception,
207           optionally using "Nbdkit.set_error" first.
208
209       "trim"
210           (Optional)
211
212            def trim(h, count, offset)
213              # no return value
214            end
215
216           The body of your "trim" function should "punch a hole" in the
217           backing store.  If the trim fails, your function should throw an
218           exception, optionally using "Nbdkit.set_error" first.
219
220       "zero"
221           (Optional)
222
223            def zero(h, count, offset, may_trim)
224              # no return value
225
226           The body of your "zero" function should ensure that "count" bytes
227           of the disk, starting at "offset", will read back as zero.  If
228           "may_trim" is true, the operation may be optimized as a trim as
229           long as subsequent reads see zeroes.
230
231           NBD only supports whole writes, so your function should try to
232           write the whole region (perhaps requiring a loop).  If the write
233           fails or is partial, your function should throw an exception,
234           optionally using "Nbdkit.set_error" first.  In particular, if you
235           would like to automatically fall back to "pwrite" (perhaps because
236           there is nothing to optimize if "may_trim" is false), use
237           "Nbdkit.set_error(Errno::EOPNOTSUPP)".
238
239   Missing callbacks
240       Missing: "load" and "unload"
241           These are not needed because you can just use ordinary Ruby
242           constructs.
243
244       Missing: "name", "version", "longname", "description", "config_help",
245       "can_fua", "can_cache", "cache"
246           These are not yet supported.
247
248   Threads
249       The thread model for Ruby callbacks currently cannot be set from Ruby.
250       It is hard-coded in the C part to
251       "NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS".  This may change or be
252       settable in future.
253

FILES

255       $plugindir/nbdkit-ruby-plugin.so
256           The plugin.
257
258           Use "nbdkit --dump-config" to find the location of $plugindir.
259

VERSION

261       "nbdkit-ruby-plugin" first appeared in nbdkit 1.2.
262

AUTHORS

267       Eric Blake
268
269       Richard W.M. Jones
270

COPYRIGHT

272       Copyright Red Hat
273

LICENSE

275       Redistribution and use in source and binary forms, with or without
276       modification, are permitted provided that the following conditions are
277       met:
278
279       •   Redistributions of source code must retain the above copyright
280           notice, this list of conditions and the following disclaimer.
281
282       •   Redistributions in binary form must reproduce the above copyright
283           notice, this list of conditions and the following disclaimer in the
284           documentation and/or other materials provided with the
285           distribution.
286
287       •   Neither the name of Red Hat nor the names of its contributors may
288           be used to endorse or promote products derived from this software
289           without specific prior written permission.
290
291       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
292       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
293       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
294       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
295       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
296       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
297       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
298       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
299       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
300       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
301       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
302
303
304
305nbdkit-1.36.2                     2023-11-26             nbdkit-ruby-plugin(3)