plugins/ruby/nbdkit-ruby-plugin.pod

   1 =encoding utf8
   2
   3 =head1 NAME
   4
   5 nbdkit-ruby-plugin - nbdkit ruby plugin
   6
   7 =head1 SYNOPSIS
   8
   9  nbdkit ruby script=/path/to/plugin.rb [arguments...]
  10
  11 =head1 DESCRIPTION
  12
  13 C<nbdkit-ruby-plugin> is an embedded Ruby interpreter for
  14 L<nbdkit(1)>, allowing you to write nbdkit plugins in Ruby.
  15
  16 Broadly speaking, Ruby nbdkit plugins work like C ones, so you should
  17 read L<nbdkit-plugin(3)> first.
  18
  19 =head2 USING A RUBY NBDKIT PLUGIN
  20
  21 Assuming you have a Ruby script which is an nbdkit plugin, you run it
  22 like this:
  23
  24  nbdkit ruby script=/path/to/ruby.rb
  25
  26 You may have to add further C<key=value> arguments to the command
  27 line.  Read the Ruby script to see if it requires any.  C<script=...>
  28 I<must> come first on the command line.
  29
  30 =head1 WRITING A RUBY NBDKIT PLUGIN
  31
  32 There is an example Ruby nbdkit plugin called C<example.rb> which
  33 ships with the nbdkit source.
  34
  35 To write a Ruby nbdkit plugin, you create a Ruby file which
  36 contains at least the following required functions:
  37
  38  def open(readonly)
  39    # see below
  40  end
  41  def get_size(h)
  42    # see below
  43  end
  44  def pread(h, count, offset)
  45    # see below
  46  end
  47
  48 Note that the subroutines must have those literal names (like C<open>),
  49 because the C part looks up and calls those functions directly.  You
  50 may want to include documentation and globals (eg. for storing global
  51 state).  Any other top level statements are run when the script is
  52 loaded, just like ordinary Ruby.
  53
  54 The file does not need to include a C<#!> (hash-bang) at the top, and
  55 does not need to be executable.  In fact it's a good idea not to do
  56 that, because running the plugin directly as a Ruby script won't
  57 work.
  58
  59 =head2 EXCEPTIONS
  60
  61 Ruby callbacks should throw exceptions to indicate errors.
  62
  63 =head2 RUBY CALLBACKS
  64
  65 This just documents the arguments to the callbacks in Ruby, and any
  66 way that they differ from the C callbacks.  In all other respects they
  67 work the same way as the C callbacks, so you should go and read
  68 L<nbdkit-plugin(3)>.
  69
  70 =over 4
  71
  72 =item C<config>
  73
  74 (Optional)
  75
  76  def config(key, value)
  77    # no return value
  78  end
  79
  80 =item C<config_complete>
  81
  82 (Optional)
  83
  84 There are no arguments or return value.
  85
  86 =item C<open>
  87
  88 (Required)
  89
  90  def open(readonly)
  91    # return handle
  92  end
  93
  94 You can return any non-nil Ruby value as the handle.  It is passed
  95 back in subsequent calls.
  96
  97 =item C<close>
  98
  99 (Optional)
 100
 101  def close(h)
 102    # no return value
 103  end
 104
 105 =item C<get_size>
 106
 107 (Required)
 108
 109  def get_size(h)
 110    # return the size of the disk
 111  end
 112
 113 =item C<can_write>
 114
 115 (Optional)
 116
 117  def can_write(h)
 118    # return a boolean
 119  end
 120
 121 =item C<can_flush>
 122
 123 (Optional)
 124
 125  def can_flush(h)
 126    # return a boolean
 127  end
 128
 129 =item C<is_rotational>
 130
 131 (Optional)
 132
 133  def is_rotational(h)
 134    # return a boolean
 135  end
 136
 137 =item C<can_trim>
 138
 139 (Optional)
 140
 141  def can_trim(h)
 142    # return a boolean
 143  end
 144
 145 =item C<pread>
 146
 147 (Required)
 148
 149  def pread(h, count, offset)
 150    # construct a string of length count bytes and return it
 151  end
 152
 153 The body of your C<pread> function should construct a string of length
 154 (at least) C<count> bytes.  You should read C<count> bytes from the
 155 disk starting at C<offset>.
 156
 157 NBD only supports whole reads, so your function should try to read
 158 the whole region (perhaps requiring a loop).  If the read fails or
 159 is partial, your function should throw an exception.
 160
 161 =item C<pwrite>
 162
 163 (Optional)
 164
 165  def pwrite(h, buf, offset)
 166    length = buf.length
 167    # no return value
 168  end
 169
 170 The body of your C<pwrite> function should write the C<buf> string to
 171 the disk.  You should write C<count> bytes to the disk starting at
 172 C<offset>.
 173
 174 NBD only supports whole writes, so your function should try to
 175 write the whole region (perhaps requiring a loop).  If the write
 176 fails or is partial, your function should throw an exception.
 177
 178 =item C<flush>
 179
 180 (Optional)
 181
 182  def flush(h)
 183    # no return value
 184  end
 185
 186 The body of your C<flush> function should do a L<sync(2)> or
 187 L<fdatasync(2)> or equivalent on the backing store.
 188
 189 =item C<trim>
 190
 191 (Optional)
 192
 193  def trim(h, count, offset)
 194    # no return value
 195  end
 196
 197 The body of your C<trim> function should "punch a hole" in the
 198 backing store.
 199
 200 =back
 201
 202 =head2 MISSING CALLBACKS
 203
 204 =over 4
 205
 206 =item Missing: C<load> and C<unload>
 207
 208 These are not needed because you can just use ordinary Ruby
 209 constructs.
 210
 211 =item Missing: C<name>, C<version>, C<longname>, C<description>, C<config_help>
 212
 213 These are not yet supported.
 214
 215 =back
 216
 217 =head2 THREADS
 218
 219 The thread model for Ruby callbacks currently cannot be set from Ruby.
 220 It is hard-coded in the C part to
 221 C<NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS>.  This may change or be
 222 settable in future.
 223
 224 =head1 SEE ALSO
 225
 226 L<nbdkit(1)>,
 227 L<nbdkit-plugin(3)>,
 228 L<ruby(1)>.
 229
 230 =head1 AUTHORS
 231
 232 Richard W.M. Jones
 233
 234 =head1 COPYRIGHT
 235
 236 Copyright (C) 2013-2016 Red Hat Inc.
 237
 238 =head1 LICENSE
 239
 240 Redistribution and use in source and binary forms, with or without
 241 modification, are permitted provided that the following conditions are
 242 met:
 243
 244 =over 4
 245
 246 =item *
 247
 248 Redistributions of source code must retain the above copyright
 249 notice, this list of conditions and the following disclaimer.
 250
 251 =item *
 252
 253 Redistributions in binary form must reproduce the above copyright
 254 notice, this list of conditions and the following disclaimer in the
 255 documentation and/or other materials provided with the distribution.
 256
 257 =item *
 258
 259 Neither the name of Red Hat nor the names of its contributors may be
 260 used to endorse or promote products derived from this software without
 261 specific prior written permission.
 262
 263 =back
 264
 265 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND
 266 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 267 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
 268 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR
 269 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 270 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 271 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 272 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 273 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 274 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 275 OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 276 SUCH DAMAGE.