plugins/ruby/nbdkit-ruby-plugin.pod

   1 =head1 NAME
   2
   3 nbdkit-ruby-plugin - nbdkit ruby plugin
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit ruby /path/to/plugin.rb [arguments...]
   8
   9 =head1 WARNING
  10
  11 The Ruby language is fundamentally broken when it comes to embedding
  12 in a program which uses pthreads.  This means you may see random
  13 "stack overflows" when using this plugin on some versions of Ruby but
  14 not others.
  15
  16 For the whole sorry saga, see:
  17 L<https://redmine.ruby-lang.org/issues/2294>
  18
  19 =head1 DESCRIPTION
  20
  21 C<nbdkit-ruby-plugin> is an embedded Ruby interpreter for
  22 L<nbdkit(1)>, allowing you to write nbdkit plugins in Ruby.
  23
  24 =head2 If you have been given an nbdkit Ruby plugin
  25
  26 Assuming you have a Ruby script which is an nbdkit plugin, you run it
  27 like this:
  28
  29  nbdkit ruby /path/to/ruby.rb
  30
  31 You may have to add further C<key=value> arguments to the command
  32 line.  Read the Ruby script to see if it requires any.
  33
  34 =head1 WRITING A RUBY NBDKIT PLUGIN
  35
  36 For an example plugin written in Ruby, see:
  37 L<https://gitlab.com/nbdkit/nbdkit/blob/master/plugins/ruby/example.rb>
  38
  39 Broadly speaking, Ruby nbdkit plugins work like C ones, so you should
  40 read L<nbdkit-plugin(3)> first.
  41
  42 To write a Ruby nbdkit plugin, you create a Ruby file which
  43 contains at least the following required functions:
  44
  45  def open(readonly)
  46    # see below
  47  end
  48  def get_size(h)
  49    # see below
  50  end
  51  def pread(h, count, offset)
  52    # see below
  53  end
  54
  55 Note that the subroutines must have those literal names (like C<open>),
  56 because the C part looks up and calls those functions directly.  You
  57 may want to include documentation and globals (eg. for storing global
  58 state).  Any other top level statements are run when the script is
  59 loaded, just like ordinary Ruby.
  60
  61 =head2 Executable script
  62
  63 If you want you can make the script executable and include a "shebang"
  64 at the top:
  65
  66  #!/usr/sbin/nbdkit ruby
  67
  68 See also L<nbdkit(1)/Shebang scripts>.
  69
  70 These scripts can also be installed in the C<$plugindir>.  See
  71 L<nbdkit-plugin(3)/WRITING PLUGINS IN OTHER PROGRAMMING LANGUAGES>.
  72
  73 =head2 Methods
  74
  75 Your script has access to the C<Nbdkit> module, with the following
  76 singleton methods:
  77
  78  Nbdkit.set_error(err)
  79
  80 Record C<err> as the reason you are about to raise an
  81 exception. C<err> should either be a class that defines an C<Errno>
  82 constant (all of the subclasses of C<SystemCallError> in module
  83 C<Errno> have this property), an object that defines an C<errno>
  84 method with no arguments (all instances of C<SystemCallError> have
  85 this property), or an integer value corresponding to the usual errno
  86 values.
  87
  88 =head2 Exceptions
  89
  90 Ruby callbacks should throw exceptions to indicate errors. Remember
  91 to use C<Nbdkit.set_error> if you need to control which error is sent
  92 back to the client; if omitted, the client will see an error of C<EIO>.
  93
  94 =head2 Ruby callbacks
  95
  96 This just documents the arguments to the callbacks in Ruby, and any
  97 way that they differ from the C callbacks.  In all other respects they
  98 work the same way as the C callbacks, so you should go and read
  99 L<nbdkit-plugin(3)>.
 100
 101 =over 4
 102
 103 =item C<dump_plugin>
 104
 105 (Optional)
 106
 107 There are no arguments or return value.
 108
 109 =item C<config>
 110
 111 (Optional)
 112
 113  def config(key, value)
 114    # no return value
 115  end
 116
 117 =item C<config_complete>
 118
 119 (Optional)
 120
 121 There are no arguments or return value.
 122
 123 =item C<open>
 124
 125 (Required)
 126
 127  def open(readonly)
 128    # return handle
 129  end
 130
 131 You can return any non-nil Ruby value as the handle.  It is passed
 132 back in subsequent calls.
 133
 134 =item C<close>
 135
 136 (Optional)
 137
 138  def close(h)
 139    # no return value
 140  end
 141
 142 =item C<get_size>
 143
 144 (Required)
 145
 146  def get_size(h)
 147    # return the size of the disk
 148  end
 149
 150 =item C<can_write>
 151
 152 (Optional)
 153
 154  def can_write(h)
 155    # return a boolean
 156  end
 157
 158 =item C<can_flush>
 159
 160 (Optional)
 161
 162  def can_flush(h)
 163    # return a boolean
 164  end
 165
 166 =item C<is_rotational>
 167
 168 (Optional)
 169
 170  def is_rotational(h)
 171    # return a boolean
 172  end
 173
 174 =item C<can_trim>
 175
 176 (Optional)
 177
 178  def can_trim(h)
 179    # return a boolean
 180  end
 181
 182 =item C<pread>
 183
 184 (Required)
 185
 186  def pread(h, count, offset)
 187    # construct a string of length count bytes and return it
 188  end
 189
 190 The body of your C<pread> function should construct a string of length
 191 (at least) C<count> bytes.  You should read C<count> bytes from the
 192 disk starting at C<offset>.
 193
 194 NBD only supports whole reads, so your function should try to read
 195 the whole region (perhaps requiring a loop).  If the read fails or
 196 is partial, your function should throw an exception, optionally using
 197 C<Nbdkit.set_error> first.
 198
 199 =item C<pwrite>
 200
 201 (Optional)
 202
 203  def pwrite(h, buf, offset)
 204    length = buf.length
 205    # no return value
 206  end
 207
 208 The body of your C<pwrite> function should write the C<buf> string to
 209 the disk.  You should write C<count> bytes to the disk starting at
 210 C<offset>.
 211
 212 NBD only supports whole writes, so your function should try to
 213 write the whole region (perhaps requiring a loop).  If the write
 214 fails or is partial, your function should throw an exception, optionally
 215 using C<Nbdkit.set_error> first.
 216
 217 =item C<flush>
 218
 219 (Optional)
 220
 221  def flush(h)
 222    # no return value
 223  end
 224
 225 The body of your C<flush> function should do a L<sync(2)> or
 226 L<fdatasync(2)> or equivalent on the backing store.
 227
 228 If the flush fails, your function should throw an exception, optionally
 229 using C<Nbdkit.set_error> first.
 230
 231 =item C<trim>
 232
 233 (Optional)
 234
 235  def trim(h, count, offset)
 236    # no return value
 237  end
 238
 239 The body of your C<trim> function should "punch a hole" in the
 240 backing store.  If the trim fails, your function should throw an
 241 exception, optionally using C<Nbdkit.set_error> first.
 242
 243 =item C<zero>
 244
 245 (Optional)
 246
 247  def zero(h, count, offset, may_trim)
 248    # no return value
 249
 250 The body of your C<zero> function should ensure that C<count> bytes
 251 of the disk, starting at C<offset>, will read back as zero.  If
 252 C<may_trim> is true, the operation may be optimized as a trim as long
 253 as subsequent reads see zeroes.
 254
 255 NBD only supports whole writes, so your function should try to
 256 write the whole region (perhaps requiring a loop).  If the write
 257 fails or is partial, your function should throw an exception,
 258 optionally using C<Nbdkit.set_error> first.  In particular, if
 259 you would like to automatically fall back to C<pwrite> (perhaps
 260 because there is nothing to optimize if C<may_trim> is false),
 261 use C<Nbdkit.set_error(Errno::EOPNOTSUPP)>.
 262
 263 =back
 264
 265 =head2 Missing callbacks
 266
 267 =over 4
 268
 269 =item Missing: C<load> and C<unload>
 270
 271 These are not needed because you can just use ordinary Ruby
 272 constructs.
 273
 274 =item Missing: C<name>, C<version>, C<longname>, C<description>,
 275 C<config_help>, C<can_fua>, C<can_cache>, C<cache>
 276
 277 These are not yet supported.
 278
 279 =back
 280
 281 =head2 Threads
 282
 283 The thread model for Ruby callbacks currently cannot be set from Ruby.
 284 It is hard-coded in the C part to
 285 C<NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS>.  This may change or be
 286 settable in future.
 287
 288 =head1 FILES
 289
 290 =over 4
 291
 292 =item F<$plugindir/nbdkit-ruby-plugin.so>
 293
 294 The plugin.
 295
 296 Use C<nbdkit --dump-config> to find the location of C<$plugindir>.
 297
 298 =back
 299
 300 =head1 VERSION
 301
 302 C<nbdkit-ruby-plugin> first appeared in nbdkit 1.2.
 303
 304 =head1 SEE ALSO
 305
 306 L<nbdkit(1)>,
 307 L<nbdkit-plugin(3)>,
 308 L<ruby(1)>.
 309
 310 =head1 AUTHORS
 311
 312 Eric Blake
 313
 314 Richard W.M. Jones
 315
 316 =head1 COPYRIGHT
 317
 318 Copyright Red Hat