plugins/perl/nbdkit-perl-plugin.pod

   1 =encoding utf8
   2
   3 =head1 NAME
   4
   5 nbdkit-perl-plugin - nbdkit perl plugin
   6
   7 =head1 SYNOPSIS
   8
   9  nbdkit perl script=/path/to/plugin.pl [arguments...]
  10
  11 =head1 DESCRIPTION
  12
  13 C<nbdkit-perl-plugin> is an embedded Perl interpreter for
  14 L<nbdkit(1)>, allowing you to write nbdkit plugins in Perl.
  15
  16 Broadly speaking, Perl nbdkit plugins work like C ones, so you should
  17 read L<nbdkit-plugin(3)> first.
  18
  19 =head2 USING A PERL NBDKIT PLUGIN
  20
  21 Assuming you have a Perl script which is an nbdkit plugin, you run it
  22 like this:
  23
  24  nbdkit perl script=/path/to/plugin.pl
  25
  26 You may have to add further C<key=value> arguments to the command
  27 line.  Read the Perl script to see if it requires any.  C<script=...>
  28 I<must> come first on the command line.
  29
  30 =head1 WRITING A PERL NBDKIT PLUGIN
  31
  32 There is an example Perl nbdkit plugin called C<example.pl> which
  33 ships with the nbdkit source.
  34
  35 To write a Perl nbdkit plugin, you create a Perl file which contains
  36 at least the following required subroutines:
  37
  38  sub open
  39  {
  40    # see below
  41  }
  42  sub get_size
  43  {
  44    # see below
  45  }
  46  sub pread
  47  {
  48    # see below
  49  }
  50
  51 Note that the subroutines must have those literal names (like
  52 C<open>), because the C part looks up and calls those functions
  53 directly.  You may want to include documentation and globals (eg. for
  54 storing global state).  Also any top-level statements, C<BEGIN>
  55 statements, C<END> statements and so on are run when nbdkit starts up
  56 and shuts down, just like ordinary Perl.
  57
  58 The file does I<not> need to include a C<#!> (hash-bang) at the top,
  59 and does I<not> need to be executable.  In fact it's a good idea
  60 I<not> to do that, because running the plugin directly as a Perl
  61 script won't work.
  62
  63 =head2 EXCEPTIONS
  64
  65 Instead of returning error codes as in C, Perl callbacks should
  66 indicate problems by throwing Perl exceptions (ie. C<die>, C<croak>
  67 etc).  The Perl error message is captured and printed by nbdkit.
  68
  69 =head2 32 vs 64 BIT
  70
  71 It is likely that Perl plugins won't work well, or maybe won't work at
  72 all, on 32 bit platforms.  This is simply because Perl doesn't have an
  73 easy way to use 64 bit integers on 32 bit platforms, and 64 bit
  74 integers (eg. file offsets, disk sizes) are required for many nbdkit
  75 operations.
  76
  77 =head2 PERL CALLBACKS
  78
  79 This just documents the arguments to the callbacks in Perl, and any
  80 way that they differ from the C callbacks.  In all other respects they
  81 work the same way as the C callbacks, so you should go and read
  82 L<nbdkit-plugin(3)>.
  83
  84 =over 4
  85
  86 =item C<config>
  87
  88 (Optional)
  89
  90  sub config
  91  {
  92      my $key = shift;
  93      my $value = shift;
  94      # No return value.
  95  }
  96
  97 =item C<config_complete>
  98
  99 (Optional)
 100
 101 There are no arguments or return value.
 102
 103 =item C<open>
 104
 105 (Required)
 106
 107  sub open
 108  {
 109      my $readonly = shift;
 110      my $handle = {};
 111      return $handle;
 112  }
 113
 114 The C<readonly> flag is a boolean.
 115
 116 You can return any Perl value as the handle.  It is passed back to
 117 subsequent calls.  It's usually convenient to use a hashref, since
 118 that lets you store arbitrary fields.
 119
 120 =item C<close>
 121
 122 (Optional)
 123
 124  sub close
 125  {
 126      my $handle = shift;
 127      # No return value
 128  }
 129
 130 After C<close> returns, the reference count of the handle is
 131 decremented in the C part, which usually means that the handle and its
 132 contents will be garbage collected.
 133
 134 =item C<get_size>
 135
 136 (Required)
 137
 138  sub get_size
 139  {
 140      my $handle = shift;
 141      my $i64 = .. the size of the disk ..;
 142      return $i64;
 143  }
 144
 145 This returns the size of the disk.  You can return any Perl object
 146 that evaluates to an integer.
 147
 148 =item C<can_write>
 149
 150 (Optional)
 151
 152  sub can_write
 153  {
 154      my $handle = shift;
 155      my $bool = ...;
 156      return $bool;
 157  }
 158
 159 Return a boolean indicating whether the disk is writable.
 160
 161 =item C<can_flush>
 162
 163 (Optional)
 164
 165  sub can_flush
 166  {
 167      my $handle = shift;
 168      my $bool = ...;
 169      return $bool;
 170  }
 171
 172 Return a boolean indicating whether flush can be performed.
 173
 174 =item C<is_rotational>
 175
 176 (Optional)
 177
 178  sub is_rotational
 179  {
 180      my $handle = shift;
 181      my $bool = ...;
 182      return $bool;
 183  }
 184
 185 Return a boolean indicating whether the disk is rotational.
 186
 187 =item C<can_trim>
 188
 189 (Optional)
 190
 191  sub can_trim
 192  {
 193      my $handle = shift;
 194      my $bool = ...;
 195      return $bool;
 196  }
 197
 198 Return a boolean indicating whether trim/discard can be performed.
 199
 200 =item C<pread>
 201
 202 (Required)
 203
 204  sub pread
 205  {
 206     my $handle = shift;
 207     my $count = shift;
 208     my $offset = shift;
 209     # Construct a buffer of length $count bytes and return it.
 210     return $buf;
 211  }
 212
 213 The body of your C<pread> function should construct a buffer of length
 214 (at least) C<$count> bytes.  You should read C<$count> bytes from the
 215 disk starting at C<$offset>.
 216
 217 NBD only supports whole reads, so your function should try to read the
 218 whole region (perhaps requiring a loop).  If the read fails or is
 219 partial, your function should C<die>.
 220
 221 =item C<pwrite>
 222
 223 (Optional)
 224
 225  sub pwrite
 226  {
 227     my $handle = shift;
 228     my $buf = shift;
 229     my $count = length ($buf);
 230     my $offset = shift;
 231     # No return value
 232  }
 233
 234 The body of your C<pwrite> function should write the C<$buf> string to
 235 the disk.  You should write C<$count> bytes to the disk starting at
 236 C<$offset>.
 237
 238 NBD only supports whole writes, so your function should try to write
 239 the whole region (perhaps requiring a loop).  If the write fails or is
 240 partial, your function should C<die>.
 241
 242 =item C<flush>
 243
 244 (Optional)
 245
 246  sub flush
 247  {
 248      my $handle = shift;
 249      # No return value
 250  }
 251
 252 The body of your C<flush> function should do a L<sync(2)> or
 253 L<fdatasync(2)> or equivalent on the backing store.
 254
 255 If there is an error, the function should call C<die>.
 256
 257 =item C<trim>
 258
 259 (Optional)
 260
 261  sub trim
 262  {
 263      my $handle = shift;
 264      my $count = shift;
 265      my $offset = shift;
 266      # No return value
 267  }
 268
 269 The body of your C<trim> function should "punch a hole" in the backing
 270 store.
 271
 272 If there is an error, the function should call C<die>.
 273
 274 =back
 275
 276 =head2 MISSING CALLBACKS
 277
 278 =over 4
 279
 280 =item Missing: C<load> and C<unload>
 281
 282 These are not needed because you can just use regular Perl C<BEGIN>
 283 and C<END> constructs.
 284
 285 =item Missing: C<name>, C<version>, C<longname>, C<description>, C<config_help>
 286
 287 These are not yet supported.
 288
 289 =back
 290
 291 =head2 THREADS
 292
 293 The thread model for Perl callbacks currently cannot be set from Perl.
 294 It is hard-coded in the C part to
 295 C<NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS>.  This may change or be
 296 settable in future.
 297
 298 =head1 SEE ALSO
 299
 300 L<nbdkit(1)>,
 301 L<nbdkit-plugin(3)>,
 302 L<perl(1)>.
 303
 304 =head1 AUTHORS
 305
 306 Richard W.M. Jones
 307
 308 =head1 COPYRIGHT
 309
 310 Copyright (C) 2013-2014 Red Hat Inc.
 311
 312 =head1 LICENSE
 313
 314 Redistribution and use in source and binary forms, with or without
 315 modification, are permitted provided that the following conditions are
 316 met:
 317
 318 =over 4
 319
 320 =item *
 321
 322 Redistributions of source code must retain the above copyright
 323 notice, this list of conditions and the following disclaimer.
 324
 325 =item *
 326
 327 Redistributions in binary form must reproduce the above copyright
 328 notice, this list of conditions and the following disclaimer in the
 329 documentation and/or other materials provided with the distribution.
 330
 331 =item *
 332
 333 Neither the name of Red Hat nor the names of its contributors may be
 334 used to endorse or promote products derived from this software without
 335 specific prior written permission.
 336
 337 =back
 338
 339 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND
 340 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 341 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
 342 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR
 343 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 344 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 345 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 346 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 347 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 348 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 349 OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 350 SUCH DAMAGE.