API(1p)

📦

version 2.085 · 3 versions

2.085 · ubuntu noble (latest)
2.074 · ubuntu jammy
2.081 · debian bookworm

✨ API(1p) ✨

okay so bestie, this page is literally from the User Contributed Perl Documentation and it's all about PDL::API. Buckle up, it's giving full cookbook energy 💅

🌸 NAME 🌸

PDL::API — making ndarrays from Perl and C/XS code 🫶

🎀 SYNOPSIS 🎀

  use PDL;
  sub mkmyndarray {
   ...
  }

🦋 DESCRIPTION 🦋

So this is like a lil' cookbook for hand-building ndarrays yourself, no cap. It covers both the Perl side and the C/XS side. On top of that, it walks you through the PDL core routines you can reach from other modules — and those routines are basically the PDL API, fr fr. If you need to poke at ndarrays from C/XS, you're probably gonna need to know these functions. 💀

Also in here: the new way (new as of PDL 2.058) of getting at PDL operations through C functions — which is what the XS functions call now. slay. ✨

Creating an ndarray manually from Perl 🌱

Sometimes you've got a pile of binary data and you just wanna build an ndarray out of it by hand. Totally doable at the Perl level, bestie. Some of the IO routines in the distribution are literally examples of this. Here's the whole required step-by-step:

   use Carp;
   sub mkmyndarray {
     my $class = shift;
     my $pdl  = $class->new;
     $pdl->set_datatype($PDL_B);
     $pdl->setdims([1,3,4]);
     my $dref = $pdl->get_dataref();

     # read data directly from file
     open my $file, '<data.dat' or die "couldn't open data.dat";
     my $len = $pdl->nelems*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 🌈

This next one builds an ndarray over at the C level. We're using the Inline module because it's honestly a great way to hook Perl and C together — specifically the with capability from Inline 0.68+. obsessed. 💖

📌 Quick note bestie: if you wanna make a "scalar" ndarray (meaning no dimensions at all, just a single element), you literally just pass a zero-length dims array with ndims set to zero. that's it, that's the trick ✨

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();
  if (!p) return p;
  pdl_error err = PDL->setdims(p, dims, ndims);  /* set dims */
  if (err.error) { PDL->destroy(p); return NULL; }
  p->datatype = datatype;         /* and data type */
  err = PDL->allocdata (p);       /* allocate the data chunk */
  if (err.error) { PDL->destroy(p); return NULL; }
  return p;
}

pdl* myfloatseq()
{
  PDL_Indx dims[] = {5,5,5};
  pdl *p = new_pdl(PDL_F,dims,3);
  if (!p) return p;
  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 🎁

Okay so sometimes you get a chunk of data handed to you from somewhere else entirely — like an image processing library, whatever. And all you actually want to do is wrap that data up into an ndarray struct at the C level. That's it. 🫶

Examples of this move live in the IO modules (where FastRaw and FlexRaw use it for mmapped access) and in the Gimp Perl module (which uses it to wrap Gimp pixel regions into ndarrays). iconic behavior.

Here's a cute lil' demo script:

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 'p' 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* p = PDL->pdlnew(); /* get the empty container */
  if (!p) return p;
  pdl_error err = PDL->setdims(p, dims, ndims);  /* set dims */
  if (err.error) { PDL->destroy(p); return NULL; }
  p->datatype = datatype;     /* and data type */
  p->data = data;             /* point it to your data */
  /* make sure the core doesn't meddle with your data */
  p->state |= PDL_DONTTOUCHDATA | PDL_ALLOCATED;
  if (delete_magic != NULL)
    PDL->add_deletedata_magic(p, delete_magic, delparam);
  else
    PDL->add_deletedata_magic(p, default_magic, 0);
  return p;
}

#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;
}

🌟 Lowkey the important bit here: when that ndarray gets destroyed on the Perl side, the function you passed as delete_magic gets called with the pointer to the pdl structure plus the delparam argument — that's your moment to do any cleanup you need. At the very least, zero out the ndarray's data pointer. don't skip it bestie 🙈

✨ and we're just getting started ✨

💅 IMPLEMENTATION DETAILS 💅

🧚 The Core struct — getting at PDL core routines at runtime

okay so plot twist: PDL pulls a technique that's basically the same one the Tk modules use so other modules can get their hands on its core routines. The whole pointer to all the shared core PDL routines lives in the $PDL::SHARE variable. XS code needs to grab that pointer at boot time, so the rest of your C/XS code can use it for access at run time. The easiest way to do that initial pointer-loading is with the functions PDL_AUTO_INCLUDE and PDL_BOOT, which are defined and exported by PDL::Core::Dev. ✨

Typical usage with the Inline module? Already flexed earlier, but here it is again:

use Inline with => 'PDL';

In earlier versions of Inline, you did it 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 that PDL_AUTO_INCLUDE hands back makes sure pdlcore.h is included, and declares the static variables that hold the pointer to the Core struct. It looks a lil something like this:

print PDL_AUTO_INCLUDE;

#include <pdlcore.h>
static Core* PDL; /* Structure holds core C functions */

The code PDL_BOOT gives you retrieves the $PDL::SHARE variable and initializes the pointer to the Core struct. For the girlies who know their way around the Perl API, here's 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));
SV* CoreSV = perl_get_sv("PDL::SHARE",FALSE); /* var with core structure */
if (!CoreSV)
  Perl_croak(aTHX_ "We require the PDL::Core module, which was not found");
if (!(PDL = INT2PTR(Core*,SvIV( CoreSV )))) /* Core* value */
  Perl_croak(aTHX_ "Got NULL pointer for PDL");
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 carries version info specifically so it can guarantee that the structure defined in pdlcore.h actually matches the one you got at runtime. The code above tests for exactly that:

