1CallExt(3)            User Contributed Perl Documentation           CallExt(3)
2
3
4

NAME

6       PDL::CallExt - call functions in external shared libraries
7

SYNOPSIS

9        use PDL::CallExt;
10        callext('file.so', 'foofunc', $x, $y); # pass ndarrays to foofunc()
11
12        % perl -MPDL::CallExt -e callext_cc file.c
13

DESCRIPTION

15       callext() loads in a shareable object (i.e. compiled code) using Perl's
16       dynamic loader, calls the named function and passes a list of ndarray
17       arguments to it.
18
19       It provides a reasonably portable way of doing this, including
20       compiling the code with the right flags, though it requires simple perl
21       and C wrapper routines to be written. You may prefer to use PP, which
22       is much more portable. See PDL::PP. You should definitely use the
23       latter for a 'proper' PDL module, or if you run in to the limitations
24       of this module.
25

API

27       callext_cc() allows one to compile the shared objects using Perl's
28       knowledge of compiler flags.
29
30       The named function (e.g. 'foofunc') must take a list of ndarray
31       structures as arguments, there is now way of doing portable general
32       argument construction hence this limitation.
33
34       In detail the code in the original file.c would look like this:
35
36        #include "pdlsimple.h" /* Declare simple ndarray structs - note this .h file
37                                  contains NO perl/PDL dependencies so can be used
38                                  standalone */
39
40        int foofunc(int nargs, pdlsimple **args); /* foofunc prototype */
41
42       i.e. foofunc() takes an array of pointers to pdlsimple structs. The use
43       is similar to that of "main(int nargs, char **argv)" in UNIX C
44       applications.
45
46       pdlsimple.h defines a simple N-dimensional data structure which looks
47       like this:
48
49         struct pdlsimple {
50            int    datatype;  /* whether byte/int/float etc. */
51            void  *data;      /* Generic pointer to the data block */
52            PDL_Indx nvals;   /* Number of data values */
53            PDL_Indx *dims;   /* Array of data dimensions */
54            PDL_Indx ndims;   /* Number of data dimensions */
55         };
56
57       (PDL_Indx is 32- or 64-bit depending on architecture and is defined in
58       pdlsimple.h)
59
60       This is a simplification of the internal representation of ndarrays in
61       PDL which is more complicated because of broadcasting, dataflow, etc.
62       It will usually be found somewhere like
63       /usr/local/lib/perl5/site_perl/PDL/pdlsimple.h
64
65       Thus to actually use this to call real functions one would need to
66       write a wrapper.  e.g. to call a 2D image processing routine:
67
68        void myimage_processer(double* image, int nx, int ny);
69
70        int foofunc(int nargs, pdlsimple **args) {
71           pdlsimple* image = pdlsimple[0];
72           myimage_processer( image->data, *(image->dims), *(image->dims+1) );
73           ...
74        }
75
76       Obviously a real wrapper would include more error and argument
77       checking.
78
79       This might be compiled (e.g. Linux):
80
81        cc -shared -o mycode.so mycode.c
82
83       In general Perl knows how to do this, so you should be able to get away
84       with:
85
86        perl -MPDL::CallExt -e callext_cc file.c
87
88       callext_cc() is a function defined in PDL::CallExt to generate the
89       correct compilation flags for shared objects.
90
91       If their are problems you will need to refer to you C compiler manual
92       to find out how to generate shared libraries.
93
94       See t/callext.t in the distribution for a working example.
95
96       It is up to the caller to ensure datatypes of ndarrays are correct - if
97       not peculiar results or SEGVs will result.
98

FUNCTIONS

100   callext
101       Call a function in an external library using Perl dynamic loading
102
103         callext('file.so', 'foofunc', $x, $y); # pass ndarrays to foofunc()
104
105       The file must be compiled with dynamic loading options (see
106       "callext_cc"). See the module docs "PDL::Callext" for a description of
107       the API.
108
109   callext_cc
110       Compile external C code for dynamic loading
111
112       Usage:
113
114        % perl -MPDL::CallExt -e callext_cc file.c -o file.so
115
116       This works portably because when Perl has built in knowledge of how to
117       do dynamic loading on the system on which it was installed.  See the
118       module docs "PDL::Callext" for a description of the API.
119

AUTHORS

121       Copyright (C) Karl Glazebrook 1997.  All rights reserved. There is no
122       warranty. You are allowed to redistribute this software / documentation
123       under certain conditions. For details, see the file COPYING in the PDL
124       distribution. If this file is separated from the PDL distribution, the
125       copyright notice should be included in the file.
126
127
128
129perl v5.34.0                      2022-02-28                        CallExt(3)
Impressum