1PP(1) User Contributed Perl Documentation PP(1)
2
6 PDL::PP - Generate PDL routines from concise descriptions
7
9 # let PDL::PP tell you what it's doing
10 $::PP_VERBOSE = 1;
11 pp_def(
12 'sumover',
13 Pars => 'a(n); [o]b();',
14 Code => q{
15 double tmp=0;
16 loop(n) %{
17 tmp += $a();
18 %}
19 $b() = tmp;
20 },
21 );
22 pp_done();
24 # do not call exit() as some processing can be done in same process
25
27 Here is a quick reference list of the functions provided by PDL::PP.
28 pp_add_boot
30 Add code to the BOOT section of generated XS file
31 pp_add_exported
33 Add functions to the list of exported functions
34 pp_add_isa
36 Add entries to the @ISA list
37 pp_addbegin
39 Sets code to be added at the top of the generate .pm file
40 pp_addhdr
42 Add code and includes to C section of the generated XS file.
43 When used in a module that is "multi-C" (one .c file per "pp_def"ed
45 function), you need to bear in mind that as each one is generated, all
46 the "pp_addhdr" so far will be included. Therefore, if you add C
47 functions, make sure to make them "static" to avoid clashes with later
48 .c files. But a better practice is make them be separate C files, with
49 any necessary .h to be included by them and the .pd file. You can then
50 add them to your Makefile.PL (note this is the "_int" version, see
51 separate notes on how to "opt-in" for your own modules):
52 my @pack = (["pnm.pd", qw(Pnm PDL::IO::Pnm)]);
54 my %hash = pdlpp_stdargs_int(@pack);
55 $hash{OBJECT} .= ' get$(OBJ_EXT)';
56 sub MY::postamble { pdlpp_postamble_int(@pack); }
57 WriteMakefile(%hash);
58 pp_addpm
60 Add code to the generated .pm file
61 pp_addxs
63 Add extra XS code to the generated XS file
64 pp_add_macros
66 Add extra $MACRO() definitions for these functions. Note these generate
67 C code. As of 2.080, they will be passed the list of arguments they
68 were called with, rather than a single string, split like the C pre-
69 processor on commas except if in "" or "()", with leading and trailing
70 whitespace removed.
71 pp_add_macros(SUCC => sub { "($_[0] + 1)" });
73 # ...
74 Code => '$a() = $SUCC($b());',
75 pp_add_typemaps
77 Available from 2.082. Add an XS typemap for use as "OtherPars" or from
78 manually-added XS. Takes one named argument, either "typemap" (an
79 ExtUtils::Typemaps object), "string", or "file".
80 pp_add_typemaps(string=><<'EOT');
82 TYPEMAP: <<END_OF_TYPEMAP
83 TYPEMAP
84 NV_ADD1 T_NV_ADD1
85 INPUT
87 T_NV_ADD1
88 $var = SvNV($arg) + 1;
89 OUTPUT
91 T_NV_ADD1
92 sv_setnv($arg, $var - 1);
93 END_OF_TYPEMAP
94 EOT
95 # ...
96 OtherPars => '[o] NV_ADD1 v1',
97 pp_beginwrap
99 Add BEGIN-block wrapping to code for the generated .pm file
100 pp_bless
102 Sets the package to which the XS code is added (default is PDL)
103 pp_core_importList
105 Specify what is imported from PDL::Core
106 pp_def
108 Define a new PDL function
109 pp_deprecate_module
111 Add runtime and POD warnings about a module being deprecated
112 pp_done
114 Mark the end of PDL::PP definitions in the file
115 pp_export_nothing
117 Clear out the export list for your generated module
118 pp_line_numbers
120 Add line number information to simplify debugging of PDL::PP code
121
123 For an alternate introduction to PDL::PP, see Practical Magick with C,
124 PDL, and PDL::PP -- a guide to compiled add-ons for PDL
125 <https://arxiv.org/abs/1702.07753>.
126 Why do we need PP? Several reasons: firstly, we want to be able to
128 generate subroutine code for each of the PDL datatypes (PDL_Byte,
129 PDL_Short, etc). AUTOMATICALLY. Secondly, when referring to slices of
130 PDL arrays in Perl (e.g. "$x->slice('0:10:2,:')" or other things such
131 as transposes) it is nice to be able to do this transparently and to be
132 able to do this 'in-place' - i.e, not to have to make a memory copy of
133 the section. PP handles all the necessary element and offset arithmetic
134 for you. There are also the notions of broadcasting (repeated calling
135 of the same routine for multiple slices, see PDL::Indexing) and
136 dataflow (see PDL::Dataflow, and "DefaultFlow") which use of PP allows.
137 In much of what follows we will assume familiarity of the reader with
139 the concepts of implicit and explicit broadcasting and index
140 manipulations within PDL. If you have not yet heard of these concepts
141 or are not very comfortable with them it is time to check
142 PDL::Indexing.
143 As you may appreciate from its name PDL::PP is a Pre-Processor, i.e.
145 it expands code via substitutions to make real C-code. Technically, the
146 output is XS code (see perlxs) but that is very close to C.
147 So how do you use PP? Well for the most part you just write ordinary C
149 code except for special PP constructs which take the form:
150 $something(something else)
152 or:
154 PPfunction %{
156 <stuff>
157 %}
158 The most important PP construct is the form $array(). Consider the very
160 simple PP function to sum the elements of a 1D vector (in fact this is
161 very similar to the actual code used by 'sumover'):
162 pp_def('sumit',
164 Pars => 'a(n); [o]b();',
165 Code => q{
166 double tmp;
167 tmp = 0;
168 loop(n) %{
169 tmp += $a();
170 %}
171 $b() = tmp;
172 }
173 );
174 What's going on? The "Pars =>" line is very important for PP - it
176 specifies all the arguments and their dimensionality. We call this the
177 signature of the PP function (compare also the explanations in
178 PDL::Indexing). In this case the routine takes a 1-D function as input
179 and returns a 0-D scalar as output. The $a() PP construct is used to
180 access elements of the array a(n) for you - PP fills in all the
181 required C code.
182 You will notice that we are using the "q{}" single-quote operator. This
184 is not an accident. You generally want to use single quotes to denote
185 your PP Code sections. PDL::PP uses $var() for its parsing and if you
186 don't use single quotes, Perl will try to interpolate $var(). Also,
187 using the single quote "q" operator with curly braces makes it look
188 like you are creating a code block, which is What You Mean. (Perl is
189 smart enough to look for nested curly braces and not close the quote
190 until it finds the matching curly brace, so it's safe to have nested
191 blocks.) Under other circumstances, such as when you're stitching
192 together a Code block using string concatenations, it's often easiest
193 to use real single quotes as
194 Code => 'something'.$interpolatable.'somethingelse;'
196 In the simple case here where all elements are accessed the PP
198 construct "loop(n) %{ ... %}" is used to loop over all elements in
199 dimension "n". Note this feature of PP: ALL DIMENSIONS ARE SPECIFIED
200 BY NAME.
201 This is made clearer if we avoid the PP loop() construct and write the
203 loop explicitly using conventional C:
204 pp_def('sumit',
206 Pars => 'a(n); [o]b();',
207 Code => q{
208 PDL_Indx i,n_size;
209 double tmp;
210 n_size = $SIZE(n);
211 tmp = 0;
212 for(i=0; i<n_size; i++) {
213 tmp += $a(n=>i);
214 }
215 $b() = tmp;
216 },
217 );
218 which does the same as before, but is more long-winded. You can see to
220 get element "i" of a() we say $a(n=>i) - we are specifying the
221 dimension by name "n". In 2D we might say:
222 Pars=>'a(m,n);',
224 ...
225 tmp += $a(m=>i,n=>j);
226 ...
227 The syntax "m=>i" borrows from Perl hashes, which are in fact used in
229 the implementation of PP. One could also say "$a(n=>j,m=>i)" as order
230 is not important.
231 You can also see in the above example the use of another PP construct -
233 $SIZE(n) to get the length of the dimension "n".
234 It should, however, be noted that you shouldn't write an explicit
236 C-loop when you could have used the PP "loop" construct since PDL::PP
237 checks automatically the loop limits for you, usage of "loop" makes the
238 code more concise, etc. But there are certainly situations where you
239 need explicit control of the loop and now you know how to do it ;).
240 To revisit 'Why PP?' - the above code for sumit() will be generated for
242 each data-type. It will operate on slices of arrays 'in-place'. It will
243 broadcast automatically - e.g. if a 2D array is given it will be called
244 repeatedly for each 1D row (again check PDL::Indexing for the details
245 of broadcasting). And then b() will be a 1D array of sums of each row.
246 We could call it with $x->transpose to sum the columns instead. And
247 Dataflow tracing etc. will be available.
248 You can see PP saves the programmer from writing a lot of needlessly
250 repetitive C-code -- in our opinion this is one of the best features of
251 PDL making writing new C subroutines for PDL an amazingly concise
252 exercise. A second reason is the ability to make PP expand your concise
253 code definitions into different C code based on the needs of the
254 computer architecture in question. Imagine for example you are lucky to
255 have a supercomputer at your hands; in that case you want PDL::PP
256 certainly to generate code that takes advantage of the
257 vectorising/parallel computing features of your machine (this a project
258 for the future). In any case, the bottom line is that your unchanged
259 code should still expand to working XS code even if the internals of
260 PDL changed.
261 Also, because you are generating the code in an actual Perl script,
263 there are many fun things that you can do. Let's say that you need to
264 write both sumit (as above) and multit. With a little bit of
265 creativity, we can do
266 for({Name => 'sumit', Init => '0', Op => '+='},
268 {Name => 'multit', Init => '1', Op => '*='}) {
269 pp_def($_->{Name},
270 Pars => 'a(n); [o]b();',
271 Code => '
272 double tmp;
273 tmp = '.$_->{Init}.';
274 loop(n) %{
275 tmp '.$_->{Op}.' $a();
276 %}
277 $b() = tmp;
278 ');
279 }
280 which defines both the functions easily. Now, if you later need to
282 change the signature or dimensionality or whatever, you only need to
283 change one place in your code. Yeah, sure, your editor does have 'cut
284 and paste' and 'search and replace' but it's still less bothersome and
285 definitely more difficult to forget just one place and have strange
286 bugs creep in. Also, adding 'orit' (bitwise or) later is a one-liner.
287 And remember, you really have Perl's full abilities with you - you can
289 very easily read any input file and make routines from the information
290 in that file. For simple cases like the above, the author (Tjl)
291 currently favors the hash syntax like the above - it's not too much
292 more characters than the corresponding array syntax but much easier to
293 understand and change.
294 As of 2.064, the "Code" must not just "return", since the signature of
296 the generated functions has changed from returning "void" to returning
297 a "pdl_error", which is pre-initialised to a successful return value.
298 You can easily just replace the "return;" with "return PDL_err;", which
299 is the variable's name.
300 We should mention here also the ability to get the pointer to the
302 beginning of the data in memory - a prerequisite for interfacing PDL to
303 some libraries. This is handled with the $P(var) directive, see below.
304 When starting work on a new pp_def'ined function, if you make a
306 mistake, you will usually find a pile of compiler errors indicating
307 line numbers in the generated XS file. If you know how to read XS files
308 (or if you want to learn the hard way), you could open the generated XS
309 file and search for the line number with the error. However, a recent
310 addition to PDL::PP helps report the correct line number of your
311 errors: "pp_line_numbers". Working with the original summit example, if
312 you had a mis-spelling of tmp in your code, you could change the
313 (erroneous) code to something like this and the compiler would give you
314 much more useful information:
315 pp_def('sumit',
317 Pars => 'a(n); [o]b();',
318 Code => pp_line_numbers(__LINE__, q{
319 double tmp;
320 tmp = 0;
321 loop(n) %{
322 tmp += $a();
323 %}
324 $b() = rmp;
325 })
326 );
327 For the above situation, my compiler tells me:
329 ...
331 test.pd:15: error: 'rmp' undeclared (first use in this function)
332 ...
333 In my example script (called test.pd), line 15 is exactly the line at
335 which I made my typo: "rmp" instead of "tmp".
336 So, after this quick overview of the general flavour of programming PDL
338 routines using PDL::PP let's summarise in which circumstances you
339 should actually use this preprocessor/precompiler. You should use
340 PDL::PP if you want to
341 • interface PDL to some external library
343 • write some algorithm that would be slow if coded in Perl (this is
345 not as often as you think; take a look at broadcasting and dataflow
346 first).
347 • be a PDL developer (and even then it's not obligatory)
349
351 Because of its architecture, PDL::PP can be both flexible and easy to
352 use on the one hand, yet exuberantly complicated at the same time.
353 Currently, part of the problem is that error messages are not very
354 informative and if something goes wrong, you'd better know what you are
355 doing and be able to hack your way through the internals (or be able to
356 figure out by trial and error what is wrong with your args to
357 "pp_def"). Although work is being done to produce better warnings, do
358 not be afraid to send your questions to the mailing list if you run
359 into trouble.
360
362 Now that you have some idea how to use "pp_def" to define new PDL
363 functions it is time to explain the general syntax of "pp_def".
364 "pp_def" takes as arguments first the name of the function you are
365 defining and then a hash list that can contain various keys.
366 Based on these keys PP generates XS code and a .pm file. The function
368 "pp_done" (see example in the SYNOPSIS) is used to tell PDL::PP that
369 there are no more definitions in this file and it is time to generate
370 the .xs and
371 .pm file.
372 As a consequence, there may be several pp_def() calls inside a file (by
374 convention files with PP code have the extension .pd or .pp) but
375 generally only one pp_done().
376 There are two main different types of usage of pp_def(), the 'data
378 operation' and 'slice operation' prototypes.
379 The 'data operation' is used to take some data, mangle it and output
381 some other data; this includes for example the '+' operation, matrix
382 inverse, sumover etc and all the examples we have talked about in this
383 document so far. Implicit and explicit broadcasting and the creation of
384 the result are taken care of automatically in those operations. You can
385 even do dataflow with "sumit", "sumover", etc (don't be dismayed if you
386 don't understand the concept of dataflow in PDL very well yet; it is
387 still very much experimental).
388 The 'slice operation' is a different kind of operation: in a slice
390 operation, you are not changing any data, you are defining
391 correspondences between different elements of two ndarrays (examples
392 include the index manipulation/slicing function definitions in the file
393 slices.pd that is part of the PDL distribution; but beware, this is not
394 introductory level stuff).
395 To support bad values, additional keys are required for "pp_def", as
397 explained below.
398 If you are just interested in communicating with some external library
400 (for example some linear algebra/matrix library), you'll usually want
401 the 'data operation' so we are going to discuss that first.
402
404 A simple example
405 In the data operation, you must know what dimensions of data you need.
406 First, an example with scalars:
407 pp_def('add',
409 Pars => 'a(); b(); [o]c();',
410 Code => '$c() = $a() + $b();'
411 );
412 That looks a little strange but let's dissect it. The first line is
414 easy: we're defining a routine with the name 'add'. The second line
415 simply declares our parameters and the parentheses mean that they are
416 scalars. We call the string that defines our parameters and their
417 dimensionality the signature of that function. For its relevance with
418 regard to broadcasting and index manipulations check the PDL::Indexing
419 man page.
420 The third line is the actual operation. You need to use the dollar
422 signs and parentheses to refer to your parameters (this will probably
423 change at some point in the future, once a good syntax is found).
424 These lines are all that is necessary to actually define the function
426 for PDL (well, actually it isn't; you additionally need to write a
427 Makefile.PL (see below) and build the module (something like 'perl
428 Makefile.PL; make'); but let's ignore that for the moment). So now you
429 can do
430 use MyModule;
432 $x = pdl 2,3,4;
433 $y = pdl 5;
434 $c = add($x,$y);
436 # or
437 add($x,$y,($c=null)); # Alternative form, useful if $c has been
438 # preset to something big, not useful here.
439 and have broadcasting work correctly (the result is $c == [7 8 9]).
441 The Pars section: the signature of a PP function
443 Seeing the above example code you will most probably ask: what is this
444 strange "$c=null" syntax in the second call to our new "add" function?
445 If you take another look at the definition of "add" you will notice
446 that the third argument "c" is flagged with the qualifier "[o]" which
447 tells PDL::PP that this is an output argument. So the above call to add
448 means 'create a new $c from scratch with correct dimensions' - "null"
449 is a special token for 'empty ndarray' (you might ask why we haven't
450 used the value "undef" to flag this instead of the PDL specific "null";
451 we are currently thinking about it ;).
452 [This should be explained in some other section of the manual as
454 well!!] The reason for having this syntax as an alternative is that if
455 you have really huge ndarrays, you can do
456 $c = PDL->null;
458 for(some long loop) {
459 # munge a,b
460 add($x,$y,$c);
461 # munge c, put something back to x,y
462 }
463 and avoid allocating and deallocating $c each time. It is allocated
465 once at the first add() and thereafter the memory stays until $c is
466 destroyed.
467 If you just say
469 $c = add($x,$y);
471 the code generated by PP will automatically fill in "$c=null" and
473 return the result. If you want to learn more about the reasons why
474 PDL::PP supports this style where output arguments are given as last
475 arguments check the PDL::Indexing man page.
476 "[o]" is not the only qualifier a pdl argument can have in the
478 signature. Another important qualifier is the "[t]" option which flags
479 a pdl as temporary. What does that mean? You tell PDL::PP that this
480 pdl is only used for temporary results in the course of the calculation
481 and you are not interested in its value after the computation has been
482 completed. But why should PDL::PP want to know about this in the first
483 place? The reason is closely related to the concepts of pdl auto
484 creation (you heard about that above) and implicit broadcasting. If you
485 use implicit broadcasting the dimensionality of automatically created
486 pdls is actually larger than that specified in the signature. With
487 "[o]" flagged pdls will be created so that they have the additional
488 dimensions as required by the number of implicit broadcast dimensions.
489 When creating a temporary pdl, however, it will always only be made big
490 enough so that it can hold the result for one iteration in a broadcast
491 loop, i.e. as large as required by the signature. So less memory is
492 wasted when you flag a pdl as temporary. Secondly, you can use output
493 auto creation with temporary pdls even when you are using explicit
494 broadcasting which is forbidden for normal output pdls flagged with
495 "[o]" (see PDL::Indexing).
496 As of 2.073, the user is unable to pass a "[t]" parameter, and PDL will
498 create and size it to its notional size, times the number of threads.
499 Here is an example where we use the "[t]" qualifier. We define the
501 function "callf" that calls a C routine "f" which needs a temporary
502 array of the same size and type as the array "a" (sorry about the
503 forward reference for $P; it's a pointer access, see below) :
504 pp_def('callf',
506 Pars => 'a(n); [t] tmp(n); [o] b()',
507 Code => 'PDL_Indx ns = $SIZE(n);
508 f($P(a),$P(b),$P(tmp),ns);
509 '
510 );
511 Another possible qualifier is "[phys]". If given, this means the pdl
513 will have "make_physical" in PDL::Core called on it.
514 Additionally, if it has a specified dimension "d" that has value 1, "d"
516 will not magically be grown if "d" is larger in another pdl with
517 specified dimension "d", and instead an exception will be thrown. E.g.:
518 pp_def('callf',
520 Pars => 'a(n); [phys] b(n); [o] c()',
521 # ...
522 );
523 If "a" had lead dimension of 2 and "b" of 3, an exception will always
525 be thrown. However, if "b" has lead dimension of 1, it would be
526 silently repeated as if it were 2, if it were not a "phys" parameter.
527 Argument dimensions and the signature
529 Now we have just talked about dimensions of pdls and the signature. How
530 are they related? Let's say that we want to add a scalar + the index
531 number to a vector:
532 pp_def('add2',
534 Pars => 'a(n); b(); [o]c(n);',
535 Code => 'loop(n) %{
536 $c() = $a() + $b() + n;
537 %}'
538 );
539 There are several points to notice here: first, the "Pars" argument now
541 contains the n arguments to show that we have a single dimensions in a
542 and c. It is important to note that dimensions are actual entities that
543 are accessed by name so this declares a and c to have the same first
544 dimensions. In most PP definitions the size of named dimensions will be
545 set from the respective dimensions of non-output pdls (those with no
546 "[o]" flag) but sometimes you might want to set the size of a named
547 dimension explicitly through an integer parameter. See below in the
548 description of the "OtherPars" section how that works.
549 Constant argument dimensions in the signature
551 Suppose you want an output ndarray to be created automatically and you
552 know that on every call its dimension will have the same size (say 9)
553 regardless of the dimensions of the input ndarrays. In this case you
554 use the following syntax in the Pars section to specify the size of the
555 dimension:
556 ' [o] y(n=9); '
558 As expected, extra dimensions required by broadcasting will be created
560 if necessary. If you need to assign a named dimension according to a
561 more complicated formula (than a constant) you must use the
562 "RedoDimsCode" key described below.
563 Type conversions and the signature
565 The signature also determines the type conversions that will be
566 performed when a PP function is invoked. So what happens when we invoke
567 one of our previously defined functions with pdls of different type,
568 e.g.
569 add2($x,$y,($ret=null));
571 where $x is of type "PDL_Float" and $y of type "PDL_Short"? With the
573 signature as shown in the definition of "add2" above the datatype of
574 the operation (as determined at runtime) is that of the pdl with the
575 'highest' type (sequence is byte < short < ushort < long < float <
576 double). In the add2 example the datatype of the operation is float ($x
577 has that datatype). All pdl arguments are then type converted to that
578 datatype (they are not converted inplace but a copy with the right type
579 is created if a pdl argument doesn't have the type of the operation).
580 Null pdls don't contribute a type in the determination of the type of
581 the operation. However, they will be created with the datatype of the
582 operation; here, for example, $ret will be of type float. You should be
583 aware of these rules when calling PP functions with pdls of different
584 types to take the additional storage and runtime requirements into
585 account.
586 These type conversions are correct for most functions you normally
588 define with "pp_def". However, there are certain cases where slightly
589 modified type conversion behaviour is desired. For these cases
590 additional qualifiers in the signature can be used to specify the
591 desired properties with regard to type conversion. These qualifiers can
592 be combined with those we have encountered already (the creation
593 qualifiers "[o]" and "[t]"). Let's go through the list of qualifiers
594 that change type conversion behaviour.
595 The most important is the "indx" qualifier which comes in handy when a
597 pdl argument represents indices into another pdl. Let's take a look at
598 an example from "PDL::Ufunc":
599 pp_def('maximum_ind',
601 Pars => 'a(n); indx [o] b()',
602 Code => '$GENERIC() cur;
603 PDL_Indx curind;
604 loop(n) %{
605 if (!n || $a() > cur) {cur = $a(); curind = n;}
606 %}
607 $b() = curind;',
608 );
609 The function "maximum_ind" finds the index of the largest element of a
611 vector. If you look at the signature you notice that the output
612 argument "b" has been declared with the additional "indx" qualifier.
613 This has the following consequences for type conversions: regardless of
614 the type of the input pdl "a" the output pdl "b" will be of type
615 "PDL_Indx" which makes sense since "b" will represent an index into
616 "a".
617 Note that 'curind' is declared as type "PDL_Indx" and not "indx".
619 While most datatype declarations in the 'Pars' section use the same
620 name as the underlying C type, "indx" is a type which is sufficient to
621 handle PDL indexing operations. For 32-bit installs, it can be a
622 32-bit integer type. For 64-bit installs, it will be a 64-bit integer
623 type.
624 Furthermore, if you call the function with an existing output pdl "b"
626 its type will not influence the datatype of the operation (see above).
627 Hence, even if "a" is of a smaller type than "b" it will not be
628 converted to match the type of "b" but stays untouched, which saves
629 memory and CPU cycles and is the right thing to do when "b" represents
630 indices. Also note that you can use the 'indx' qualifier together with
631 other qualifiers (the "[o]" and "[t]" qualifiers). Order is significant
632 -- type qualifiers precede creation qualifiers ("[o]" and "[t]").
633 The above example also demonstrates typical usage of the $GENERIC()
635 macro. It expands to the current type in a so called generic loop.
636 What is a generic loop? As you already heard a PP function has a
637 runtime datatype as determined by the type of the pdl arguments it has
638 been invoked with. The PP generated XS code for this function
639 therefore contains a switch like "switch (type) {case PDL_Byte: ...
640 case PDL_Double: ...}" that selects a case based on the runtime
641 datatype of the function (it's called a type ``loop'' because there is
642 a loop in PP code that generates the cases). In any case your code is
643 inserted once for each PDL type into this switch statement. The
644 $GENERIC() macro just expands to the respective type in each copy of
645 your parsed code in this "switch" statement, e.g., in the "case
646 PDL_Byte" section "cur" will expand to "PDL_Byte" and so on for the
647 other case statements. I guess you realise that this is a useful macro
648 to hold values of pdls in some code.
649 There are a couple of other qualifiers with similar effects as "indx".
651 For your convenience there are the "float" and "double" qualifiers with
652 analogous consequences on type conversions as "indx". Let's assume you
653 have a very large array for which you want to compute row and column
654 sums with an equivalent of the "sumover" function. However, with the
655 normal definition of "sumover" you might run into problems when your
656 data is, e.g. of type short. A call like
657 sumover($large_pdl,($sums = null));
659 will result in $sums be of type short and is therefore prone to
661 overflow errors if $large_pdl is a very large array. On the other hand
662 calling
663 @dims = $large_pdl->dims; shift @dims;
665 sumover($large_pdl,($sums = zeroes(double,@dims)));
666 is not a good alternative either. Now we don't have overflow problems
668 with $sums but at the expense of a type conversion of $large_pdl to
669 double, something bad if this is really a large pdl. That's where
670 "double" comes in handy:
671 pp_def('sumoverd',
673 Pars => 'a(n); double [o] b()',
674 Code => 'double tmp=0;
675 loop(n) %{ tmp += a(); %}
676 $b() = tmp;',
677 );
678 This gets us around the type conversion and overflow problems. Again,
680 analogous to the "indx" qualifier "double" results in "b" always being
681 of type double regardless of the type of "a" without leading to a type
682 conversion of "a" as a side effect.
683 There is also a special type, "real". The others above are all actual
685 PDL/C datatypes, but "real" is a modifier; if the operation type is
686 real, it has no effect; if it is complex, then the parameter will be
687 the real version - so "cdouble" becomes "double", etc.
688 There is also the converse, "complex". If the operation is already
690 complex, there is no effect; if not, the output will be promoted to the
691 type's "complexversion" in PDL::Type, which defaults to "cfloat". Note
692 this is controlled both by the PDL::Types data, and the code in
693 PDL::PP. NB Because this outputs floating-point data, the inputs will
694 by definition be turned into such. Therefore, it only makes sense to
695 have floating-point "GenericTypes" inputs. If you want to default to
696 coercing inputs to "float", give that as the last "GenericTypes" as the
697 generated XS function defaults to the last-given one. Hence (with the
698 "PMCode" and "Doc" omitted):
699 pp_def('r2C',
701 GenericTypes=>[reverse qw(F D G C)], # last one is default so here = F
702 Pars => 'r(); complex [o]c()',
703 Code => '$c() = $r();'
704 );
705 Finally, there are the "type+" qualifiers where type is one of "int" or
707 "float". What shall that mean. Let's illustrate the "int+" qualifier
708 with the actual definition of sumover:
709 pp_def('sumover',
711 Pars => 'a(n); int+ [o] b()',
712 Code => '$GENERIC(b) tmp=0;
713 loop(n) %{ tmp += a(); %}
714 $b() = tmp;',
715 );
716 As we had already seen for the "int", "float" and "double" qualifiers,
718 a pdl marked with a "type+" qualifier does not influence the datatype
719 of the pdl operation. Its meaning is "make this pdl at least of type
720 "type" or higher, as required by the type of the operation". In the
721 sumover example this means that when you call the function with an "a"
722 of type PDL_Short the output pdl will be of type PDL_Long (just as
723 would have been the case with the "int" qualifier). This again tries to
724 avoid overflow problems when using small datatypes (e.g. byte images).
725 However, when the datatype of the operation is higher than the type
726 specified in the "type+" qualifier "b" will be created with the
727 datatype of the operation, e.g. when "a" is of type double then "b"
728 will be double as well. We hope you agree that this is sensible
729 behaviour for "sumover". It should be obvious how the "float+"
730 qualifier works by analogy. It may become necessary to be able to
731 specify a set of alternative types for the parameters. However, this
732 will probably not be implemented until someone comes up with a
733 reasonable use for it.
734 Note that we now had to specify the $GENERIC macro with the name of the
736 pdl to derive the type from that argument. Why is that? If you
737 carefully followed our explanations you will have realised that in some
738 cases "b" will have a different type than the type of the operation.
739 Calling the '$GENERIC' macro with "b" as argument makes sure that the
740 type will always the same as that of "b" in that part of the generic
741 loop.
742 This is about all there is to say about the "Pars" section in a
744 "pp_def" call. You should remember that this section defines the
745 signature of a PP defined function, you can use several options to
746 qualify certain arguments as output and temporary args and all
747 dimensions that you can later refer to in the "Code" section are
748 defined by name.
749 It is important that you understand the meaning of the signature since
751 in the latest PDL versions you can use it to define broadcasting
752 functions from within Perl, i.e. what we call Perl level broadcasting.
753 Please check PDL::Indexing for details.
754 The Code section
756 The "Code" section contains the actual XS code that will be in the
757 innermost part of a broadcast loop (if you don't know what a broadcast
758 loop is then you still haven't read PDL::Indexing; do it now ;) after
759 any PP macros (like $GENERIC) and PP functions have been expanded (like
760 the "loop" function we are going to explain next).
761 Let's quickly reiterate the "sumover" example:
763 pp_def('sumover',
765 Pars => 'a(n); int+ [o] b()',
766 Code => '$GENERIC(b) tmp=0;
767 loop(n) %{ tmp += a(); %}
768 $b() = tmp;',
769 );
770 The "loop" construct in the "Code" section also refers to the dimension
772 name so you don't need to specify any limits: the loop is correctly
773 sized and everything is done for you, again.
774 Next, there is the surprising fact that $a() and $b() do not contain
776 the index. This is not necessary because we're looping over n and both
777 variables know which dimensions they have so they automatically know
778 they're being looped over.
779 This feature comes in very handy in many places and makes for much
781 shorter code. Of course, there are times when you want to circumvent
782 this; here is a function which make a matrix symmetric and serves as an
783 example of how to code explicit looping:
784 pp_def('symm',
786 Pars => 'a(n,n); [o]c(n,n);',
787 Code => 'loop(n) %{
788 int n2;
789 for(n2=n; n2<$SIZE(n); n2++) {
790 $c(n0 => n, n1 => n2) =
791 $c(n0 => n2, n1 => n) =
792 $a(n0 => n, n1 => n2);
793 }
794 %}
795 '
796 );
797 Let's dissect what is happening. Firstly, what is this function
799 supposed to do? From its signature you see that it takes a 2D matrix
800 with equal numbers of columns and rows and outputs a matrix of the same
801 size. From a given input matrix $a it computes a symmetric output
802 matrix $c (symmetric in the matrix sense that A^T = A where ^T means
803 matrix transpose, or in PDL parlance $c == $c->transpose). It does this
804 by using only the values on and below the diagonal of $a. In the output
805 matrix $c all values on and below the diagonal are the same as those in
806 $a while those above the diagonal are a mirror image of those below the
807 diagonal (above and below are here interpreted in the way that PDL
808 prints 2D pdls). If this explanation still sounds a bit strange just go
809 ahead, make a little file into which you write this definition, build
810 the new PDL extension (see section on Makefiles for PP code) and try it
811 out with a couple of examples.
812 Having explained what the function is supposed to do there are a couple
814 of points worth noting from the syntactical point of view. First, we
815 get the size of the dimension named "n" again by using the $SIZE macro.
816 Second, there are suddenly these funny "n0" and "n1" index names in the
817 code though the signature defines only the dimension "n". Why this? The
818 reason becomes clear when you note that both the first and second
819 dimension of $a and $b are named "n" in the signature of "symm". This
820 tells PDL::PP that the first and second dimension of these arguments
821 should have the same size. Otherwise the generated function will raise
822 a runtime error. However, now in an access to $a and $c PDL::PP cannot
823 figure out which index "n" refers to any more just from the name of the
824 index. Therefore, the indices with equal dimension names get numbered
825 from left to right starting at 0, e.g. in the above example "n0" refers
826 to the first dimension of $a and $c, "n1" to the second and so on.
827 In all examples so far, we have only used the "Pars" and "Code" members
829 of the hash that was passed to "pp_def". There are certainly other keys
830 that are recognised by PDL::PP and we will hear about some of them in
831 the course of this document. Find a (non-exhaustive) list of keys in
832 Appendix A. A list of macros and PPfunctions (we have only encountered
833 some of those in the examples above yet) that are expanded in values of
834 the hash argument to "pp_def" is summarised in Appendix B.
835 At this point, it might be appropriate to mention that PDL::PP is not a
837 completely static, well designed set of routines (as Tuomas puts it:
838 "stop thinking of PP as a set of routines carved in stone") but rather
839 a collection of things that the PDL::PP author (Tuomas J. Lukka)
840 considered he would have to write often into his PDL extension
841 routines. PP tries to be expandable so that in the future, as new needs
842 arise, new common code can be abstracted back into it. If you want to
843 learn more on why you might want to change PDL::PP and how to do it
844 check the section on PDL::PP internals.
845 Handling bad values
847 There are several keys and macros used when writing code to handle bad
848 values. The first one is the "HandleBad" key:
849 HandleBad => 0
851 This flags a pp-routine as NOT handling bad values. If this routine
852 is sent ndarrays with their "badflag" set, then a warning message
853 is printed to STDOUT and the ndarrays are processed as if the value
854 used to represent bad values is a valid number. The "badflag" value
855 is not propagated to the output ndarrays.
856 An example of when this is used is for FFT routines, which
858 generally do not have a way of ignoring part of the data.
859 HandleBad => 1
861 This causes PDL::PP to write extra code that ensures the BadCode
862 section is used, and that the $ISBAD() macro (and its brethren)
863 work. If no "BadCode" is supplied, the "Code" section will be used,
864 on the assumption it will use "PDL_IF_BAD" to handle bad values.
865 HandleBad is not given
867 If any of the input ndarrays have their "badflag" set, then the
868 output ndarrays will have their "badflag" set, but any supplied
869 BadCode is ignored.
870 The value of "HandleBad" is used to define the contents of the "BadDoc"
872 key, if it is not given.
873 To handle bad values, code must be written somewhat differently; for
875 instance,
876 $c() = $a() + $b();
878 becomes something like
880 if ( $a() != BADVAL && $b() != BADVAL ) {
882 $c() = $a() + $b();
883 } else {
884 $c() = BADVAL;
885 }
886 However, we only want the second version if bad values are present in
888 the input ndarrays (and that bad-value support is wanted!) - otherwise
889 we actually want the original code. This is where the "BadCode" key
890 comes in; you use it to specify the code to execute if bad values may
891 be present, and PP uses both it and the "Code" section to create
892 something like:
893 if ( bad_values_are_present ) {
895 fancy_broadcastloop_stuff {
896 BadCode
897 }
898 } else {
899 fancy_broadcastloop_stuff {
900 Code
901 }
902 }
903 This approach means that there is virtually no overhead when bad values
905 are not present (i.e. the badflag routine returns 0).
906 The C preprocessor symbol "PDL_BAD_CODE" is defined when the bad code
908 is compiled, so that you can reduce the amount of code you write. The
909 BadCode section can use the same macros and looping constructs as the
910 Code section. As of 2.073, you can also use
911 "PDL_IF_BAD(iftrue,iffalse)".
912 Other bad-value macros
914 However, it wouldn't be much use without the following additional
915 macros:
916 $ISBAD(var)
918 To check whether an ndarray's value is bad, use the $ISBAD macro:
920 if ( $ISBAD(a()) ) { printf("a() is bad\n"); }
922 You can also access given elements of an ndarray:
924 if ( $ISBAD(a(n=>l)) ) { printf("element %d of a() is bad\n", l); }
926 $ISGOOD(var)
928 This is the opposite of the $ISBAD macro.
930 $SETBAD(var)
932 For when you want to set an element of an ndarray bad.
934 $ISBADVAR(c_var,pdl)
936 If you have cached the value of an ndarray $a() into a c-variable
938 ("foo" say), then to check whether it is bad, use "$ISBADVAR(foo,a)".
939 $ISGOODVAR(c_var,pdl)
941 As above, but this time checking that the cached value isn't bad.
943 $SETBADVAR(c_var,pdl)
945 To copy the bad value for an ndarray into a c variable, use
947 "$SETBADVAR(foo,a)".
948 TODO: mention $PPISBAD() etc macros.
950 PDL STATE macros
952 If you want access to the value of the badflag for a given ndarray, you
953 can use the PDL STATE macros, for use in "CopyBadStatusCode" and
954 "FindBadStatusCode".
955 $ISPDLSTATEBAD(pdl)
957 $ISPDLSTATEGOOD(pdl)
958 $SETPDLSTATEBAD(pdl)
959 $SETPDLSTATEGOOD(pdl)
960 And for use in "Code" sections:
962 $PDLSTATEISBAD(pdl)
964 $PDLSTATEISGOOD(pdl)
965 $PDLSTATESETBAD(pdl)
966 $PDLSTATESETGOOD(pdl)
967 Bad-value examples
969 Using these macros, the above code could be specified as:
970 Code => '$c() = $a() + $b();',
972 BadCode => '
973 if ( $ISBAD(a()) || $ISBAD(b()) ) {
974 $SETBAD(c());
975 } else {
976 $c() = $a() + $b();
977 }',
978 Since this is Perl, TMTOWTDI, so you could also write:
980 BadCode => '
982 if ( $ISGOOD(a()) && $ISGOOD(b()) ) {
983 $c() = $a() + $b();
984 } else {
985 $SETBAD(c());
986 }',
987 You can reduce code repetition using the C "PDL_BAD_CODE" macro,
989 supplying only the "Code" section:
990 Code => '
992 #ifdef PDL_BAD_CODE
993 if ( $ISGOOD(a()) && $ISGOOD(b()) ) {
994 #endif PDL_BAD_CODE
995 $c() = $a() + $b();
996 #ifdef PDL_BAD_CODE
997 } else {
998 $SETBAD(c());
999 }
1000 #endif PDL_BAD_CODE
1001 ',
1002 As of 2.073, you can also use "PDL_IF_BAD(iftrue,iffalse)":
1004 Code => '
1006 PDL_IF_BAD(if ( $ISGOOD(a()) && $ISGOOD(b()) ) {,)
1007 $c() = $a() + $b();
1008 PDL_IF_BAD(} else $SETBAD(c());,)
1009 ',
1010 Interfacing your own/library functions using PP
1012 Now, consider the following: you have your own C function (that may in
1013 fact be part of some library you want to interface to PDL) which takes
1014 as arguments two pointers to vectors of double:
1015 void myfunc(int n,double *v1,double *v2);
1017 The correct way of defining the PDL function is
1019 pp_def('myfunc',
1021 Pars => 'a(n); [o]b(n);',
1022 GenericTypes => ['D'],
1023 Code => 'myfunc($SIZE(n),$P(a),$P(b));'
1024 );
1025 The "$P("par")" syntax returns a pointer to the first element and the
1027 other elements are guaranteed to lie after that.
1028 Notice that here it is possible to make many mistakes. First, $SIZE(n)
1030 must be used instead of "n". Second, you shouldn't put any loops in
1031 this code. Third, here we encounter a new hash key recognised by
1032 PDL::PP : the "GenericTypes" declaration tells PDL::PP to ONLY GENERATE
1033 THE TYPELOOP FOP THE LIST OF TYPES SPECIFIED. In this case "double".
1034 This has two advantages. Firstly the size of the compiled code is
1035 reduced vastly, secondly if non-double arguments are passed to myfunc()
1036 PDL will automatically convert them to double before passing to the
1037 external C routine and convert them back afterwards.
1038 One can also use "Pars" to qualify the types of individual arguments.
1040 Thus one could also write this as:
1041 pp_def('myfunc',
1043 Pars => 'double a(n); double [o]b(n);',
1044 Code => 'myfunc($SIZE(n),$P(a),$P(b));'
1045 );
1046 The type specification in "Pars" exempts the argument from variation in
1048 the typeloop - rather it is automatically converted to and from the
1049 type specified. This is obviously useful in a more general example,
1050 e.g.:
1051 void myfunc(int n,float *v1,long *v2);
1053 pp_def('myfunc',
1055 Pars => 'float a(n); long [o]b(n);',
1056 GenericTypes => ['F'],
1057 Code => 'myfunc($SIZE(n),$P(a),$P(b));'
1058 );
1059 Note we still use "GenericTypes" to reduce the size of the type loop,
1061 obviously PP could in principle spot this and do it automatically
1062 though the code has yet to attain that level of sophistication!
1063 Finally note when types are converted automatically one MUST use the
1065 "[o]" qualifier for output variables or you hard-won changes will get
1066 optimised away by PP!
1067 If you interface a large library you can automate the interfacing even
1069 further. Perl can help you again(!) in doing this. In many libraries
1070 you have certain calling conventions. This can be exploited. In short,
1071 you can write a little parser (which is really not difficult in Perl)
1072 that then generates the calls to "pp_def" from parsed descriptions of
1073 the functions in that library. For an example, please check the Slatec
1074 interface in the "Lib" tree of the PDL distribution. If you want to
1075 check (during debugging) which calls to PP functions your Perl code
1076 generated a little helper package comes in handy which replaces the PP
1077 functions by identically named ones that dump their arguments to
1078 stdout.
1079 Just say
1081 perl -MPDL::PP::Dump myfile.pd
1083 to see the calls to "pp_def" and friends. Try it with ops.pd and
1085 slatec.pd. If you're interested (or want to enhance it), the source is
1086 in Basic/Gen/PP/Dump.pm
1087 Other macros in the Code section
1089 Macros: So far we have encountered the $SIZE, $GENERIC and $P macros.
1090 Now we are going to quickly explain the other macros that are expanded
1091 in the "Code" section of PDL::PP along with examples of their usage.
1092 $T
1094 The $T macro is used for type switches. This is very useful when you
1096 have to use different external (e.g. library) functions depending on
1097 the input type of arguments. The general syntax is
1098 $Ttypeletters(type_alternatives)
1100 where "typeletters" is a permutation of a subset of the letters
1102 "BSULNQFDGC" which stand for Byte, Short, Ushort, etc. and
1103 "type_alternatives" are the expansions when the type of the PP
1104 operation is equal to that indicated by the respective letter. Let's
1105 illustrate this incomprehensible description by an example. Assuming
1106 you have two C functions with prototypes
1107 void float_func(float *in, float *out);
1109 void double_func(double *in, double *out);
1110 which do basically the same thing but one accepts float and the other
1112 double pointers. You could interface them to PDL by defining a generic
1113 function "foofunc" (which will call the correct function depending on
1114 the type of the transformation):
1115 pp_def('foofunc',
1117 Pars => ' a(n); [o] b();',
1118 Code => ' $TFD(float,double)_func ($P(a),$P(b));'
1119 GenericTypes => [qw(F D)],
1120 );
1121 There is a limitation that the comma-separated values cannot have
1123 parentheses.
1124 $PP
1126 The $PP macro is used for a so called physical pointer access. The
1128 physical refers to some internal optimisations of PDL (for those who
1129 are familiar with the PDL core we are talking about the vaffine
1130 optimisations). This macro is mainly for internal use and you shouldn't
1131 need to use it in any of your normal code.
1132 $PPSYM
1134 The $PPSYM() macro is replaced by the value of "ppsym" in PDL::Types
1136 for the loop type, or that of the given parameter, similar to
1137 $GENERIC(). This is useful for e.g. macros that vary by that, avoiding
1138 the need for things like "$TXY(X,Y)". Another benefit is that if an
1139 operation's GenericTypes get extended, this macro will still be
1140 correct.
1141 $COMP (and the OtherPars section)
1143 The $COMP macro is used to access non-pdl values in the code section.
1145 Its name is derived from the implementation of transformations in PDL.
1146 The variables you can refer to using $COMP are members of the
1147 ``compiled'' structure that represents the PDL transformation in
1148 question but does not yet contain any information about dimensions (for
1149 further details check PDL::Internals). However, you can treat $COMP
1150 just as a black box without knowing anything about the implementation
1151 of transformations in PDL. So when would you use this macro? Its main
1152 usage is to access values of arguments that are declared in the
1153 "OtherPars" section of a "pp_def" definition. But then you haven't
1154 heard about the "OtherPars" key yet?! Let's have another example that
1155 illustrates typical usage of both new features:
1156 pp_def('pnmout',
1158 Pars => 'a(m)',
1159 OtherPars => "PerlIO *fp",
1160 GenericTypes => [qw(B U S L)],
1161 Code => '
1162 if (PerlIO_write($COMP(fp),$P(a),len) != len)
1163 $CROAK("Error writing pnm file");
1164 ');
1165 This function is used to write data from a pdl to a file. The file
1167 descriptor is passed as a string into this function. This parameter
1168 does not go into the "Pars" section since it cannot be usefully treated
1169 like a pdl but rather into the aptly named "OtherPars" section.
1170 Parameters in the "OtherPars" section follow those in the "Pars"
1171 section when invoking the function, i.e.
1172 open FILE,">out.dat" or die "couldn't open out.dat";
1174 pnmout($pdl,'FILE');
1175 When you want to access this parameter inside the code section you have
1177 to tell PP by using the $COMP macro, i.e. you write $COMP(fp) as in the
1178 example. Otherwise PP wouldn't know that the "fp" you are referring to
1179 is the same as that specified in the "OtherPars" section.
1180 Another use for the "OtherPars" section is to set a named dimension in
1182 the signature. Let's have an example how that is done:
1183 pp_def('setdim',
1185 Pars => '[o] a(n)',
1186 OtherPars => 'int ns => n',
1187 Code => 'loop(n) %{ $a() = n; %}',
1188 );
1189 This says that the named dimension "n" will be initialised from the
1191 value of the other parameter "ns" which is of integer type (I guess you
1192 have realised that we use the "CType From => named_dim" syntax). As of
1193 2.082, this can be used to set the size of a dimension not used in any
1194 "Pars". Now you can call this function in the usual way:
1195 setdim(($x=null),5);
1197 print $x;
1198 [ 0 1 2 3 4 ]
1199 Admittedly this function is not very useful but it demonstrates how it
1201 works. If you call the function with an existing pdl and you don't need
1202 to explicitly specify the size of "n" since PDL::PP can figure it out
1203 from the dimensions of the non-null pdl. In that case you just give the
1204 dimension parameter as -1:
1205 $x = hist($y);
1207 setdim($x,-1);
1208 The default values available via $COMP() are the "OtherPars" as noted
1210 above, which get copied in. However, this can be added to (previous to
1211 2.058, replaced) by supplying "Comp" and/or "MakeComp" keys (the
1212 defaults will happen first):
1213 pp_def(
1215 'diagonal',
1216 OtherPars => 'SV *list',
1217 Comp => 'PDL_Indx whichdims_count; PDL_Indx whichdims[$COMP(whichdims_count)];',
1218 MakeComp => '
1219 PDL_Indx i;
1220 PDL_Indx *tmp= PDL->packdims(list,&($COMP(whichdims_count)));
1221 if (!tmp) $CROAK("Failed to packdims for creating");
1222 if ($COMP(whichdims_count) < 1)
1223 $CROAK("Diagonal: must have at least 1 dimension");
1224 $DOCOMPALLOC(); /* malloc()s the whichdims */
1225 for(i=0; i<$COMP(whichdims_count); i++)
1226 $COMP(whichdims)[i] = tmp[i];
1227 free(tmp);
1228 /* ... */
1229 ',
1230 # ...
1231 );
1232 The "MakeComp" code is placed in the pdl_run_(funcname), so access to
1234 "Pars" (which will just be "pdl *"s)/"OtherPars" values is just via
1235 their names, not a macro. The default code (which also applies to
1236 "OtherPars") makes a copy of values where it knows how to do so,
1237 including "SV*" and "char*".
1238 You can also provide a "CompFreeCodeComp" key, in case your "MakeComp"
1240 needs tidying up after it.
1241 As of 2.058, you can instead give a C99 "incomplete array" type
1243 parameter as an "OtherPars" entry:
1244 pp_def(
1246 'diagonal',
1247 OtherPars => 'PDL_Indx whichdims[]',
1248 MakeComp => '
1249 if ($COMP(whichdims_count) < 1)
1250 $CROAK("Diagonal: must have at least 1 dimension");
1251 /* ... */
1252 ',
1253 # ...
1254 );
1255 There is an XS typemap entry (for "PDL_Indx" and "pdl*" array types for
1257 now) that relies on a "(varname)_count" variable being declared in the
1258 XS "INPUT" section (PP does this for you), to extract the index numbers
1259 from an array-ref parameter, and sets the count variable to the right
1260 value. PP then makes a copy of the data available. The C function
1261 (here, "pdl_run_diagonal")'s caller (here, the generated XS function)
1262 is responsible for freeing the array passed in (here, PDL's "smalloc"
1263 function is used, so the user need do nothing different).
1264 XS-only OtherPars
1266 As of 2.083, you can prefix the names of "OtherPars" with "$", e.g.
1268 pp_def('minus',
1270 OtherPars => 'int $swap',
1271 # ...
1272 );
1273 This will mean they are available in "HdrCode" and "FtrCode", but not
1275 elsewhere in the generated code (e.g. "MakeComp", "Code").
1276 Other functions in the Code section
1278 The only PP function that we have used in the examples so far is
1279 "loop". Additionally, there are currently two other functions which
1280 are recognised in the "Code" section:
1281 broadcastloop
1283 As we heard above the signature of a PP defined function defines the
1285 dimensions of all the pdl arguments involved in a primitive operation.
1286 However, you often call the functions that you defined with PP with
1287 pdls that have more dimensions than those specified in the signature.
1288 In this case the primitive operation is performed on all subslices of
1289 appropriate dimensionality in what is called a broadcast loop (see also
1290 overview above and PDL::Indexing). Assuming you have some notion of
1291 this concept you will probably appreciate that the operation specified
1292 in the code section should be optimised since this is the tightest loop
1293 inside a broadcast loop. However, if you revisit the example where we
1294 define the "pnmout" function, you will quickly realise that looking up
1295 the "IO" file descriptor in the inner broadcast loop is not very
1296 efficient when writing a pdl with many rows. A better approach would be
1297 to look up the "IO" descriptor once outside the broadcast loop and use
1298 its value then inside the tightest broadcast loop. This is exactly
1299 where the "broadcastloop" function comes in handy. Here is an improved
1300 definition of "pnmout" which uses this function:
1301 pp_def('pnmout',
1303 Pars => 'a(m)',
1304 OtherPars => "PerlIO *fp",
1305 GenericTypes => [qw(B U S L)],
1306 Code => '
1307 int len;
1308 len = $SIZE(m) * sizeof($GENERIC());
1309 broadcastloop %{
1310 if (PerlIO_write($COMP(fp),$P(a),len) != len)
1311 $CROAK("Error writing pnm file");
1312 %}
1313 ');
1314 This works as follows. Normally the C code you write inside the "Code"
1316 section is placed inside a broadcast loop (i.e. PP generates the
1317 appropriate wrapping C code around it). However, when you explicitly
1318 use the "broadcastloop" function, PDL::PP recognises this and doesn't
1319 wrap your code with an additional broadcast loop. This has the effect
1320 that code you write outside the broadcast loop is only executed once
1321 per transformation and just the code with in the surrounding "%{ ...
1322 %}" pair is placed within the tightest broadcast loop. This also comes
1323 in handy when you want to perform a decision (or any other code,
1324 especially CPU intensive code) only once per thread, i.e.
1325 pp_addhdr('
1327 #define RAW 0
1328 #define ASCII 1
1329 ');
1330 pp_def('do_raworascii',
1331 Pars => 'a(); b(); [o]c()',
1332 OtherPars => 'int mode',
1333 Code => ' switch ($COMP(mode)) {
1334 case RAW:
1335 broadcastloop %{
1336 /* do raw stuff */
1337 %}
1338 break;
1339 case ASCII:
1340 broadcastloop %{
1341 /* do ASCII stuff */
1342 %}
1343 break;
1344 default:
1345 $CROAK("unknown mode");
1346 }'
1347 );
1348 types
1350 The types function works similar to the $T macro. However, with the
1352 "types" function the code in the following block (delimited by "%{" and
1353 "%}" as usual) is executed for all those cases in which the datatype of
1354 the operation is any of the types represented by the letters in the
1355 argument to "type", e.g.
1356 Code => '...
1358 types(BSUL) %{
1360 /* do integer type operation */
1361 %}
1362 types(FD) %{
1363 /* do floating point operation */
1364 %}
1365 ...'
1366 You are encouraged to use this idiom (from PDL::Math) in order to
1368 minimise effort needed to make your code work with new types:
1369 use PDL::Types qw(types);
1371 my @Rtypes = grep $_->real, types();
1372 my @Ctypes = grep !$_->real, types();
1373 # ...
1374 my $got_complex = PDL::Core::Dev::got_complex_version($name, 2);
1375 my $complex_bit = join "\n",
1376 map 'types('.$_->ppsym.') %{$'.$c.'() = c'.$name.$_->floatsuffix.'($'.$x.'(),$'.$y.'());%}',
1377 @Ctypes;
1378 my $real_bit = join "\n",
1379 map 'types('.$_->ppsym.') %{$'.$c.'() = '.$name.'($'.$x.'(),$'.$y.'());%}',
1380 @Rtypes;
1381 ($got_complex ? $complex_bit : '') . $real_bit;
1382 (although you should first check whether tgmath.h already has a type-
1384 generic version of the function you want to call, in which case the
1385 above becomes unnecessary).
1386 The RedoDimsCode Section
1388 The "RedoDimsCode" key is an optional key that is used to compute
1389 dimensions of ndarrays at runtime in case the standard rules for
1390 computing dimensions from the signature are not sufficient. The
1391 contents of the "RedoDimsCode" entry is interpreted in the same way
1392 that the Code section is interpreted-- i.e., PP macros are expanded and
1393 the result is interpreted as C code. The purpose of the code is to set
1394 the size of some dimensions that appear in the signature. Storage
1395 allocation and broadcastloops and so forth will be set up as if the
1396 computed dimension had appeared in the signature. In your code, you
1397 first compute the desired size of a named dimension in the signature
1398 according to your needs and then assign that value to it via the
1399 $SIZE() macro.
1400 As an example, consider the following situation. You are interfacing an
1402 external library routine that requires an temporary array for workspace
1403 to be passed as an argument. Two input data arrays that are passed are
1404 p(m) and x(n). The output data array is y(n). The routine requires a
1405 workspace array with a length of n+m*m, and you'd like the storage
1406 created automatically just like it would be for any ndarray flagged
1407 with [t] or [o]. What you'd like is to say something like
1408 pp_def( "myexternalfunc",
1410 Pars => " p(m); x(n); [o] y; [t] work(n+m*m); ", ...
1411 but that won't work, because PP can't interpret expressions with
1413 arithmetic in the signature. Instead you write
1414 pp_def(
1416 "myexternalfunc",
1417 Pars => ' p(m); x(n); [o] y(); [t] work(wn); ',
1418 RedoDimsCode => '$SIZE(wn) = $SIZE(n) + $SIZE(m) * $SIZE(m);',
1419 Code => '
1420 externalfunc( $P(p), $P(x), $SIZE(m), $SIZE(n), $P(work) );
1421 '
1422 );
1423 As of 2.075, you can use the dimensions of passed-in ndarrays as they
1425 are available when the "RedoDimsCode" is run. Before the code in the
1426 Code section is executed PP will create the proper storage for "work"
1427 (one area per POSIX thread, in case of broadcasting that multi-threads
1428 - the user cannot supply this). Note that you only took the first
1429 dimension of "p" and "x" because the user may have sent ndarrays with
1430 extra broadcasting dimensions.
1431 You can also use "RedoDimsCode" to set the dimension of a ndarray
1433 flagged with [o]. In this case you set the dimensions for the named
1434 dimension in the signature using $SIZE() as in the preceding example.
1435 However, because the ndarray is flagged with [o] instead of [t],
1436 broadcasting dimensions will be added if required just as if the size
1437 of the dimension were computed from the signature according to the
1438 usual rules. Here is an example from PDL::Math
1439 pp_def("polyroots",
1441 Pars => 'cr(n); ci(n); [o]rr(m); [o]ri(m);',
1442 RedoDimsCode => '$SIZE(m) = $SIZE(n)-1;',
1443 The input ndarrays are the real and imaginary parts of complex
1445 coefficients of a polynomial. The output ndarrays are real and
1446 imaginary parts of the roots. There are "n" roots to an "n"th order
1447 polynomial and such a polynomial has "n+1" coefficients (the zero-th
1448 through the "n"th). In this example, broadcasting will work correctly.
1449 That is, the first dimension of the output ndarray with have its
1450 dimension adjusted, but other broadcasting dimensions will be assigned
1451 just as if there were no "RedoDimsCode".
1452 RedoDims passed directly
1454 A "RedoDimsCode" value as above gets processed, including expanding
1456 macros, and adding type-generic loops. For very specific purposes, you
1457 may not want this processing done to your dimension-updating code,
1458 probably in "slice"-like functions.
1459 Then, instead of passing a "RedoDimsCode" value, you can pass a
1461 "RedoDims" value (which the "RedoDimsCode" would otherwise get
1462 processed into). Because you will probably want to access the ndarrays,
1463 the following macros are provided. They are named assuming you will
1464 have the first parameter as "PARENT" and the second as "CHILD", which
1465 is the case if you passed a true "P2Child" value, which you will
1466 basically always want to do for this scenario.
1467 RedoDims generated from EquivPDimExpr and EquivDimCheck
1469 Another way to generate the "RedoDims" code is to supply a
1471 "EquivPDimExpr" and maybe a "EquivDimCheck":
1472 pp_def(
1474 'xchg',
1475 OtherPars => 'PDL_Indx n1; PDL_Indx n2;',
1476 TwoWay => 1,
1477 P2Child => 1,
1478 AffinePriv => 1,
1479 EquivDimCheck => '
1480 if ($COMP(n1) <0) $COMP(n1) += $PARENT(broadcastids[0]);
1481 if ($COMP(n2) <0) $COMP(n2) += $PARENT(broadcastids[0]);
1482 if (PDLMIN($COMP(n1),$COMP(n2)) <0 ||
1483 PDLMAX($COMP(n1),$COMP(n2)) >= $PARENT(broadcastids[0]))
1484 $CROAK("One of dims %d, %d out of range: should be 0<=dim<%d",
1485 $COMP(n1),$COMP(n2),$PARENT(broadcastids[0]));',
1486 EquivPDimExpr => '
1487 (($CDIM == $COMP(n1)) ? $COMP(n2) :
1488 ($CDIM == $COMP(n2)) ? $COMP(n1) :
1489 $CDIM)
1490 ',
1491 );
1492 "EquivPDimExpr" is evaluated within a loop, and the value of the
1494 relevant dimension is available using the macro $CDIM as shown above.
1495 Typemap handling in the OtherPars section
1497 The "OtherPars" section discussed above is very often absolutely
1498 crucial when you interface external libraries with PDL. However in many
1499 cases the external libraries either use derived types or pointers of
1500 various types.
1501 The standard way to handle this in Perl is to use a typemap file. This
1503 is discussed in some detail in perlxs in the standard Perl
1504 documentation. In PP the functionality is very similar, so you can
1505 create a typemap file in the directory where your PP file resides and
1506 when it is built it is automatically read in to figure out the
1507 appropriate translation between the C type and Perl's built-in type.
1508 For instance the "gsl_spline_init" function has the following C
1510 declaration:
1511 int gsl_spline_init(gsl_spline * spline,
1513 const double xa[], const double ya[], size_t size);
1514 Clearly the "xa" and "ya" arrays are candidates for being passed in as
1516 ndarrays and the "size" argument is just the length of these ndarrays
1517 so that can be handled by the $SIZE() macro in PP. Write an
1518 "OtherPars" declaration of the form
1519 OtherPars => 'gsl_spline *spl'
1521 and write a short typemap file which handles this type:
1523 TYPEMAP
1525 gsl_spline * T_PTR
1526 and use it in the code:
1528 pp_def('init_meat',
1530 Pars => 'double x(n); double y(n);',
1531 OtherPars => 'gsl_spline *spl',
1532 Code =>'gsl_spline_init,($COMP(spl),$P(x),$P(y),$SIZE(n)));'
1533 );
1534 where I have removed a macro wrapper call, but that would obscure the
1536 discussion.
1537 You can also have "OtherPars" entries that are "incomplete arrays" of
1539 "pdl*", both for input and output:
1540 OtherPars => 'pdl *ins[]', # $COMP(ins_count) will be available
1542 # OR
1543 OtherPars => '[o] pdl *outs[]', # update $COMP(outs_count) in your code
1544 Note that the output typemap entry does a "free" on the array of "pdl*"
1546 pointers, so ensure that you "malloc" it in your code, without leaking.
1547 OtherPars as outputs
1549 As of 2.081, you can specify an "OtherPar" as an output. This looks
1551 like:
1552 pp_def('output_op',
1554 Pars => 'in(n=2)',
1555 OtherPars => '[o] PDL_Anyval v0; [o] PDL_Anyval v1',
1556 Code => '
1557 pdl_datatypes dt = $PDL(in)->datatype;
1558 ANYVAL_FROM_CTYPE($COMP(v0), dt, $in(n=>0));
1559 ANYVAL_FROM_CTYPE($COMP(v1), dt, $in(n=>1));
1560 ',
1561 );
1562 The passed-in stack SV will be mutated in place, so this code will then
1564 work:
1565 output_op([5,7], my $v0, my $v1);
1567 is_deeply [$v0,$v1], [5,7], 'output OtherPars work';
1568 ($v0, $v1) = output_op([5,7]); # you can omit them, then they get returned
1569 is_deeply [$v0,$v1], [5,7], 'output OtherPars work 1a';
1570 An operation with output "OtherPars" cannot broadcast, since that would
1572 cause undefined results. A runtime check is generated that throws an
1573 exception if any "Par" would cause broadcasting.
1574 Note the syntax for "OtherPars" has "[o]" go before the type, while it
1576 goes after the type in "Pars". It was felt this was the best way to
1577 avoid ambiguity given C types can have "[]" in them.
1578 This relies on the relevant "OtherPar" having an "OUTPUT" entry in an
1580 XS typemap.
1581 As of 2.083, it is also possible to specify "OtherPars" as "[io]",
1583 which means they must be supplied (rather than being optional, like an
1584 "[o]" one), but will still be updated after the operation has finished.
1585 Other useful PP keys in data operation definitions
1587 You have already heard about the "OtherPars" key. Currently, there are
1588 not many other keys for a data operation that will be useful in normal
1589 (whatever that is) PP programming. In fact, it would be interesting to
1590 hear about a case where you think you need more than what is provided
1591 at the moment. Please speak up on one of the PDL mailing lists. Most
1592 other keys recognised by "pp_def" are only really useful for what we
1593 call slice operations (see also above).
1594 One thing that is strongly being planned is variable number of
1596 arguments, which will be a little tricky.
1597 An incomplete list of the available keys:
1599 Inplace
1601 Setting this key marks the routine as working inplace - ie the input
1603 and output ndarrays are the same. An example is "$x->inplace->sqrt()"
1604 (or "sqrt(inplace($x))").
1605 Inplace => 1
1607 Use when the routine is a unary function, such as "sqrt".
1608 Inplace => ['a']
1610 If there are more than one input ndarrays, specify the name of the
1611 one that can be changed inplace using an array reference.
1612 Inplace => ['a','b']
1614 If there are more than one output ndarray, specify the name of the
1615 input ndarray and output ndarray in a 2-element array reference.
1616 This probably isn't needed, but left in for completeness.
1617 If bad values are being used, care must be taken to ensure the
1619 propagation of the badflag when inplace is being used; consider this
1620 excerpt from Basic/Bad/bad.pd:
1621 pp_def('setbadtoval',HandleBad => 1,
1623 Pars => 'a(); [o]b();',
1624 OtherPars => 'double newval',
1625 Inplace => 1,
1626 CopyBadStatusCode => 'PDL->propagate_badflag( b, 0 );',
1627 ...
1628 Since this routine removes all bad values, the output ndarray had its
1630 bad flag cleared. This is then propagated to both parents and children.
1631 NOTE: one idea is that the documentation for the routine could be
1633 automatically flagged to indicate that it can be executed inplace, ie
1634 something similar to how "HandleBad" sets "BadDoc" if it's not supplied
1635 (it's not an ideal solution).
1636 FTypes
1638 # in slices.pd
1640 FTypes => {CHILD => '$COMP(totype)'},
1641 The value is a hash-ref mapping parameter-names to an expression giving
1643 an override of the type for that parameter. The example above shows the
1644 type being overridden to the "OtherPars" "totype".
1645 OtherParsDefaults
1647 OtherPars => 'int a; int b',
1649 OtherParsDefaults => { b => 0 },
1650 Allows specifying default values for "OtherPars". It is an error to
1652 specify a default for one that is before another that does not have a
1653 default.
1654 ArgOrder
1656 Pars => 'x(); y(); [o]z()'
1658 OtherPars => 'int a; int b',
1659 ArgOrder => [qw(x y a b z)],
1660 # or, a non-reference true value to enable flexible arg-handling and
1662 # move defaultable to the end, followed by output ndarrays then OtherPars
1663 Pars => 'x(); y(); [o]z()'
1664 OtherPars => 'int a; int b',
1665 ArgOrder => 1,
1666 Allows specifying a different order for providing the operation's
1668 arguments. This affects only the generated XS (not C pdl_run_(name))
1669 parameter list; the internal ordering of "pdl*" in various C arrays is
1670 unaffected.
1671 Providing a non-reference true value enables flexible argument-handling
1673 and moves defaultable to the end, followed by output ndarrays then
1674 output "OtherPars". Also, all outputs (ndarray and "OtherPars") will be
1675 returned on the stack, even if supplied as arguments.
1676 It is an error to specify arguments that are not provided, or to give a
1678 false value, or to have "optional" arguments after mandatory ones.
1679 XS argument-handling change
1681 This also changes PP's XS argument handling; normally you can specify:
1683 • just the input/io arguments
1685 • (if the operation has default values provided) those plus values
1687 for all arguments with defaults
1688 • all of those plus output arguments, in other words all non-"[t]"
1690 arguments
1691 With "ArgOrder" given, "optional" arguments (outputs and ones with
1693 defaults) will be filled in from the leftmost missing one.
1694 HdrCode
1696 This is C code that is inserted in the XS function before the call to
1698 the generated pdl_run_(funcname). It will have access to all the Pars
1699 and OtherPars as C values.
1700 FtrCode
1702 As of 2.083. This is C code that is inserted in the XS function after
1704 the call to the generated pdl_run_(funcname). It will have access to
1705 all the Pars and OtherPars as C values.
1706 Other PDL::PP functions to support concise package definition
1708 So far, we have described the "pp_def" and "pp_done" functions. PDL::PP
1709 exports a few other functions to aid you in writing concise PDL
1710 extension package definitions.
1711 pp_addhdr
1713 Often when you interface library functions as in the above example you
1715 have to include additional C include files. Since the XS file is
1716 generated by PP we need some means to make PP insert the appropriate
1717 include directives in the right place into the generated XS file. To
1718 this end there is the "pp_addhdr" function. This is also the function
1719 to use when you want to define some C functions for internal use by
1720 some of the XS functions (which are mostly functions defined by
1721 "pp_def"). By including these functions here you make sure that
1722 PDL::PP inserts your code before the point where the actual XS module
1723 section begins and will therefore be left untouched by xsubpp (cf.
1724 perlxs and perlxstut man pages).
1725 A typical call would be
1727 pp_addhdr('
1729 #include <unistd.h> /* we need defs of XXXX */
1730 #include "libprotos.h" /* prototypes of library functions */
1731 #include "mylocaldecs.h" /* Local decs */
1732 static void do_the real_work(PDL_Byte * in, PDL_Byte * out, int n)
1734 {
1735 /* do some calculations with the data */
1736 }
1737 ');
1738 This ensures that all the constants and prototypes you need will be
1740 properly included and that you can use the internal functions defined
1741 here in the "pp_def"s, e.g.:
1742 pp_def('barfoo',
1744 Pars => ' a(n); [o] b(n)',
1745 GenericTypes => ['B'],
1746 Code => ' PDL_Indx ns = $SIZE(n);
1747 do_the_real_work($P(a),$P(b),ns);
1748 ',
1749 );
1750 pp_addpm
1752 In many cases the actual PP code (meaning the arguments to "pp_def"
1754 calls) is only part of the package you are currently implementing.
1755 Often there is additional Perl code and XS code you would normally have
1756 written into the pm and XS files which are now automatically generated
1757 by PP. So how to get this stuff into those dynamically generated files?
1758 Fortunately, there are a couple of functions, generally called
1759 "pp_addXXX" that assist you in doing this.
1760 Let's assume you have additional Perl code that should go into the
1762 generated pm-file. This is easily achieved with the "pp_addpm" command:
1763 pp_addpm(<<'EOD');
1765 =head1 NAME
1767 PDL::Lib::Mylib -- a PDL interface to the Mylib library
1769 =head1 DESCRIPTION
1771 This package implements an interface to the Mylib package with full
1773 broadcasting and indexing support (see L<PDL::Indexing>).
1774 =cut
1776 use PGPLOT;
1778 =head2 use_myfunc
1780 this function applies the myfunc operation to all the
1781 elements of the input pdl regardless of dimensions
1782 and returns the sum of the result
1783 =cut
1784 sub use_myfunc {
1786 my $pdl = shift;
1787 myfunc($pdl->clump(-1),($res=null));
1789 return $res->sum;
1791 }
1792 EOD
1794 pp_add_exported
1796 You have probably got the idea. In some cases you also want to export
1798 your additional functions. To avoid getting into trouble with PP which
1799 also messes around with the @EXPORT array you just tell PP to add your
1800 functions to the list of exported functions:
1801 pp_add_exported('use_myfunc gethynx');
1803 pp_add_isa
1805 The "pp_add_isa" command works like the the "pp_add_exported" function.
1807 The arguments to "pp_add_isa" are added the @ISA list, e.g.
1808 pp_add_isa(' Some::Other::Class ');
1810 pp_bless
1812 If your pp_def routines are to be used as object methods use "pp_bless"
1814 to specify the package (i.e. class) to which your pp_defed methods will
1815 be added. For example, pp_bless('PDL::MyClass'). The default is "PDL"
1816 if this is omitted.
1817 The value given here (or the default, "PDL"), anywhere in the .pd file,
1819 will be the package into which all PP operations get added, even for
1820 operations whose "pp_def" was called before the "pp_bless". This is
1821 because that package is inserted at the start of the generated XS code
1822 by "pp_done". The only way this changes is if "pp_addxs" is called,
1823 which will add the given code (or none if an empty string is given) to
1824 the $::PDLPACK package, and then changes the package to the pp_bless
1825 value. For historical reasons, this cannot be changed. So, to have
1826 several different packages in one .pd file, do something like this:
1827 # any pp_def up till now will get put in PDL::Pack2
1829 pp_bless('PDL::Pack1');
1830 pp_addxs('');
1831 pp_def('func1', ...);
1832 pp_bless('PDL::Pack2');
1833 pp_addxs('');
1834 pp_def('otherfunc', ...);
1835 pp_addxs
1837 Sometimes you want to add extra XS code of your own (that is generally
1839 not involved with any broadcasting/indexing issues but supplies some
1840 other functionality you want to access from the Perl side) to the
1841 generated XS file, for example
1842 pp_addxs('','
1844 # Determine endianness of machine
1846 int
1848 isbigendian()
1849 CODE:
1850 unsigned short i;
1851 PDL_Byte *b;
1852 i = 42; b = (PDL_Byte*) (void*) &i;
1854 if (*b == 42)
1856 RETVAL = 0;
1857 else if (*(b+1) == 42)
1858 RETVAL = 1;
1859 else
1860 croak("Impossible - machine is neither big nor little endian!!\n");
1861 OUTPUT:
1862 RETVAL
1863 ');
1864 Especially "pp_add_exported" and "pp_addxs" should be used with care.
1866 PP uses PDL::Exporter, hence letting PP export your function means that
1867 they get added to the standard list of function exported by default
1868 (the list defined by the export tag ``:Func''). If you use "pp_addxs"
1869 you shouldn't try to do anything that involves broadcasting or indexing
1870 directly. PP is much better at generating the appropriate code from
1871 your definitions.
1872 pp_add_boot
1874 Finally, you may want to add some code to the BOOT section of the XS
1876 file (if you don't know what that is check perlxs). This is easily done
1877 with the "pp_add_boot" command:
1878 pp_add_boot(<<EOB);
1880 descrip = mylib_initialize(KEEP_OPEN);
1881 if (descrip == NULL)
1883 croak("Can't initialize library");
1884 GlobalStruc->descrip = descrip;
1886 GlobalStruc->maxfiles = 200;
1887 EOB
1888 pp_export_nothing
1890 By default, PP.pm puts all subs defined using the pp_def function into
1892 the output .pm file's EXPORT list. This can create problems if you are
1893 creating a subclassed object where you don't want any methods exported.
1894 (i.e. the methods will only be called using the $object->method
1895 syntax).
1896 For these cases you can call pp_export_nothing() to clear out the
1898 export list. Example (At the end of the .pd file):
1899 pp_export_nothing();
1901 pp_done();
1902 pp_core_importList
1904 By default, PP.pm puts the 'use Core;' line into the output .pm file.
1906 This imports Core's exported names into the current namespace, which
1907 can create problems if you are over-riding one of Core's methods in the
1908 current file. You end up getting messages like "Warning: sub sumover
1909 redefined in file subclass.pm" when running the program.
1910 For these cases the pp_core_importList can be used to change what is
1912 imported from Core.pm. For example:
1913 pp_core_importList('()')
1915 This would result in
1917 use Core();
1919 being generated in the output .pm file. This would result in no names
1921 being imported from Core.pm. Similarly, calling
1922 pp_core_importList(' qw/ barf /')
1924 would result in
1926 use Core qw/ barf/;
1928 being generated in the output .pm file. This would result in just
1930 'barf' being imported from Core.pm.
1931 pp_setversion
1933 Simultaneously set the .pm and .xs files' versions, thus avoiding
1935 unnecessary version-skew between the two. To use this, simply do this
1936 in your .pd file, probably near the top:
1937 our $VERSION = '0.0.3';
1939 pp_setversion($VERSION);
1940 # Then, in your Makefile.PL:
1942 my @package = qw(FFTW3.pd FFTW3 PDL::FFTW3);
1943 my %descriptor = pdlpp_stdargs(\@package);
1944 $descriptor{VERSION_FROM} = 'FFTW3.pd'; # EUMM can parse the format above
1945 However, don't use this if you use Module::Build::PDL. See that
1947 module's documentation for details.
1948 pp_deprecate_module
1950 If a particular module is deemed obsolete, this function can be used to
1952 mark it as deprecated. This has the effect of emitting a warning when a
1953 user tries to "use" the module. The generated POD for this module also
1954 carries a deprecation notice. The replacement module can be passed as
1955 an argument like this:
1956 pp_deprecate_module( infavor => "PDL::NewNonDeprecatedModule" );
1958 Note that function affects only the runtime warning and the POD.
1960
1962 Let's say that you have a function in your module called PDL::foo that
1963 uses the PP function "bar_pp" to do the heavy lifting. But you don't
1964 want to advertise that "bar_pp" exists. To do this, you must move your
1965 PP function to the top of your module file, then call
1966 pp_export_nothing()
1968 to clear the "EXPORT" list. To ensure that no documentation (even the
1970 default PP docs) is generated, set
1971 Doc => undef
1973 and to prevent the function from being added to the symbol table, set
1975 PMFunc => ''
1977 in your pp_def declaration (see Image2D.pd for an example). This will
1979 effectively make your PP function "private." However, it is always
1980 accessible via PDL::bar_pp due to Perl's module design. But making it
1981 private will cause the user to go very far out of their way to use it,
1982 so they shoulder the consequences!
1983
1985 The slice operations require a much more intimate knowledge of PDL
1986 internals than the data operations. Furthermore, the complexity of the
1987 issues involved is considerably higher than that in the average data
1988 operation. Nevertheless, functions generated using the slice operations
1989 are at the heart of the index manipulation and dataflow capabilities of
1990 PDL. You can get started by reading the section on "P2Child".
1991 Also, there are a lot of dirty issues with virtual ndarrays and
1993 vaffines which we shall entirely skip here.
1994 Slices and bad values
1996 Slice operations need to be able to handle bad values. The easiest
1997 thing to do is look at Basic/Slices/slices.pd to see how this works.
1998 Along with "BadCode", there are also the "BadBackCode" and
2000 "BadRedoDimsCode" keys for "pp_def". However, any "EquivCPOffsCode"
2001 should not need changing, since any changes are absorbed into the
2002 definition of the $EQUIVCPOFFS() macro (i.e. it is handled
2003 automatically by PDL::PP).
2004
2006 For printing warning messages or aborting/dieing, you can call "warn"
2007 or "barf" from PP code. However, you should be aware that these calls
2008 have been redefined using C preprocessor macros to "PDL->barf" and
2009 "PDL->warn". These redefinitions are in place to keep you from
2010 inadvertently calling perl's "warn" or "barf" directly, which can cause
2011 segfaults during pthreading (i.e. processor multi-threading).
2012 PDL's own versions of "barf" and "warn" will queue-up warning or barf
2014 messages until after pthreading is completed, and then call the perl
2015 versions of these routines.
2016 See PDL::ParallelCPU for more information on pthreading.
2018 NB As of 2.064, it is highly recommended that you do not call "barf" at
2020 all in PP code, but instead use $CROAK(). This will return a
2021 "pdl_error" which will transparently be used to throw the correct
2022 exception in Perl code, but can be handled suitably by non-Perl
2023 callers.
2024
2026 If you are going to generate a package from your PP file (typical file
2027 extensions are ".pd" or ".pp" for the files containing PP code) it is
2028 easiest and safest to leave generation of the appropriate commands to
2029 the Makefile. In the following we will outline the typical format of a
2030 Perl Makefile to automatically build and install your package from a
2031 description in a PP file. Most of the rules to build the xs, pm and
2032 other required files from the PP file are already predefined in the
2033 PDL::Core::Dev package. We just have to tell MakeMaker to use it.
2034 In most cases you can define your Makefile like
2036 use PDL::Core::Dev; # Pick up development utilities
2038 use ExtUtils::MakeMaker;
2039 $package = ["mylib.pd",Mylib,PDL::Lib::Mylib,'',1];
2041 %hash = pdlpp_stdargs($package);
2042 $hash{OBJECT} .= ' additional_Ccode$(OBJ_EXT) ';
2043 WriteMakefile(%hash);
2044 sub MY::postamble { pdlpp_postamble($package); }
2046 # additional_Ccode.c
2048 #include "pdl.h"
2049 void ppcp(PDL_Byte *dst, PDL_Byte *src, int len)
2050 {
2051 int i;
2052 for (i=0;i<len;i++) *dst++=*src++;
2053 }
2054 Here, the list in $package is: first: PP source file name, then the
2056 prefix for the produced files, the whole package name, the package to
2057 add XS functions to (empty string to use the same as the PP functions),
2058 and a boolean to dictate whether to have PDL generate a separate C file
2059 for each PP function (for faster compilation). The last feature is
2060 opt-in as you have to avoid duplicate symbols when linking the library
2061 (so separate out C functions into their own file). You can modify the
2062 hash in whatever way you like but it would be reasonable to stay within
2063 some limits so that your package will continue to work with later
2064 versions of PDL.
2065 To make life even easier PDL::Core::Dev defines the function
2067 "pdlpp_stdargs" that returns a hash with default values that can be
2068 passed (either directly or after appropriate modification) to a call to
2069 WriteMakefile. Currently, "pdlpp_stdargs" returns a hash where the
2070 keys are filled in as follows:
2071 (
2073 'NAME' => $mod,
2074 VERSION_FROM => $src,
2075 'TYPEMAPS' => [&PDL_TYPEMAP()],
2076 'OBJECT' => "$pref\$(OBJ_EXT)",
2077 PM => {"$pref.pm" => "\$(INST_LIBDIR)/$pref.pm"},
2078 MAN3PODS => {"$pref.pm" => "\$(INST_MAN3DIR)/$mod.\$(MAN3EXT)"},
2079 'INC' => &PDL_INCLUDE(),
2080 'LIBS' => [''],
2081 'clean' => {'FILES' => "$pref.xs $pref.pm $pref\$(OBJ_EXT)"},
2082 )
2083 Here, $src is the name of the source file with PP code, $pref the
2085 prefix for the generated .pm and .xs files and $mod the name of the
2086 extension module to generate.
2087 If your "VERSION_FROM" provides a version, PP will use that to set the
2089 "XS_VERSION". If you need to influence the value of that variable so
2090 that XSLoader etc don't reject the loaded dynamic library, you can use
2091 this workaround in a "pp_addpm" (the "BEGIN" is because the "bootstrap"
2092 happens at runtime, and your code appears after that call, but with a
2093 "BEGIN" it will take place beforehand):
2094 our $VERSION; BEGIN { $VERSION = '2.019106' };
2096 our $XS_VERSION; BEGIN { $XS_VERSION = $VERSION };
2097
2099 The internals of the current version consist of a large table which
2100 gives the rules according to which things are translated and the subs
2101 which implement these rules.
2102 Later on, it would be good to make the table modifiable by the user so
2104 that different things may be tried.
2105 [Meta comment: here will hopefully be more in the future; currently,
2107 your best bet will be to read the source code :-( or ask on the list
2108 (try the latter first) ]
2109
2111 As well as the above-mentioned "PDL_BAD_CODE" and
2112 "PDL_IF_BAD(iftrue,iffalse)", there are also
2113 "PDL_IF_GENTYPE_REAL(iftrue,iffalse)", "PDL_IF_GENTYPE_UNSIGNED", and
2114 "PDL_IF_GENTYPE_INTEGER":
2115 $b() = PDL_IF_GENTYPE_INTEGER(0,NAN);
2117
2119 Unless otherwise specified, the arguments are strings.
2120 Pars
2122 define the signature of your function
2124 OtherPars
2126 arguments which are not pdls. Default: nothing. This is a semi-colon
2128 separated list of arguments, e.g., "OtherPars=>'int k; double value;
2129 PerlIO *fp'". See $COMP(x) and also the same entry in Appendix B.
2130 Code
2132 the actual code that implements the functionality; several PP macros
2134 and PP functions are recognised in the string value
2135 HandleBad
2137 If set to 1, the routine is assumed to support bad values and the code
2139 in the BadCode key is used if bad values are present; it also sets
2140 things up so that the $ISBAD() etc macros can be used. If set to 0,
2141 cause the routine to print a warning if any of the input ndarrays have
2142 their bad flag set.
2143 BadCode
2145 Give the code to be used if bad values may be present in the input
2147 ndarrays. Only used if "HandleBad => 1". If "HandleBad" is true and
2148 "BadCode" is not supplied, the "Code" section will be reused, on the
2149 assumption it will use "#ifdef PDL_BAD_CODE" to handle bad values. As
2150 of 2.073, you can, and are recommended to, use
2151 "PDL_IF_BAD(iftrue,iffalse)".
2152 CopyBadStatusCode
2154 As of 2.079, this is deprecated due to being largely unnecessary;
2156 instead, just use $PDLSTATESETBAD(pdlname) in your "Code" section and
2157 the badflag setting will be propagated to all its parents and children.
2158 The default code here sets the bad flag of the output ndarrays if
2160 $BADFLAGCACHE() is true after the code has been evaluated. Sometimes
2161 "CopyBadStatusCode" is set to an empty string, with the responsibility
2162 of setting the badflag of the output ndarray left to the "BadCode"
2163 section (e.g. the "xxxover" routines in Basic/Primitive/primitive.pd).
2164 GenericTypes
2166 An array reference. The array may contain any subset of the one-
2168 character strings given below, which specify which types your operation
2169 will accept. The meaning of each type is:
2170 B - signed byte (i.e. signed char)
2172 S - signed short (two-byte integer)
2173 U - unsigned short
2174 L - signed long (four-byte integer, int on 32 bit systems)
2175 N - signed integer for indexing ndarray elements (platform & Perl-dependent size)
2176 Q - signed long long (eight byte integer)
2177 F - float
2178 D - double
2179 G - complex float
2180 C - complex double
2181 This is very useful (and important!) when interfacing an external
2183 library. Default: [qw/B S U L N Q F D/]
2184 Inplace
2186 Mark a function as being able to work inplace.
2188 Inplace => 1 if Pars => 'a(); [o]b();'
2190 Inplace => ['a'] if Pars => 'a(); b(); [o]c();'
2191 Inplace => ['a','c'] if Pars => 'a(); b(); [o]c(); [o]d();'
2192 If bad values are being used, care must be taken to ensure the
2194 propagation of the badflag when inplace is being used; for instance see
2195 the code for "setbadtoval" in Basic/Bad/bad.pd.
2196 Doc
2198 Used to specify a documentation string in Pod format. See PDL::Doc for
2200 information on PDL documentation conventions. Note: in the special case
2201 where the PP 'Doc' string is one line this is implicitly used for the
2202 quick reference AND the documentation!
2203 If the Doc field is omitted PP will generate default documentation
2205 (after all it knows about the Signature).
2206 If you really want the function NOT to be documented in any way at this
2208 point (e.g. for an internal routine, or because you are doing it
2209 elsewhere in the code) explicitly specify "Doc=>undef".
2210 BadDoc
2212 Contains the text returned by the "badinfo" command (in "perldl") or
2214 the "-b" switch to the "pdldoc" shell script. In many cases, you will
2215 not need to specify this, since the information can be automatically
2216 created by PDL::PP. However, as befits computer-generated text, it's
2217 rather stilted; it may be much better to do it yourself!
2218 NoPthread
2220 Optional flag to indicate the PDL function should not use processor
2222 threads (i.e. pthreads or POSIX threads) to split up work across
2223 multiple CPU cores. This option is typically set to 1 if the underlying
2224 PDL function is not threadsafe. If this option isn't present, then the
2225 function is assumed to be threadsafe. This option only applies if PDL
2226 has been compiled with POSIX threads enabled.
2227 PMCode
2229 pp_def('funcname',
2231 Pars => 'a(); [o] b();',
2232 PMCode => 'sub PDL::funcname {
2233 return PDL::_funcname_int(@_) if @_ == 2; # output arg "b" supplied
2234 PDL::_funcname_int(@_, my $out = PDL->null);
2235 $out;
2236 }',
2237 # ...
2238 );
2239 PDL functions allow "[o]" ndarray arguments into which you want the
2241 output saved. This is handy because you can allocate an output ndarray
2242 once and reuse it many times; the alternative would be for PDL to
2243 create a new ndarray each time, which may waste compute cycles or, more
2244 likely, RAM.
2245 PDL functions check the number of arguments they are given, and call
2247 "croak" if given the wrong number. By default (with no "PMCode"
2248 supplied), any output arguments may be omitted, and PDL::PP provides
2249 code that can handle this by creating "null" objects, passing them to
2250 your code, then returning them on the stack.
2251 If you do supply "PMCode", the rest of PDL::PP assumes it will be a
2253 string that defines a Perl function with the function's name in the
2254 "pp_bless" package ("PDL" by default). As the example implies, the PP-
2255 generated function name will change from "<funcname>", to
2256 "_<funcname>_int". As also shown above, you will need to supply all
2257 ndarrays in the exact order specified in the signature: output ndarrays
2258 are not optional, and the PP-generated function will not return
2259 anything.
2260 PMFunc
2262 When pp_def generates functions, it typically defines them in the PDL
2264 package. Then, in the .pm file that it generates for your module, it
2265 typically adds a line that essentially copies that function into your
2266 current package's symbol table with code that looks like this:
2267 *func_name = \&PDL::func_name;
2269 It's a little bit smarter than that (it knows when to wrap that sort of
2271 thing in a BEGIN block, for example, and if you specified something
2272 different for pp_bless), but that's the gist of it. If you don't care
2273 to import the function into your current package's symbol table, you
2274 can specify
2275 PMFunc => '',
2277 PMFunc has no other side-effects, so you could use it to insert
2279 arbitrary Perl code into your module if you like. However, you should
2280 use pp_addpm if you want to add Perl code to your module.
2281 ReadDataFuncName
2283 Allows overriding the default function-name, for reading data
2285 transformed by this operation. Mainly used internally to set it to
2286 "NULL", in which case a default affine-orientated function will be
2287 called instead.
2288 WriteBackDataFuncName
2290 As above, but for writing transformed data from a child of this
2292 transformation back to the parent when "BackCode" is supplied.
2293 AffinePriv
2295 Flag to indicate this is an affine transformation whose "Priv"
2297 (contents of the "pdl_trans") contains data that will need allocating
2298 and freeing.
2299 GlobalNew
2301 If supplied, will prevent generation of an XS function, and assigns the
2303 generated C "run" function into the named slot in the "Core" struct.
2304 This is not used as of 2.058, and instead the relevant C functions are
2305 in pdlaffine.c.
2306 P2Child
2308 Forces "Pars" to be "PARENT" and "CHILD", the function's "GenericTypes"
2310 to be all of them, no "HaveBroadcasting" or "CallCopy", and turns on
2311 "DefaultFlow" (so do not supply any of those args). Intended for
2312 affine transformations with dataflow.
2313 DefaultFlow
2315 If set, sets in the "pdl_transvtable" (see PDL::Internals) the "iflags"
2317 such that the trans will start with dataflow both forwards and
2318 backwards. Note that setting this to any value (including 0) will
2319 trigger the behaviour.
2320 HaveBroadcasting
2322 Default true. If so, generate code implementing broadcasting (see
2324 PDL::Indexing).
2325 CallCopy
2327 For parameters that get created, normally the "PDL->initialize" will be
2329 used (or on a subclass). If this is true (which is the default for
2330 simple functions i.e. 2-arg with 0-dim signatures), instead the first
2331 argument's "copy" method will be used.
2332 TwoWay
2334 If true, sets in the "pdl_transvtable" (see PDL::Internals) the
2336 "iflags" such as to inform the trans's error checks connected to
2337 dataflow.
2338 Identity
2340 If true, sets "RedoDims" "EquivCPOffsCode" "HandleBad" "P2Child"
2342 "TwoWay" such that the function is a dataflowing identity
2343 transformation.
2344 BackCode
2346 For dataflowing functions, this value (which gets parsed) overrides the
2348 operation of that from children ndarrays to parents.
2349 BadBackCode
2351 Same but taking account of bad values.
2353 EquivCPOffsCode
2355 If supplied, allows concise control of copying to Child from Parent the
2357 data considered Equivalent at each given Offset (hence the name); the
2358 "Code" and "BackCode" will be generated from this.
2359 Example:
2361 pp_def(
2363 '_clump_int',
2364 OtherPars => 'int n',
2365 P2Child => 1,
2366 RedoDims => # omitted
2367 EquivCPOffsCode => '
2368 PDL_Indx i;
2369 for(i=0; i<$PDL(CHILD)->nvals; i++) $EQUIVCPOFFS(i,i);
2370 ',
2371 );
2372
2374 Macros
2375 $variablename_from_sig()
2376 access a pdl (by its name) that was specified in the signature
2378 $COMP(x)
2380 access a value in the private data structure of this transformation
2382 (mainly used to use an argument that is specified in the "OtherPars"
2383 section)
2384 $SIZE(n)
2386 replaced at runtime by the actual size of a named dimension (as
2388 specified in the signature)
2389 $GENERIC()
2391 replaced by the C type that is equal to the runtime type of the
2393 operation
2394 $P(a)
2396 a pointer to the data of the PDL named "a" in the signature. Useful for
2398 interfacing to C functions
2399 $PP(a)
2401 a physical pointer access to pdl "a"; mainly for internal use
2403 $TXYZ(AlternativeX,AlternativeY,AlternativeZ)
2405 expansion alternatives according to runtime type of operation, where
2407 XXX is some string that is matched by "/[BSULNQFD+]/".
2408 $PDL(a)
2410 return a pointer to the pdl data structure (pdl *) of ndarray "a"
2412 $ISBAD(a())
2414 returns true if the value stored in a() equals the bad value for this
2416 ndarray. Requires "HandleBad" being set to 1.
2417 $ISGOOD(a())
2419 returns true if the value stored in a() does not equal the bad value
2421 for this ndarray. Requires "HandleBad" being set to 1.
2422 $SETBAD(a())
2424 Sets a() to equal the bad value for this ndarray. Requires "HandleBad"
2426 being set to 1.
2427 $PRIV()
2429 To access fields in the "pdl_trans", eg $PRIV(offs).
2431 $CROAK()
2433 Returns a "pdl_error" with the supplied (var-args) message, adding the
2435 function name at the start, which will cause a "barf" within the Perl
2436 code. This is (as of 2.064) a change in PDL functions' API, so that
2437 callers can handle exceptions in their preferred way, which may not use
2438 Perl at all.
2439 $EQUIVCPOFFS()
2441 Copy from the "PARENT" parameter at the first given offset, to the
2443 "CHILD" parameter at the second given offset.
2444 $EQUIVCPTRUNC()
2446 Similar, but if the expression given as the third parameter is false,
2448 instead set the "CHILD"'s value to 0.
2449 $DOCOMPALLOC()
2451 Allocates memory for any "Comp" arrays, after their size has been
2453 determined, e.g. here after $COMP(whichdims_count) has been set:
2454 Comp => 'PDL_Indx whichdims[$COMP(whichdims_count)]',
2456 $DOPRIVALLOC()
2458 As above, except the key is "Priv"; because it is "Priv", this is only
2460 for entries in the "pdl_trans" itself, and almost certainly only for
2461 operations where "AffinePriv" is true.
2462 $SETNDIMS()
2464 For affine transformations (specifically, ones which set P2Child to
2466 true), set the child's "ndims" to the given value and allocate a
2467 suitably-sized array of dimension values.
2468 $SETDIMS()
2470 Similarly for affine transformations, after the above and then the
2472 actual dimension sizes are set, use this to resize the child ndarray to
2473 the right size.
2474 $SETDELTABROADCASTIDS()
2476 Similarly again, this sets the child's "nbroadcastids" to the same as
2478 the parent's, allocates space for the "broadcastids", then sets the
2479 child's ones to the same as the parent's plus the given value.
2480 To get a flavour of what "broadcastids" are for, in the normal way of
2482 things the first (0th) one in the parent is the highest dimension-
2483 number in it. See PDL::Indexing for more.
2484 functions
2486 "loop(DIMS) %{ ... %}"
2487 loop over named dimensions; limits are generated automatically by PP
2489 "broadcastloop %{ ... %}"
2491 enclose following code in a broadcast loop
2493 As of 2.075, "threadloop" is a deprecated alias for this.
2495 "types(TYPES) %{ ... %}"
2497 execute following code if type of operation is any of "TYPES"
2499
2501 A number of functions are imported when you "use PDL::PP". These
2502 include functions that control the generated C or XS code, functions
2503 that control the generated Perl code, and functions that manipulate the
2504 packages and symbol tables into which the code is created.
2505 Generating C and XS Code
2507 PDL::PP's main purpose is to make it easy for you to wrap the
2508 broadcasting engine around your own C code, but you can do some other
2509 things, too.
2510 pp_def
2512 Used to wrap the broadcasting engine around your C code. Virtually all
2514 of this document discusses the use of pp_def.
2515 pp_done
2517 Indicates you are done with PDL::PP and that it should generate its .xs
2519 and .pm files based upon the other pp_* functions that you have called.
2520 This function takes no arguments.
2521 pp_addxs
2523 This lets you add XS code to your .xs file. This is useful if you want
2525 to create Perl-accessible functions that invoke C code but cannot or
2526 should not invoke the broadcasting engine. XS is the standard means by
2527 which you wrap Perl-accessible C code. You can learn more at perlxs.
2528 pp_add_boot
2530 This function adds whatever string you pass to the XS BOOT section. The
2532 BOOT section is C code that gets called by Perl when your module is
2533 loaded and is useful for automatic initialization. You can learn more
2534 about XS and the BOOT section at perlxs.
2535 pp_addhdr
2537 Adds pure-C code to your XS file. XS files are structured such that
2539 pure C code must come before XS specifications. This allows you to
2540 specify such C code.
2541 Generating Perl Code
2543 Many functions imported when you use PDL::PP allow you to modify the
2544 contents of the generated .pm file. In addition to pp_def and pp_done,
2545 the role of these functions is primarily to add code to various parts
2546 of your generated .pm file.
2547 pp_addpm
2549 Adds Perl code to the generated .pm file. PDL::PP actually keeps track
2551 of three different sections of generated code: the Top, the Middle, and
2552 the Bottom. You can add Perl code to the Middle section using the one-
2553 argument form, where the argument is the Perl code you want to supply.
2554 In the two-argument form, the first argument is an anonymous hash with
2555 only one key that specifies where to put the second argument, which is
2556 the string that you want to add to the .pm file. The hash is one of
2557 these three:
2558 {At => 'Top'}
2560 {At => 'Middle'}
2561 {At => 'Bot'}
2562 For example:
2564 pp_addpm({At => 'Bot'}, <<POD);
2566 =head1 Some documentation
2568 I know I'm typing this in the middle of my file, but it'll go at
2570 the bottom.
2571 =cut
2573 POD
2575 Warning: If, in the middle of your .pd file, you put documentation
2577 meant for the bottom of your pod, you will thoroughly confuse CPAN. On
2578 the other hand, if in the middle of your .pd file, you add some Perl
2579 code destined for the bottom or top of your .pm file, you only have
2580 yourself to confuse. :-)
2581 pp_beginwrap
2583 Adds BEGIN-block wrapping. Certain declarations can be wrapped in BEGIN
2585 blocks, though the default behavior is to have no such wrapping.
2586 pp_addbegin
2588 Sets code to be added to the top of your .pm file, even above code that
2590 you specify with "pp_addpm({At => 'Top'}, ...)". Unlike pp_addpm,
2591 calling this overwrites whatever was there before. Generally, you
2592 probably shouldn't use it.
2593 Tracking Line Numbers
2595 When you get compile errors, either from your C-like code or your Perl
2596 code, it can help to make those errors back to the line numbers in the
2597 source file at which the error occurred.
2598 pp_line_numbers
2600 Takes a line number and a (usually long) string of code. The line
2602 number should indicate the line at which the quote begins. This is
2603 usually Perl's "__LINE__" literal, unless you are using heredocs, in
2604 which case it is "__LINE__ + 1". The returned string has #line
2605 directives interspersed to help the compiler report errors on the
2606 proper line.
2607 Modifying the Symbol Table and Export Behavior
2609 PDL::PP usually exports all functions generated using pp_def, and
2610 usually installs them into the PDL symbol table. However, you can
2611 modify this behavior with these functions.
2612 pp_bless
2614 Sets the package (symbol table) to which the XS code is added. The
2616 default is PDL, which is generally what you want. If you use the
2617 default blessing and you create a function myfunc, then you can do the
2618 following:
2619 $ndarray->myfunc(<args>);
2621 PDL::myfunc($ndarray, <args>);
2622 On the other hand, if you bless your functions into another package,
2624 you cannot invoke them as PDL methods, and must invoke them as:
2625 MyPackage::myfunc($ndarray, <args>);
2627 Of course, you could always use the PMFunc key to add your function to
2629 the PDL symbol table, but why do that?
2630 pp_add_isa
2632 Adds to the list of modules from which your module inherits. The
2634 default list is
2635 qw(PDL::Exporter DynaLoader)
2637 pp_core_importlist
2639 At the top of your generated .pm file is a line that looks like this:
2641 use PDL::Core;
2643 You can modify that by specifying a string to pp_core_importlist. For
2645 example,
2646 pp_core_importlist('::Blarg');
2648 will result in
2650 use PDL::Core::Blarg;
2652 You can use this, for example, to add a list of symbols to import from
2654 PDL::Core. For example:
2655 pp_core_importlist(" ':Internal'");
2657 will lead to the following use statement:
2659 use PDL::Core ':Internal';
2661 pp_setversion
2663 Sets your module's version. The version must be consistent between the
2665 .xs and the .pm file, and is used to ensure that your Perl's libraries
2666 do not suffer from version skew.
2667 pp_add_exported
2669 Adds to the export list whatever names you give it. Functions created
2671 using pp_def are automatically added to the list. This function is
2672 useful if you define any Perl functions using pp_addpm or pp_addxs that
2673 you want exported as well.
2674 pp_export_nothing
2676 This resets the list of exported symbols to nothing. This is probably
2678 better called "pp_export_clear", since you can add exported symbols
2679 after calling "pp_export_nothing". When called just before calling
2680 pp_done, this ensures that your module does not export anything, for
2681 example, if you only want programmers to use your functions as methods.
2682
2684 For the concepts of broadcasting and slicing check PDL::Indexing.
2685 PDL::Internals
2687 PDL::BadValues for information on bad values
2689 perlxs, perlxstut
2691 Practical Magick with C, PDL, and PDL::PP -- a guide to compiled add-
2693 ons for PDL <https://arxiv.org/abs/1702.07753>
2694
2696 Although PDL::PP is quite flexible and thoroughly used, there are
2697 surely bugs. First amongst them: this documentation needs a thorough
2698 revision.
2699
2701 Copyright(C) 1997 Tuomas J. Lukka (lukka@fas.harvard.edu), Karl
2702 Glaazebrook (kgb@aaocbn1.aao.GOV.AU) and Christian Soeller
2703 (c.soeller@auckland.ac.nz). All rights reserved. Documentation updates
2704 Copyright(C) 2011 David Mertens (dcmertens.perl@gmail.com). This
2705 documentation is licensed under the same terms as Perl itself.
2706perl v5.38.0 2023-07-21 PP(1)