if (PDL->Version != PDL_CORE_VERSION)
  ....

Want the full tea on the Core struct? Go see PDL::Internals. 👑

With all that prep done, your code can now access the core routines, just like some of the examples above already showed, e.g.

pdl *p = PDL->pdlnew();

By default the C variable named PDL is what holds the pointer to the Core struct. If that's a problem (for literally any reason), you can explicitly name that variable using the PDL_AUTO_INCLUDE and 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 then use that same identifier in your own code too. E.g., continuing from the example above:

pdl *p = PDL_Corep->pdlnew();

🔥 Some selected core routines explained

The full definition of the Core struct lives in the file pdlcore.h. Below, the most frequently used member functions of that struct get a quick breakdown. 💖

pdl *SvPDLV(SV *sv)
pdl *SetSV_PDL(SV *sv, pdl *it)
pdl *pdlnew()

pdlnew returns an empty pdl object that's initialised like a null but with no data. Example:

pdl *p = PDL->pdlnew();
if (!p) return p;
pdl_error err = PDL->setdims(p, dims, ndims);  /* set dims */
if (err.error) { PDL->destroy(p); return NULL; }
p->datatype = PDL_B;

Returns NULL if a problem occurred, so check for that. 👀

pdl *null()

Returns NULL if a problem occurred, so check for that.

SV *copy(pdl* p, char* )
void *smalloc(STRLEN nbytes)
int howbig(int pdl_datatype)
pdl_error add_deletedata_magic(pdl *p, void (*func)(pdl*, int), int param)
pdl_error allocdata(pdl *p)
pdl_error make_physical(pdl *p)
pdl_error make_physdims(pdl *p)
pdl_error make_physvaffine(pdl *p)
void pdl_barf(const char* pat,...) and void pdl_warn(const char* pat,...)

These are the C-code equivalents of barf and warn. They include special handling of error or warning messages during pthreading (i.e. processor multi-threading) that defers the messages until after pthreading is completed. When pthreading is done, perl's barf or warn gets 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 info on pthreading.

NB As of 2.064, it is highly recommended that you do not call barf at all in PP code, but instead use $CROAK(). This will return a pdl_error which will transparently be used to throw the correct exception in Perl code, but can be handled suitably by non-Perl callers.

converttype

Used by set_datatype to change an ndarray's type, converting and possibly re-allocating the data if a different size. If the ndarray's badflag was set, its badvalue will become the default for the new type. Bad values will still be bad.

converttypei_new

Affine transformation used only by get_convertedpdl to convert an ndarray's type. Not bad-value aware.

get_convertedpdl

Used by convert in PDL::Core.

affine_new

Creates a child vaffine ndarray from a given parent ndarray, with given offs (starting point for that pthread in that ndarray), inclist and dims.

make_trans_mutual

Triggers the actual running of a previously-set-up pdl_trans.

get

Get data at given coordinates.

get_offs

Get data at given offset.

put_offs

Put data at given offset.

setdims_careful

Despite the name, it just calls resize_defaultincs then reallocbroadcastids with one.

destroy

Destroy ndarray.

reallocdims

Cause the ndarray to have given number of dimensions, destroying previous ones.

reallocbroadcastids

Reallocate n broadcastids. Set the new extra ones to the end.

resize_defaultincs

Recalculate default increments from dims, and grow the PDL data.

🎀 Handy macros from pdl.h

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

You might wanna use, for example, the 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;
PDL_Anyval bv = PDL->get_pdl_badvalue(a);
if (bv.type < 0) croak("error getting badvalue");
ANYVAL_TO_CTYPE(bad_a, double, bv);
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) /* returns -1 on type error */

As of PDL 2.039 (returns -1 rather than croaking on failure as of 2.064) there is:

ANYVAL_ISNAN(anyval)

As of PDL 2.040 (changed parameter list, also returns -1 rather than croaking on failure, in 2.064) — and you need to check the badflag first:

ANYVAL_ISBAD(in_anyval, badval)

e.g.

int badflag = (x->state & PDL_BADVAL) > 0;
PDL_Anyval badval = pdl_get_pdl_badvalue(x);
if (badflag) {
  int isbad = ANYVAL_ISBAD(result, badval);
  if (isbad == -1) croak("ANYVAL_ISBAD error on types %d, %d", result.type, badval.type);
  if (isbad)
    RETVAL = newSVpvn( "BAD", 3 );
  else
    ANYVAL_TO_SV(RETVAL, result);
} else
  ANYVAL_TO_SV(RETVAL, result);

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're 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, you will need to include pdlperl.h in any XS file with functions that take or return a PDL_Anyval. 🫶

As of 2.083, ANYVAL_TO_SV assigns a value into the passed SV* using the Perl API, rather than assigning the given C value to having a newly-created SV*, so the caller is responsible for memory-management.

🌈 Access to PDL operations as C functions

As of 2.058, all PDL operations can be accessed from C code in a way that's similar to XS functions, since that's literally 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 get 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. 🎀

✨ COPYRIGHT ✨

Okay bestie, legal era 💅 but make it cute, here's who to thank for this whole thing:

And the licensing tea ☕ — you can distribute and/or modify this document under the same terms as the current Perl license. Yes, the same terms as the current Perl license, no cap, that's the whole vibe.

Wanna read the actual fine print? Go here: http://dev.perl.org/licenses/ 🫶

And that's a wrap on this whole page, bestie 🎀 this was perl v5.38.2, dated 2024-04-10, and it lives as API(1p) in the manual — you ate that whole read, iconic behavior fr fr, go take a lil break 🌸✨

📦 where this page comes from

ubuntu noble: pdl 1:2.085-1ubuntu1 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms