PDL::Internals 2.4.3

PDL::Internals is a Perl module that contains a description of some aspects of the current internals.

Intro

This document explains various aspects of the current implementation of PDL. If you just want to use PDL for something, you definitely do not need to read this. Even if you want to interface your C routines to PDL or create new PDL::PP functions, you do not need to read this man page (though it may be informative). This document is primarily intended for people interested in debugging or changing the internals of PDL. To read this, a good understanding of the C language and programming and data structures in general is required, as well as some Perl understanding. If you read through this document and understand all of it and are able to point what any part of this document refers to in the PDL core sources and additionally struggle to understand PDL::PP, you will be awarded the title "PDL Guru" (of course, the current version of this document is so incomplete that this is next to impossible from just these notes).

Warning: If it seems that this document has gotten out of date, please inform the PDL porters email list (pdl-porters@jach.hawaii.edu). This may well happen.

Piddles

The pdl data object is generally an opaque scalar reference into a pdl structure in memory. Alternatively, it may be a hash reference with the PDL field containing the scalar reference (this makes overloading piddles easy, see PDL::Objects). You can easily find out at the Perl level which type of piddle you are dealing with. The example code below demonstrates how to do it:

# check if this a piddle
die "not a piddle" unless UNIVERSAL::isa($pdl, PDL);
# is it a scalar ref or a hash ref?
if (UNIVERSAL::isa($pdl, "HASH")) {
die "not a valid PDL" unless exists $pdl->{PDL} &&
UNIVERSAL::isa($pdl->{PDL},PDL);
print "This is a hash reference,",
" the PDL field contains the scalar refn";
} else {
print "This is a scalar ref that points to address $$pdl in memoryn";
}

The scalar reference points to the numeric address of a C structure of type pdl which is defined in pdl.h. The mapping between the object at the Perl level and the C structure containing the actual data and structural that makes up a piddle is done by the PDL typemap. The functions used in the PDL typemap are defined pretty much at the top of the file pdlcore.h. So what does the structure look like:

struct pdl {
unsigned long magicno; /* Always stores PDL_MAGICNO as a sanity check */
/* This is first so most pointer accesses to wrong type are caught */
int state; /* Whats in this pdl */

pdl_trans *trans; /* Opaque pointer to internals of transformation from
parent */

pdl_vaffine *vafftrans;

void* sv; /* (optional) pointer back to original sv.
ALWAYS check for non-null before use.
We cannot inc refcnt on this one or wed
never get destroyed */

void *datasv; /* Pointer to SV containing data. Refcnt inced */
void *data; /* Null: no data alloced for this one */
int nvals; /* How many values allocated */
int datatype;
PDL_Long *dims; /* Array of data dimensions */
PDL_Long *dimincs; /* Array of data default increments */
short ndims; /* Number of data dimensions */

unsigned char *threadids; /* Starting index of the thread index set n */
unsigned char nthreadids;

pdl *progenitor; /* Im in a mutated family. make_physical_now must
copy me to the new generation. */
pdl *future_me; /* Im the "then" pdl and this is my "now" (or more modern
version, anyway */

pdl_children children;

short living_for; /* perl side not referenced; delete me when */

PDL_Long def_dims[PDL_NDIMS]; /* Preallocated space for efficiency */
PDL_Long def_dimincs[PDL_NDIMS]; /* Preallocated space for efficiency */
unsigned char def_threadids[PDL_NTHREADIDS];

struct pdl_magic *magic;

void *hdrsv; /* "header", settable from outside */
};

This is quite a structure for just storing some data in - what is going on?