Inline::Pdlpp - Write PDL Subroutines inline with PDL::PP
"Inline::Pdlpp" is a module that allows you to write PDL subroutines
in the PDL::PP style. The big benefit compared to plain "PDL::PP" is
that you can write these definitions inline in any old perl script (without
the normal hassle of creating Makefiles, building, etc). Since version 0.30
the Inline module supports multiple programming languages and each language
has its own support module. This document describes how to use Inline with
PDL::PP (or rather, it will once these docs are complete ";)".
For more information on Inline in general, see Inline.
Some example scripts demonstrating "Inline::Pdlpp" usage can be found
in the
Example/InlinePdlpp directory.
"Inline::Pdlpp" is a subclass of Inline::C. Most Kudos goes to Brian
I.
You never actually use "Inline::Pdlpp" directly. It is just a support
module for using "Inline.pm" with "PDL::PP". So the usage
is always:
use Inline Pdlpp => ...;
or
bind Inline Pdlpp => ...;
Pending availability of full docs a few quick examples that illustrate typical
usage.
# example script inlpp.pl
use PDL; # must be called before (!) 'use Inline Pdlpp' calls
use Inline Pdlpp; # the actual code is in the __Pdlpp__ block below
$x = sequence 10;
print $x->inc,"\n";
print $x->inc->dummy(1,10)->tcumul,"\n";
__DATA__
__Pdlpp__
pp_def('inc',
Pars => 'i();[o] o()',
Code => '$o() = $i() + 1;',
);
pp_def('tcumul',
Pars => 'in(n);[o] mul()',
Code => '$mul() = 1;
loop(n) %{
$mul() *= $in();
%}',
);
# end example script
If you call this script it should generate output similar to this:
prompt> perl inlpp.pl
Inline running PDL::PP version 2.2...
[1 2 3 4 5 6 7 8 9 10]
[3628800 3628800 3628800 3628800 3628800 3628800 3628800 3628800 3628800 3628800]
Usage of "Inline::Pdlpp" in general is similar to
"Inline::C". In the absence of full docs for
"Inline::Pdlpp" you might want to compare Inline::C.
The script below is somewhat more complicated in that it uses code from an
external library (here from Numerical Recipes). All the relevant information
regarding include files, libraries and boot code is specified in a config call
to "Inline". For more experienced Perl hackers it might be helpful
to know that the format is similar to that used with ExtUtils::MakeMaker. The
keywords are largely equivalent to those used with "Inline::C".
Please see below for further details on the usage of "INC",
"LIBS", "AUTO_INCLUDE" and "BOOT".
use PDL; # this must be called before (!) 'use Inline Pdlpp' calls
use Inline Pdlpp => Config =>
INC => "-I$ENV{HOME}/include",
LIBS => "-L$ENV{HOME}/lib -lnr -lm",
# code to be included in the generated XS
AUTO_INCLUDE => <<'EOINC',
#include <math.h>
#include "nr.h" /* for poidev */
#include "nrutil.h" /* for err_handler */
static void nr_barf(char *err_txt)
{
fprintf(stderr,"Now calling croak...\n");
croak("NR runtime error: %s",err_txt);
}
EOINC
# install our error handler when loading the Inline::Pdlpp code
BOOT => 'set_nr_err_handler(nr_barf);';
use Inline Pdlpp; # the actual code is in the __Pdlpp__ block below
$x = zeroes(10) + 30;;
print $x->poidev(5),"\n";
__DATA__
__Pdlpp__
pp_def('poidev',
Pars => 'xm(); [o] pd()',
GenericTypes => [L,F,D],
OtherPars => 'long idum',
Code => '$pd() = poidev((float) $xm(), &$COMP(idum));',
);
For information on how to specify Inline configuration options, see Inline. This
section describes each of the configuration options available for Pdlpp. Most
of the options correspond either to MakeMaker or XS options of the same name.
See ExtUtils::MakeMaker and perlxs.
Specifies extra statements to automatically included. They will be added onto
the defaults. A newline char will be automatically added. Does essentially the
same as a call to "pp_addhdr". For short bits of code
"AUTO_INCLUDE" is probably syntactically nicer.
use Inline Pdlpp => Config => AUTO_INCLUDE => '#include "yourheader.h"';
Same as "pp_bless" command. Specifies the package (i.e. class) to
which your new
pp_defed methods will be added. Defaults to
"PDL" if omitted.
use Inline Pdlpp => Config => BLESS => 'PDL::MyPackage';
cf "PACKAGE", equivalent for "pp_addxs" in PDL::PP.
Specifies C code to be executed in the XS BOOT section. Corresponds to the XS
parameter. Does the same as the "pp_add_boot" command. Often used to
execute code only once at load time of the module, e.g. a library
initialization call.
Specify which compiler to use.
Specify extra compiler flags.
Specifies an include path to use. Corresponds to the MakeMaker parameter.
use Inline Pdlpp => Config => INC => '-I/inc/path';
Specify which linker to use.
Specify which linker flags to use.
NOTE: These flags will completely override the existing flags, instead of just
adding to them. So if you need to use those too, you must respecify them here.
Specifies external libraries that should be linked into your code. Corresponds
to the MakeMaker parameter.
use Inline Pdlpp => Config => LIBS => '-lyourlib';
or
use Inline Pdlpp => Config => LIBS => '-L/your/path -lyourlib';
Specify the name of the 'make' utility to use.
Specifies a user compiled object that should be linked in. Corresponds to the
MakeMaker parameter.
use Inline Pdlpp => Config => MYEXTLIB => '/your/path/yourmodule.so';
This controls the MakeMaker OPTIMIZE setting. By setting this value to '-g', you
can turn on debugging support for your Inline extensions. This will allow you
to be able to set breakpoints in your C code using a debugger like gdb.
Controls into which package the created XSUBs from "pp_addxs" in
PDL::PP go. E.g.:
use Inline Pdlpp => 'DATA', => PACKAGE => 'Other::Place';
will put the created routines into "Other::Place", not the calling
package (which is the default). Note this differs from "BLESS",
which is where "pp_def" in PDL::PPs go.
Specifies extra typemap files to use. Corresponds to the MakeMaker parameter.
use Inline Pdlpp => Config => TYPEMAPS => '/your/path/typemap';
Show the output of any compilations going on behind the scenes. Turns on
"BUILD_NOISY" in Inline::C.
Beware that there is a problem when you use the __DATA__ keyword style of Inline
definition and want to "do" your script containing inlined code. For
example
# myscript.pl contains inlined code
# in the __DATA__ section
perl -e 'do "myscript.pl";'
One or more DATA sections were not processed by Inline.
According to Brian Ingerson (of Inline fame) the workaround is to include an
"Inline->init" call in your script, e.g.
use PDL;
use Inline Pdlpp;
Inline->init;
# perl code
__DATA__
__Pdlpp__
# pp code
There is currently an undesired interaction between PDL::NiceSlice and
"Inline::Pdlpp". Since PP code generally contains expressions of the
type "$var()" (to access ndarrays, etc) PDL::NiceSlice recognizes
those incorrectly as slice expressions and does its substitutions. For the
moment (until hopefully the parser can deal with that) it is best to
explicitly switch PDL::NiceSlice off before the section of inlined Pdlpp code.
For example:
use PDL::NiceSlice;
use Inline::Pdlpp;
$x = sequence 10;
$x(0:3)++;
$x->inc;
no PDL::NiceSlice;
__DATA__
__C__
ppdef (...); # your full pp definition here
Brian Ingerson for creating the Inline infrastructure.
Christian Soeller <
[email protected]>
PDL
PDL::PP
Inline
Inline::C
Copyright (c) 2001. Christian Soeller. All rights reserved.
This program is free software; you can redistribute it and/or modify it under
the same terms as PDL itself.
See
http://pdl.perl.org