PDL::API - Man Page

making ndarrays from Perl and C/XS code

Synopsis

  use PDL;
  sub mkmyndarray {
   ...
  }

Description

A simple cookbook how to create ndarrays manually. It covers both the Perl and the C/XS level. Additionally, it describes the PDL core routines that can be accessed from other modules. These routines basically define the PDL API. If you need to access ndarrays from C/XS you probably need to know about these functions.

Also described is the new (as of PDL 2.058) access to PDL operations via C functions, which the XS functions now call.

Creating an ndarray manually from Perl

Sometimes you want to create an ndarray 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 mkmyndarray {
     my $class = shift;
     my $pdl  = $class->new;
     $pdl->set_datatype($PDL_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*PDL::Core::howbig($pdl->get_datatype);
     croak "couldn't read enough data" if
       read( $file, $$dref, $len) != $len;
     close $file;
     $pdl->upd_data();

     return $pdl;
   }

Creating an ndarray in C

The following example creates an ndarray at the C level. We use the Inline module which is a good way to interface Perl and C, using the with capability in Inline 0.68+.

Note that to create a “scalar” ndarray (with no dimensions at all, and a single element), just pass a zero-length dims array, with ndims as zero.

   use PDL::LiteF;

   $x = myfloatseq(); # exercise our C ndarray constructor

   print $x->info,"\n";

   use Inline with => 'PDL';
   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, PDL_Indx dims[], int ndims)
   {
     pdl *p = PDL->pdlnew();
     PDL->setdims (p, dims, ndims);  /* set dims */
     p->datatype = datatype;         /* and data type */
     PDL->allocdata (p);             /* allocate the data chunk */

     return p;
   }

   pdl* myfloatseq()
   {
     PDL_Indx dims[] = {5,5,5};
     pdl *p = new_pdl(PDL_F,dims,3);
     PDL_Float *dataf = (PDL_Float *) p->data;
     PDL_Indx i; /* dimensions might be 64bits */

     for (i=0;i<5*5*5;i++)
       dataf[i] = i; /* the data must be initialized ! */
     return p;
   }

