PDLA::API - making piddles from Perl and C/XS code
A simple cookbook how to create piddles manually. It covers both the Perl and the C/XS level. Additionally, it describes the PDLA core routines that can be accessed from other modules. These routines basically define the PDLA API. If you need to access piddles from C/XS you probably need to know about these functions.
use PDLA; sub mkmypiddle { ... }
Sometimes you want to create a piddle manually from binary data. You can do that at the Perl level. Examples in the distribution include some of the IO routines. The code snippet below illustrates the required steps.
use Carp; sub mkmypiddle { my $class = shift; my $pdl = $class->new; $pdl->set_datatype($PDLA_B); my @dims = (1,3,4); my $size = 1; for (@dims) { $size *= $_ } $pdl->setdims([@dims]); my $dref = $pdl->get_dataref(); # read data directly from file open my $file, '<data.dat' or die "couldn't open data.dat"; my $len = $size*PDLA::Core::howbig($pdl->get_datatype); croak "couldn't read enough data" if read( $file, $$dref, $len) != $len; close $file; $pdl->upd_data(); return $pdl; }
The following example creates a piddle at the C level. We use the Inline module which is really the way to interface Perl and C these days, using the with capability in Inline 0.68+.
Inline
with
use PDLA::LiteF; $a = myfloatseq(); # exercise our C piddle constructor print $a->info,"\n"; use Inline with => 'PDLA'; use Inline C; Inline->init; # useful if you want to be able to 'do'-load this script __DATA__ __C__ static pdl* new_pdl(int datatype, PDLA_Indx dims[], int ndims) { pdl *p = PDLA->pdlnew(); PDLA->setdims (p, dims, ndims); /* set dims */ p->datatype = datatype; /* and data type */ PDLA->allocdata (p); /* allocate the data chunk */ return p; } pdl* myfloatseq() { PDLA_Indx dims[] = {5,5,5}; pdl *p = new_pdl(PDLA_F,dims,3); PDLA_Float *dataf = (PDLA_Float *) p->data; PDLA_Indx i; /* dimensions might be 64bits */ for (i=0;i<5*5*5;i++) dataf[i] = i; /* the data must be initialized ! */ return p; }
Sometimes you obtain a chunk of data from another source, for example an image processing library, etc. All you want to do in that case is wrap your data into a piddle struct at the C level. Examples using this approach can be found in the IO modules (where FastRaw and FlexRaw use it for mmapped access) and the Gimp Perl module (that uses it to wrap Gimp pixel regions into piddles). The following script demonstrates a simple example:
use PDLA::LiteF; use PDLA::Core::Dev; use PDLA::Graphics::PGPLOT; $b = mkpiddle(); print $b->info,"\n"; imag1 $b; use Inline with => 'PDLA'; use Inline C; Inline->init; __DATA__ __C__ /* wrap a user supplied chunk of data into a piddle * You must specify the dimensions (dims,ndims) and * the datatype (constants for the datatypes are declared * in pdl.h; e.g. PDLA_B for byte type, etc) * * when the created piddle 'npdl' is destroyed on the * Perl side the function passed as the 'delete_magic' * parameter will be called with the pointer to the pdl structure * and the 'delparam' argument. * This gives you an opportunity to perform any clean up * that is necessary. For example, you might have to * explicitly call a function to free the resources * associated with your data pointer. * At the very least 'delete_magic' should zero the piddle's data pointer: * * void delete_mydata(pdl* pdl, int param) * { * pdl->data = 0; * } * pdl *p = pdl_wrap(mydata, PDLA_B, dims, ndims, delete_mydata,0); * * pdl_wrap returns the pointer to the pdl * that was created. */ typedef void (*DelMagic)(pdl *, int param); static void default_magic(pdl *p, int pa) { p->data = 0; } static pdl* pdl_wrap(void *data, int datatype, PDLA_Indx dims[], int ndims, DelMagic delete_magic, int delparam) { pdl* npdl = PDLA->pdlnew(); /* get the empty container */ PDLA->setdims(npdl,dims,ndims); /* set dims */ npdl->datatype = datatype; /* and data type */ npdl->data = data; /* point it to your data */ /* make sure the core doesn't meddle with your data */ npdl->state |= PDLA_DONTTOUCHDATA | PDLA_ALLOCATED; if (delete_magic != NULL) PDLA->add_deletedata_magic(npdl, delete_magic, delparam); else PDLA->add_deletedata_magic(npdl, default_magic, 0); return npdl; } #define SZ 256 /* a really silly function that makes a ramp image * in reality this could be an opaque function * in some library that you are using */ static PDLA_Byte* mkramp(void) { PDLA_Byte *data; int i; /* should use PDLA_Indx to support 64bit pdl indexing */ if ((data = malloc(SZ*SZ*sizeof(PDLA_Byte))) == NULL) croak("mkramp: Couldn't allocate memory"); for (i=0;i<SZ*SZ;i++) data[i] = i % SZ; return data; } /* this function takes care of the required clean-up */ static void delete_myramp(pdl* p, int param) { if (p->data) free(p->data); p->data = 0; } pdl* mkpiddle() { PDLA_Indx dims[] = {SZ,SZ}; pdl *p; p = pdl_wrap((void *) mkramp(), PDLA_B, dims, 2, delete_myramp,0); /* the delparam is abitrarily set to 0 */ return p; }
PDLA uses a technique similar to that employed by the Tk modules to let other modules use its core routines. A pointer to all shared core PDLA routines is stored in the $PDLA::SHARE variable. XS code should get hold of this pointer at boot time so that the rest of the C/XS code can then use that pointer for access at run time. This initial loading of the pointer is most easily achieved using the functions PDLA_AUTO_INCLUDE and PDLA_BOOT that are defined and exported by PDLA::Core::Dev. Typical usage with the Inline module has already been demonstrated:
$PDLA::SHARE
PDLA_AUTO_INCLUDE
PDLA_BOOT
PDLA::Core::Dev
use Inline with => 'PDLA';
In earlier versions of Inline, this was achieved like this:
use Inline C => Config => INC => &PDLA_INCLUDE, TYPEMAPS => &PDLA_TYPEMAP, AUTO_INCLUDE => &PDLA_AUTO_INCLUDE, # declarations BOOT => &PDLA_BOOT; # code for the XS boot section
The code returned by PDLA_AUTO_INCLUDE makes sure that pdlcore.h is included and declares the static variables to hold the pointer to the Core struct. It looks something like this:
Core
print PDLA_AUTO_INCLUDE; #include <pdlcore.h> static Core* PDLA; /* Structure holds core C functions */ static SV* CoreSV; /* Gets pointer to Perl var holding core structure */
The code returned by PDLA_BOOT retrieves the $PDLA::SHARE variable and initializes the pointer to the Core struct. For those who know their way around the Perl API here is the code:
perl_require_pv ("PDLA/Core.pm"); /* make sure PDLA::Core is loaded */ #ifndef aTHX_ #define aTHX_ #endif if (SvTRUE (ERRSV)) Perl_croak(aTHX_ "%s",SvPV_nolen (ERRSV)); CoreSV = perl_get_sv("PDLA::SHARE",FALSE); /* SV* value */ if (CoreSV==NULL) Perl_croak(aTHX_ "We require the PDLA::Core module, which was not found"); PDLA = INT2PTR(Core*,SvIV( CoreSV )); /* Core* value */ if (PDLA->Version != PDLA_CORE_VERSION) Perl_croak(aTHX_ "[PDLA->Version: \%d PDLA_CORE_VERSION: \%d XS_VERSION: \%s] The code needs to be recompiled against the newly installed PDLA", PDLA->Version, PDLA_CORE_VERSION, XS_VERSION);
The Core struct contains version info to ensure that the structure defined in pdlcore.h really corresponds to the one obtained at runtime. The code above tests for this
if (PDLA->Version != PDLA_CORE_VERSION) ....
For more information on the Core struct see PDLA::Internals.
With these preparations your code can now access the core routines as already shown in some of the examples above, e.g.
pdl *p = PDLA->pdlnew();
By default the C variable named PDLA is used to hold the pointer to the Core struct. If that is (for whichever reason) a problem you can explicitly specify a name for the variable with the PDLA_AUTO_INCLUDE and the PDLA_BOOT routines:
PDLA
use Inline C => Config => INC => &PDLA_INCLUDE, TYPEMAPS => &PDLA_TYPEMAP, AUTO_INCLUDE => &PDLA_AUTO_INCLUDE 'PDLA_Corep', BOOT => &PDLA_BOOT 'PDLA_Corep';
Make sure you use the same identifier with PDLA_AUTO_INCLUDE and PDLA_BOOT and use that same identifier in your own code. E.g., continuing from the example above:
pdl *p = PDLA_Corep->pdlnew();
The full definition of the Core struct can be found in the file pdlcore.h. In the following the most frequently used member functions of this struct are briefly explained.
pdl *SvPDLAV(SV *sv)
pdl *SetSV_PDLA(SV *sv, pdl *it)
pdl *pdlnew()
pdlnew returns an empty pdl object that needs further initialization to turn it into a proper piddle. Example:
pdlnew
pdl *p = PDLA->pdlnew(); PDLA->setdims(p,dims,ndims); p->datatype = PDLA_B;
pdl *null()
SV *copy(pdl* p, char* )
void *smalloc(STRLEN nbytes)
int howbig(int pdl_datatype)
void add_deletedata_magic(pdl *p, void (*func)(pdl*, int), int param)
void allocdata(pdl *p)
void make_physical(pdl *p)
void make_physdims(pdl *p)
void make_physvaffine(pdl *p)
void qsort_X(PDLA_Xtype *data, PDLA_Indx a, PDLA_Indx b) and void qsort_ind_X(PDLA_Xtype *data, PDLA_Indx *ix, PDLA_Indx a, PDLA_Indx b)
void qsort_X(PDLA_Xtype *data, PDLA_Indx a, PDLA_Indx b)
void qsort_ind_X(PDLA_Xtype *data, PDLA_Indx *ix, PDLA_Indx a, PDLA_Indx b)
where X is one of B,S,U,L,F,D and Xtype is one of Byte, Short, Ushort, Long, Float or Double. PDLA_Indx is the C integer type corresponding to appropriate indexing size for the perl configuration (ivsize and ivtype). It can be either 'long' or 'long long' depending on whether your perl is 32bit or 64bit enabled.
float NaN_float and double NaN_double
float NaN_float
double NaN_double
These are constants to produce the required NaN values.
void pdl_barf(const char* pat,...) and void pdl_warn(const char* pat,...)
void pdl_barf(const char* pat,...)
void pdl_warn(const char* pat,...)
These are C-code equivalents of barf and warn. They include special handling of error or warning messages during pthreading (i.e. processor multi-threading) that defer the messages until after pthreading is completed. When pthreading is complete, perl's barf or warn is called with the deferred messages. This is needed to keep from calling perl's barf or warn during pthreading, which can cause segfaults.
barf
warn
Note that barf and warn have been redefined (using c-preprocessor macros) in pdlcore.h to PDLA->barf and PDLA->warn. This is to keep any XS or PP code from calling perl's barf or warn directly, which can cause segfaults during pthreading.
PDLA->barf
PDLA->warn
See PDLA::ParallelCPU for more information on pthreading.
Some of the C API functions return PDLA_Anyval C type which is a structure and therefore requires special handling.
PDLA_Anyval
You might want to use for example get_pdl_badvalue function:
get_pdl_badvalue
/* THIS DOES NOT WORK! (although it did in older PDLA) */ if( PDLA->get_pdl_badvalue(a) == 0 ) { ... } /* THIS IS CORRECT */ double bad_a; ANYVAL_TO_CTYPE(bad_a, double, PDLA->get_pdl_badvalue(a)); if( bad_a == 0 ) { ... }
In pdl.h there are the following macros for handling PDLA_Anyval from C code:
ANYVAL_TO_SV(out_SV, in_anyval) ANYVAL_FROM_CTYPE(out_anyval, out_anyval_type, in_variable) ANYVAL_TO_CTYPE(out_variable, out_ctype, in_anyval) ANYVAL_EQ_ANYVAL(x, y)
As these macros where not available in older PDLA versions you might want to add the following defines into your C/XS code to make compatible with older PDLA versions.
#if PDLA_CORE_VERSION < 12 #define ANYVAL_TO_SV(outsv,inany) outsv = newSVnv((NV)(inany) #define ANYVAL_FROM_CTYPE(outany,avtype,inval) outany = (PDLA_Double)(inval) #define ANYVAL_TO_CTYPE(outval,ctype,inany) outval = (ctype)(inany) #define ANYVAL_EQ_ANYVAL(x,y) (x == y) #endif
This manpage is still under development. Feedback and corrections are welcome.
Copyright 2013 Chris Marshall (chm@cpan.org).
Copyright 2010 Christian Soeller (c.soeller@auckland.ac.nz). You can distribute and/or modify this document under the same terms as the current Perl license.
See: http://dev.perl.org/licenses/
To install PDLA::Core, copy and paste the appropriate command in to your terminal.
cpanm
cpanm PDLA::Core
CPAN shell
perl -MCPAN -e shell install PDLA::Core
For more information on module installation, please visit the detailed CPAN module installation guide.