FFI::Platypus::Declare(3pm)

1FFI::Platypus::Declare(U3s)er Contributed Perl DocumentatFiFoIn::Platypus::Declare(3)
2
3
4

NAME

6       FFI::Platypus::Declare - Declarative interface to FFI::Platypus
7

VERSION

9       version 1.32
10

SYNOPSIS

12        use FFI::Platypus::Declare 'string', 'int';
13
14        lib undef; # use libc
15        attach puts => [string] => int;
16
17        puts("hello world");
18

DESCRIPTION

20       This module is officially discouraged.  The idea was to provide a
21       simpler declarative interface without the need of (directly) creating
22       an FFI::Platypus instance.  In practice it is almost as complicated and
23       makes it difficult to upgrade to the proper OO interface if the need
24       arises.  I have stopped using it mainly for this reason.  It will
25       remain as part of the Platypus core distribution to keep old code
26       working, but you are encouraged to write new code using the OO
27       interface.  Alternatively, you can try the Perl 6 inspired NativeCall,
28       which provides most of the goals this module was intended for (that is
29       a simple interface at the cost of some power), without much of the
30       complexity.  The remainder of this document describes the interface.
31
32       This module provides a declarative interface to FFI::Platypus. It
33       provides a more concise interface at the cost of a little less power,
34       and a little more namespace pollution.
35
36       Any strings passed into the "use" line will be declared as types and
37       exported as constants into your namespace, so that you can use them
38       without quotation marks.
39
40       Aliases can be declared using a list reference:
41
42        use FFI::Platypus [ 'int[48]' => 'my_integer_array' ];
43
44       Custom types can also be declared as a list reference (the type name
45       must include a ::):
46
47        use FFI::Platypus [ '::StringPointer' => 'my_string_pointer' ];
48        # short for FFI::Platypus::Type::StringPointer
49

FUNCTIONS