Wrapping your own data into an ndarray

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 an ndarray 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 ndarrays). The following script demonstrates a simple example:

   use PDL::LiteF;
   use PDL::Core::Dev;
   use PDL::Graphics::PGPLOT;

   $y = mkndarray();

   print $y->info,"\n";

   imag1 $y;

   use Inline with => 'PDL';
   use Inline C;
   Inline->init;

   __DATA__

   __C__

   /* wrap a user supplied chunk of data into an ndarray
    * You must specify the dimensions (dims,ndims) and 
    * the datatype (constants for the datatypes are declared
    * in pdl.h; e.g. PDL_B for byte type, etc)
    *
    * when the created ndarray '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 ndarray's data pointer:
    * 
    *     void delete_mydata(pdl* pdl, int param)
    *     {
    *       pdl->data = 0;
    *     }
    *     pdl *p = pdl_wrap(mydata, PDL_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, PDL_Indx dims[],
                        int ndims, DelMagic delete_magic, int delparam)
   {
     pdl* npdl = PDL->pdlnew(); /* get the empty container */

     PDL->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 |= PDL_DONTTOUCHDATA | PDL_ALLOCATED;
     if (delete_magic != NULL)
       PDL->add_deletedata_magic(npdl, delete_magic, delparam);
     else
       PDL->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 PDL_Byte* mkramp(void)
   {
     PDL_Byte *data;
     int i; /* should use PDL_Indx to support 64bit pdl indexing */

     if ((data = malloc(SZ*SZ*sizeof(PDL_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* mkndarray()
   {
     PDL_Indx dims[] = {SZ,SZ};
     pdl *p;

     p = pdl_wrap((void *) mkramp(), PDL_B, dims, 2, 
                  delete_myramp,0); /* the delparam is abitrarily set to 0 */
     return p;
   }

Implementation Details

The Core struct — getting at PDL core routines at runtime

PDL 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 PDL routines is stored in the $PDL::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 PDL_AUTO_INCLUDE and PDL_BOOT that are defined and exported by PDL::Core::Dev. Typical usage with the Inline module has already been demonstrated:

   use Inline with => 'PDL';

In earlier versions of Inline, this was achieved like this:

   use Inline C => Config =>
     INC           => &PDL_INCLUDE,
     TYPEMAPS      => &PDL_TYPEMAP,
     AUTO_INCLUDE  => &PDL_AUTO_INCLUDE, # declarations
     BOOT          => &PDL_BOOT;         # code for the XS boot section

The code returned by PDL_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:

   print PDL_AUTO_INCLUDE;

 #include <pdlcore.h>
 static Core* PDL; /* Structure holds core C functions */
 static SV* CoreSV;       /* Gets pointer to Perl var holding core structure */

The code returned by PDL_BOOT retrieves the $PDL::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 ("PDL/Core.pm"); /* make sure PDL::Core is loaded */
#ifndef aTHX_
#define aTHX_
#endif
   if (SvTRUE (ERRSV)) Perl_croak(aTHX_ "%s",SvPV_nolen (ERRSV));
   CoreSV = perl_get_sv("PDL::SHARE",FALSE);  /* SV* value */
   if (CoreSV==NULL)
     Perl_croak(aTHX_ "We require the PDL::Core module, which was not found");
   PDL = INT2PTR(Core*,SvIV( CoreSV ));  /* Core* value */
   if (PDL->Version != PDL_CORE_VERSION)
     Perl_croak(aTHX_ "[PDL->Version: \%d PDL_CORE_VERSION: \%d XS_VERSION: \%s] The code needs to be recompiled against the newly installed PDL", PDL->Version, PDL_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 (PDL->Version != PDL_CORE_VERSION)
     ....

For more information on the Core struct see PDL::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 = PDL->pdlnew();

By default the C variable named PDL 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 PDL_AUTO_INCLUDE and the PDL_BOOT routines:

   use Inline C => Config =>
     INC           => &PDL_INCLUDE,
     TYPEMAPS      => &PDL_TYPEMAP,
     AUTO_INCLUDE  => &PDL_AUTO_INCLUDE 'PDL_Corep',
     BOOT          => &PDL_BOOT 'PDL_Corep';

Make sure you use the same identifier with PDL_AUTO_INCLUDE and PDL_BOOT and use that same identifier in your own code. E.g., continuing from the example above:

  pdl *p = PDL_Corep->pdlnew();

Some selected core routines explained

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 *SvPDLV(SV *sv)
  • pdl *SetSV_PDL(SV *sv, pdl *it)
  • pdl *pdlnew()

    pdlnew returns an empty pdl object that needs further initialization to turn it into a proper ndarray. Example:

      pdl *p = PDL->pdlnew();
      PDL->setdims(p,dims,ndims);
      p->datatype = PDL_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 pdl_barf(const char* pat,...) and 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.

    Note that barf and warn have been redefined (using c-preprocessor macros) in pdlcore.h to PDL->barf and PDL->warn. This is to keep any XS or PP code from calling perl's barf or warn directly, which can cause segfaults during pthreading.

    See PDL::ParallelCPU for more information on pthreading.

Handy macros from pdl.h

Some of the C API functions return PDL_Anyval C type which is a structure and therefore requires special handling.

You might want to use for example get_pdl_badvalue function:

 /* THIS DOES NOT WORK! (although it did in older PDL) */
 if( PDL->get_pdl_badvalue(a) == 0 )  { ... }

 /* THIS IS CORRECT */
 double bad_a;
 ANYVAL_TO_CTYPE(bad_a, double, PDL->get_pdl_badvalue(a));
 if( bad_a == 0 ) { ... }

As of PDL 2.014, in pdl.h there are the following macros for handling PDL_Anyval from C code:

 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 of PDL 2.039 there is:

 ANYVAL_ISNAN(anyval)

As of PDL 2.040 (the additional parameters are to detect the badflag, and handle caching the bad value for efficiency):

 ANYVAL_ISBAD(in_anyval, pdl, badval)

As of PDL 2.058, there are:

  ANYVAL_FROM_CTYPE_OFFSET(result, datatype, x, ioff);
  ANYVAL_TO_CTYPE_OFFSET(x, ioff, datatype, value);

The latter dispatches on both the destination type and the input “anyval” type. They are intended for retrieving values from, and setting them within, ndarrays.

As of PDL 2.048, in pdlperl.h there are:

 ANYVAL_FROM_SV(out_anyval, in_SV, use_undefval, forced_type)
 ANYVAL_TO_SV(out_SV, in_anyval)

Because these are used in the PDL typemap.pdl, you will need to include pdlperl.h in any XS file with functions that take or return a PDL_Anyval.

Access to PDL operations as C functions

As of 2.058, all PDL operations can be accessed from C code in a similar way to XS functions, since that is what the XS functions now call. Each module defines various C functions and data-structures for each operation, as needed to operate as a PDL transformation. The entry point from outside (and from XS functions) is a C function called pdl_(operationname)_run, with a signature derived from its Pars and OtherPars. E.g.

  # from PDL::Primitive
  pp_def('wtstat',
    Pars => 'a(n); wt(n); avg(); [o]b();',
    OtherPars => 'int deg',
    # ...
  );

has the C signature:

  void pdl_wtstat_run(pdl *a, pdl *wt, pdl *avg, pdl *b, int deg);

Not very surprisingly, all pdl* parameters must be initialised (at least to PDL->null status), and they are changed according to the operation's specification. This makes the XS _(name)_int non-varargs XS functions very thin layers over this.

See Also

PDL

Inline

Bugs

This manpage is still under development. Feedback and corrections are welcome.

Info

2021-11-22 perl v5.34.0 User Contributed Perl Documentation