51       All functions are exported into your namespace.  If you do not want
52       that, then use the OO interface (see FFI::Platypus).
53
54   lib
55        lib $libpath;
56
57       Specify one or more dynamic libraries to search for symbols. If you are
58       unsure of the location / version of the library then you can use
59       FFI::CheckLib#find_lib.
60
61   type
62        type $type;
63        type $type = $alias;
64
65       Declare the given type.
66
67       Examples:
68
69        type 'uint8'; # only really checks that uint8 is a valid type
70        type 'uint8' => 'my_unsigned_int_8';
71
72   custom_type
73        custom_type $alias => \%args;
74
75       Declare the given custom type.  See FFI::Platypus::Type#Custom-Types
76       for details.
77
78   load_custom_type
79        load_custom_type $name => $alias, @type_args;
80
81       Load the custom type defined in the module $name, and make an alias
82       with the name $alias. If the custom type requires any arguments, they
83       may be passed in as @type_args. See FFI::Platypus::Type#Custom-Types
84       for details.
85
86       If $name contains "::" then it will be assumed to be a fully qualified
87       package name. If not, then "FFI::Platypus::Type::" will be prepended to
88       it.
89
90   type_meta
91        my $meta = type_meta $type;
92
93       Get the type meta data for the given type.
94
95       Example:
96
97        my $meta = type_meta 'int';
98
99   attach
100        attach $name => \@argument_types => $return_type;
101        attach [$c_name => $perl_name] => \@argument_types => $return_type;
102        attach [$address => $perl_name] => \@argument_types => $return_type;
103
104       Find and attach a C function as a Perl function as a real live xsub.
105
106       If just one $name is given, then the function will be attached in Perl
107       with the same name as it has in C.  The second form allows you to give
108       the Perl function a different name.  You can also provide a memory
109       address (the third form) of a function to attach.
110
111       Examples:
112
113        attach 'my_function', ['uint8'] => 'string';
114        attach ['my_c_function_name' => 'my_perl_function_name'], ['uint8'] => 'string';
115        my $string1 = my_function($int);
116        my $string2 = my_perl_function_name($int);
117
118   closure
119        my $closure = closure $codeblock;
120
121       Create a closure that can be passed into a C function.  For details on
122       closures, see FFI::Platypus::Type#Closures.
123
124       Example:
125
126        my $closure1 = closure { return $_[0] * 2 };
127        my $closure2 = closure sub { return $_[0] * 4 };
128
129   sticky
130        my $closure = sticky closure $codeblock;
131
132       Keyword to indicate the closure should not be deallocated for the life
133       of the current process.
134
135       If you pass a closure into a C function without saving a reference to
136       it like this:
137
138        foo(closure { ... });         # BAD
139
140       Perl will not see any references to it and try to free it immediately.
141       (this has to do with the way Perl and C handle responsibilities for
142       memory allocation differently).  One fix for this is to make sure the
143       closure remains in scope using either "my" or "our".  If you know the
144       closure will need to remain in existence for the life of the process
145       (or if you do not care about leaking memory), then you can add the
146       sticky keyword to tell FFI::Platypus to keep the thing in memory.
147
148        foo(sticky closure { ... });  # OKAY
149
150   cast
151        my $converted_value = cast $original_type, $converted_type, $original_value;
152
153       The "cast" function converts an existing $original_value of type
154       $original_type into one of type $converted_type.  Not all types are
155       supported, so care must be taken.  For example, to get the address of a
156       string, you can do this:
157
158        my $address = cast 'string' => 'opaque', $string_value;
159
160   attach_cast
161        attach_cast "cast_name", $original_type, $converted_type;
162        my $converted_value = cast_name($original_value);
163
164       This function creates a subroutine which can be used to convert
165       variables just like the cast function above.  The above synopsis is
166       roughly equivalent to this:
167
168        sub cast_name { cast($original_type, $converted_type, $_[0]) }
169        my $converted_value = cast_name($original_value);
170
171       Except that the attach_cast variant will be much faster if called
172       multiple times since the cast does not need to be dynamically allocated
173       on each instance.
174
175   sizeof
176        my $size = sizeof $type;
177
178       Returns the total size of the given type.  For example to get the size
179       of an integer:
180
181        my $intsize = sizeof 'int'; # usually 4 or 8 depending on platform
182
183       You can also get the size of arrays
184
185        my $intarraysize = sizeof 'int[64]';
186
187       Keep in mind that "pointer" types will always be the pointer / word
188       size for the platform that you are using.  This includes strings,
189       opaque and pointers to other types.
190
191       This function is not very fast, so you might want to save this value as
192       a constant, particularly if you need the size in a loop with many
193       iterations.
194
195   lang
196        lang $language;
197
198       Specifies the foreign language that you will be interfacing with. The
199       default is C.  The foreign language specified with this attribute
200       changes the default native types (for example, if you specify Rust, you
201       will get "i32" as an alias for "sint32" instead of "int" as you do with
202       C).
203
204       In the future this may attribute may offer hints when doing demangling
205       of languages that require it like C++.
206
207   abi
208        abi $abi;
209
210       Set the ABI or calling convention for use in subsequent calls to
211       "attach".  May be either a string name or integer value from
212       FFI::Platypus#abis.
213

AUTHOR

234       Author: Graham Ollis <plicease@cpan.org>
235
236       Contributors:
237
238       Bakkiaraj Murugesan (bakkiaraj)
239
240       Dylan Cali (calid)
241
242       pipcet
243
244       Zaki Mughal (zmughal)
245
246       Fitz Elliott (felliott)
247
248       Vickenty Fesunov (vyf)
249
250       Gregor Herrmann (gregoa)
251
252       Shlomi Fish (shlomif)
253
254       Damyan Ivanov
255
256       Ilya Pavlov (Ilya33)
257
258       Petr Pisar (ppisar)
259
260       Mohammad S Anwar (MANWAR)
261
262       Håkon Hægland (hakonhagland, HAKONH)
263
264       Meredith (merrilymeredith, MHOWARD)
265
266       Diab Jerius (DJERIUS)
267

COPYRIGHT AND LICENSE

269       This software is copyright (c) 2015,2016,2017,2018,2019,2020 by Graham
270       Ollis.
271
272       This is free software; you can redistribute it and/or modify it under
273       the same terms as the Perl 5 programming language system itself.
274
275
276
277perl v5.32.0                      2020-09-21         FFI::Platypus::Declare(3)