npm - javonet-nodejs-sdk - Versions diffs - 2.5.15 → 2.5.17 - Mend

javonet-nodejs-sdk 2.5.15 → 2.5.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2047) hide show

package/Binaries/Perl/Linux/X64/deps/lib/perl5/x86_64-linux-gnu-thread-multi/FFI/Platypus/Type.pm DELETED Viewed

@@ -1,1399 +0,0 @@
-package FFI::Platypus::Type;
-use strict;
-use warnings;
-use 5.008004;
-use Carp qw( croak );
-require FFI::Platypus;
-# ABSTRACT: Defining types for FFI::Platypus
-our $VERSION = '2.10'; # VERSION
-# The TypeParser and Type classes are used internally ONLY and
-# are not to be exposed to the user.  External users should
-# not under any circumstances rely on the implementation of
-# these classes.
-sub alignof
-{
-  my($self) = @_;
-  my $meta = $self->meta;
-  # TODO: it is possible, though complicated
-  #       to compute the alignment of a struct
-  #       type record.
-  croak "cannot determine alignment of record"
-    if $meta->{type} eq 'record'
-    && $meta->{ref} == 1;
-  my $ffi_type;
-  if($meta->{type} eq 'pointer')
-  {
-    $ffi_type = 'pointer';
-  }
-  elsif($meta->{type} eq 'record')
-  {
-    $ffi_type = 'uint8';
-  }
-  else
-  {
-    $ffi_type = $meta->{ffi_type};
-  }
-  require FFI::Platypus::ShareConfig;
-  FFI::Platypus::ShareConfig->get('align')->{$ffi_type};
-}
-1;
-__END__
-=pod
-=encoding UTF-8
-=head1 NAME
-FFI::Platypus::Type - Defining types for FFI::Platypus
-=head1 VERSION
-version 2.10
-=head1 SYNOPSIS
-OO Interface:
- use FFI::Platypus 2.00;
- my $ffi = FFI::Platypus->new( api => 2 );
- $ffi->type('int' => 'my_int');
-=head1 DESCRIPTION
-B<Note>: This document assumes that you are using C<api =E<gt> 2>,
-which you should be using for all new code.
-This document describes how to define types using L<FFI::Platypus>.
-Types may be "defined" ahead of time, or simply used when defining or
-attaching functions.
- # Example of defining types
- use FFI::Platypus 2.00;
- my $ffi = FFI::Platypus->new( api => 2 );
- $ffi->type('int');
- $ffi->type('string');
- # Example of simply using types in function declaration or attachment
- my $f = $ffi->function(puts => ['string'] => 'int');
- $ffi->attach(puts => ['string'] => 'int');
-Unless you are using aliases the L<FFI::Platypus#type> method is not
-necessary, but they will throw an exception if the type is incorrectly
-specified or not supported, which may be helpful for determining if
-the types are available or not.
-Note: This document sometimes uses the term "C Function" as short hand
-for function implemented in a compiled language.  Unless the term is
-referring literally to a C function example code, you can assume that
-it should also work with another compiled language.
-=head2 meta information about types
-You can get the size of a type using the L<FFI::Platypus#sizeof> method.
- my $intsize = $ffi->sizeof('int');           # usually 4
- my $intarraysize = $ffi->sizeof('int[64]');  # usually 256
-=head2 converting types
-Sometimes it is necessary to convert types.  In particular various
-pointer types often need to be converted for consumption in Perl.  For
-this purpose the L<FFI::Platypus#cast> method is provided.  It needs to
-be used with care though, because not all type combinations are
-supported.  Here are some useful ones:
- my $address = $ffi->cast('string' => 'opaque', $string);
-This converts a Perl string to a pointer address that can be used
-by functions that take an C<opaque> type.  Be carefully though that
-the Perl string is not resized or free'd while in use from C code.
- my $string  = $ffi->cast('opaque' => 'string', $pointer);
-This does the opposite, converting a null terminated string (the
-type of strings used by C) into a Perl string.  In this case the
-string is copied, so the other language is free to deallocate or
-otherwise manipulate the string after the conversion without adversely
-affecting the Perl.
-=head2 aliases
-Some times using alternate names is useful for documenting the purpose
-of an argument or return type.  For this "aliases" can be helpful.  The
-second argument to the L<FFI::Platypus#type> method can be used to
-define a type alias that can later be used by function declaration
-and attachment.
- use FFI::Platypus 2.00;
- my $ffi = FFI::Platypus->new( api => 2 );
- $ffi->type('int'    => 'myint');
- $ffi->type('string' => 'mystring');
- my $f = $ffi->function( puts => ['mystring'] => 'myint' );
- $ffi->attach( puts => ['mystring'] => 'myint' );
-Aliases are contained without the L<FFI::Platypus> object, so feel free
-to define your own crazy types without stepping on the toes of other
-CPAN developers using Platypus.
-One useful application of an alias is when you know types are different
-on two different platforms:
- if($^O eq 'MSWin32')
- {
-   $type->type('sint16' => 'foo_t');
- } elsif($^O eq 'linux')
- {
-   $type->type('sint32' => 'foo_t');
- }
- # function foo takes 16 bit signed integer on Windows
- # and a 32 bit signed integer on Linux.
- $ffi->attach( foo => [ 'foo_t' ] => 'void' );
-=for stopwords tm
-=head1 TYPE CATEGORIES
-=head2 Native types
-So called native types are the types that the CPU understands that can
-be passed on the argument stack or returned by a function.  It does not
-include more complicated types like arrays or structs, which can be
-passed via pointers (see the opaque type below).  Generally native types
-include void, integers, floats and pointers.
-=head3 the void type
-This can be used as a return value to indicate a function does not
-return a value (or if you want the return value to be ignored).
- $ffi->type( foo => [] => 'void' );
-Newer versions of Platypus also allow you to omit the return type and
-C<void> is assumed.
- $ffi->type( foo => [] );
-It doesn't really make sense to use C<void> in any other context.  However,
-because of historical reasons involving older versions of Perl.
-It doesn't really make sense for C<void> to be passed in as an argument.
-However, because C functions that take no arguments frequently are specified
-as taking C<void> as this was required by older C compilers, as a special
-case you can specify a function's arguments as taking a single C<void> to
-mean it takes no arguments.
- # C: void foo(void);
- $ffi->type( foo => ['void'] );
- # same (but probably better)
- $ffi->type( foo => [] );
-=head3 integer types
-The following native integer types are always available (parentheticals
-indicates the usual corresponding C type):
-=over 4
-=item sint8
-Signed 8 bit byte (C<signed char>, C<int8_t>).
-=item uint8
-Unsigned 8 bit byte (C<unsigned char>, C<uint8_t>).
-=item sint16
-Signed 16 bit integer (C<short>, C<int16_t>)
-=item uint16
-Unsigned 16 bit integer (C<unsigned short>, C<uint16_t>)
-=item sint32
-Signed 32 bit integer (C<int>, C<int32_t>)
-=item uint32
-Unsigned 32 bit integer (C<unsigned int>, C<uint32_t>)
-=item sint64
-Signed 64 bit integer (C<long long>, C<int64_t>)
-=item uint64
-Unsigned 64 bit integer (C<unsigned long long>,
-C<uint64_t>)
-=back
-You may also use C<uchar>, C<ushort>, C<uint> and C<ulong> as short
-names for C<unsigned char>, C<unsigned short>, C<unsigned int> and
-C<unsigned long>.
-These integer types are also available, but there actual size and sign
-may depend on the platform.
-=over 4
-=item char
-Somewhat confusingly, C<char> is an integer type!  This is really an
-alias for either C<sint8_t> or C<uint8_t> depending on your platform.
-If you want to pass a character (not integer) in to a C function that
-takes a character you want to use the perl L<ord|perlfunc/ord> function.
-Here is an example that uses the standard libc C<isalpha>, C<isdigit>
-type functions:
- use FFI::Platypus 2.00;
- my $ffi = FFI::Platypus->new( api => 2 );
- $ffi->lib(undef);
- $ffi->type('int' => 'character');
- my @list = qw(
-   alnum alpha ascii blank cntrl digit lower print punct
-   space upper xdigit
- );
- $ffi->attach("is$_" => ['character'] => 'int') for @list;
- my $char = shift(@ARGV) || 'a';
- no strict 'refs';
- printf "'%s' is %s %s\n", $char, $_, &{'is'.$_}(ord $char) for @list;
-=item size_t
-This is usually an C<unsigned long>, but it is up to the compiler to
-decide.  The C<malloc> function is defined in terms of C<size_t>:
- $ffi->attach( malloc => ['size_t'] => 'opaque';
-(Note that you can get C<malloc> from L<FFI::Platypus::Memory>).
-=item long, unsigned long
-On 64 bit systems, this is usually a 64 bit integer.  On 32 bit systems
-this is frequently a 32 bit integer (and C<long long> or
-C<unsigned long long> are for 64 bit).
-=back
-There are a number of other types that may or may not be available if
-they are detected when L<FFI::Platypus> is installed.  This includes
-things like C<wchar_t>, C<off_t>, C<wint_t>. You can use this script to
-list all the integer types that L<FFI::Platypus> knows about, plus how
-they are implemented.
- use FFI::Platypus 2.00;
- my $ffi = FFI::Platypus->new( api => 2 );
- foreach my $type_name (sort $ffi->types)
- {
-   my $meta = $ffi->type_meta($type_name);
-   next unless defined $meta->{element_type} && $meta->{element_type} eq 'int';
-   printf "%20s %s\n", $type_name, $meta->{ffi_type};
- }
-If you need a common system type that is not provided, please open a
-ticket in the Platypus project's GitHub issue tracker.  Be sure to
-include the usual header file the type can be found in.
-=head3 Enum types
-C provides enumerated types, which are typically implemented as integer
-types.
- enum {
-   BAR = 1,
-   BAZ = 2
- } foo_t;
- void f(enum foo_t foo);
-Platypus provides C<enum> and C<senum> types for the integer types used
-to represent enum and signed enum types respectively.
- use constant BAR => 1;
- use constant BAZ => 2;
- $ffi->attach( f => [ 'enum' ] => 'void' );
- f(BAR);
- f(BAZ);
-When do you use C<senum>?  Anytime the enum has negative values:
- enum {
-   BAR = -1;
-   BAZ = 2;
- } foo_t;
- void f(enum foo_t foo);
-Perl:
- use constant BAR => -1;
- use constant BAZ => 2;
- $ffi->attach( f => [ 'senum' ] => 'void' );
- f(BAR);
- f(BAZ);
-Dealing with enumerated values with FFI can be tricky because these are
-usually defined in C header files and cannot be found in dynamic libraries.
-For trivial usage you can do as illustrated above, simply define your own
-Perl constants.  For more complicated usage, or where the values might vary
-from platform to platform you may want to consider the new Platypus bundle
-interface to define Perl constants (essentially the same as an enumerated
-value) from C space.  This is more reliable, but does require a compiler
-at install time.  See L<FFI::Platypus::Constant> for details.
-The main FAQ (L<FFI::Platypus/FAQ>) also has a discussion on dealing
-with constants and enumerated types.
-There is also a type plugin (L<FFI::Platypus::Type::Enum>) that can be helpful
-in writing interfaces that use enums.
-=head3 Boolean types
-At install time Platypus attempts to detect the correct type for C<bool>
-for your platform, and you can use that.  C<bool> is really an integer
-type, but the type used varies from platform to platform.
-C header:
- #include <stdbool.h>
- bool foo();
-Platypus
- $ffi->attach( foo => [] => 'bool' );
-If you get an exception when trying to use this type it means you either
-have a very old version of Platypus, or for some reason it was unable to
-detect the correct type at install time.  Please open a ticket if that is
-the case.
-=head3 floating point types
-The following native floating point types are always available
-(parentheticals indicates the usual corresponding C type):
-=over 4
-=item float
-Single precision floating point (I<float>)
-=item double
-Double precision floating point (I<double>)
-=item longdouble
-Floating point that may be larger than C<double> (I<longdouble>).  This
-type is only available if supported by the C compiler used to build
-L<FFI::Platypus>.  There may be a performance penalty for using this
-type, even if your Perl uses long doubles internally for its number
-value (NV) type, because of the way L<FFI::Platypus> interacts with
-C<libffi>.
-As an argument type either regular number values (NV) or instances of
-L<Math::LongDouble> are accepted.  When used as a return type,
-L<Math::LongDouble> will be used, if you have that module installed.
-Otherwise the return type will be downgraded to whatever your Perl's
-number value (NV) is.
-=item complex_float
-Complex single precision floating point (I<float complex>)
-=item complex_double
-Complex double precision floating point (I<double complex>)
-C<complex_float> and C<complex_double> are only available if supported
-by your C compiler and by libffi.  Complex numbers are only supported in
-very recent versions of libffi, and as of this writing the latest
-production version doesn't work on x86_64.  It does seem to work with
-the latest production version of libffi on 32 bit Intel (x86), and with
-the latest libffi version in git on x86_64.
-=back
-=head3 opaque pointers
-Opaque pointers are simply a pointer to a region of memory that you do
-not manage, and do not know or care about its structure. It is like
-a C<void *> in C.  These types are represented in Perl space as integers
-and get converted to and from pointers by L<FFI::Platypus>.  You may use
-C<pointer> as an alias for C<opaque>, although this is discouraged.
-(The Platypus documentation uses the convention of using "pointer"
-to refer to pointers to known types (see below) and "opaque" as short
-hand for opaque pointer).
-As an example, libarchive defines C<struct archive> type in its header
-files, but does not define its content.  Internally it is defined as a
-C<struct> type, but the caller does not see this.  It is therefore
-opaque to its caller.  There are C<archive_read_new> and
-C<archive_write_new> functions to create a new instance of this opaque
-object and C<archive_read_free> and C<archive_write_free> to destroy
-this objects when you are done.
-C header:
- struct archive;
- struct archive *archive_read_new(void);
- struct archive *archive_write_new(void);
- int archive_free(struct archive *);
- int archive_write_free(struct archive *);
-Perl code:
- $lib->find_lib( lib => 'archive' );
- $ffi->attach(archive_read_new   => []         => 'opaque');
- $ffi->attach(archive_write_new  => []         => 'opaque');
- $ffi->attach(archive_read_free  => ['opaque'] => 'int');
- $ffi->attach(archive_write_free => ['opaque'] => 'int');
-It is often useful to alias an C<opaque> type like this so that you know
-what the object represents:
- $lib->find_lib( lib => 'archive' );
- $ffi->type('opaque' => 'archive');
- $ffi->attach(archive_read_new   => [] => 'archive');
- $ffi->attach(archive_read_free  => ['archive'] => 'int');
- ...
-As a special case, when you pass C<undef> into a function that takes an
-opaque type it will be translated into C<NULL> for C.  When a C function
-returns a NULL pointer, it will be translated back to C<undef>.
-For functions that take a pointer to a void pointer (that is a C<void **>),
-you can use a pointer to an opaque type.  Consider the C code:
- struct archive_entry;
- int archive_read_next_header(struct archive *, struvct archive_entry **);
-Once again the internals of C<archive_entry> are not provided.  Perl code:
- $ffi->type('opaque' => 'archive_entry');
- $ffi->attach(archive_read_next_header => [ 'archive', 'archive_entry*' ] => 'int');
-Now we can call this function
- my $archive = archive_read_new();
- ...  # additional prep for $active is required
- while(1) {
-   my $entry;
-   archive_read_next_header($archive, \$entry);
-   last unless defined $entry;
-   # can now use $entry for other archive_entry_ methods.
- }
-The way C<archive_read_next_header> works, it will return a pointer to the next
-C<archive_entry> object until it gets to the end, when it will return a pointer
-to C<NULL> which will be represented in Perl by a C<undef>.
-There are a number of useful utility functions for dealing with opaque
-types in the L<FFI::Platypus::Memory> module.
-=head2 Objects
-Object types are thin wrappers around two native types: integer and
-C<opaque> types.  They are just blessed references around either of
-those two types so that methods can be defined on them, but when they
-get passed to a Platypus xsub they are converted into the native
-integer or C<opaque> types.  This type is most useful when a API
-provides an OO style interface with an integer or C<opaque> value
-acting as an instance of a class.  There are two detailed examples
-in the main Platypus documentation using libarchive and unix open:
-=over 4
-=item L<FFI::Platypus/libarchive>
-=item L<FFI::Platypus/"unix open">
-=back
-=head2 Strings
- # used when you need a char * or const char *
- $ffi->attach( puts => [ 'string' ] => 'int' );
-The C<string> type is a series of bytes that usually represent a
-series of characters.  They will be NULL terminated for C and passed
-in as a pointer.  This will typically work for APIs that take ASCII
-or UTF-8 strings which are common in Unix environments.
-(Note if you need to handle the native "wide" string for example
-if you need to talk UTF-16 on Windows see L<FFI::Platypus::Type::WideString>).
-(Note if you need to pass in a fixed length string by value (not as
-a pointer) then you can do so using L<FFI::Platypus::Record>).
-(Note that languages like L<Go|FFI::Platypus::Lang::Go> and L<Rust|FFI::Platypus::Lang::Rust> do not use NULL terminated strings
-and need their own string types; see the appropriate language plugins for details)
- # can also be used when you need a void * or const void *
- $ffi->attach( write => ['int', 'string', 'size_t' ] => 'ssizet' );
-The C<string> type can also be used to pass in the start of a buffer
-of arbitrary bytes stored in a Perl scalar.  Because a C<string> is
-passed just as a pointer you will typically need to also pass the
-length of the buffer as a separate argument.  This is necessary because
-buffers could potentially have a NULL in them.
-The pointer passed into C (or other language) is to the content of the
-actual scalar, which means it can modify the content of a scalar.
-B<NOTE>: When used as a return type, the string is I<copied> into a
-new scalar rather than using the original address.  This is due to
-the ownership model of scalars in Perl, but it is also most of the
-time what you want.
-This can be problematic when a function returns a string that the callee
-is expected to free.  Consider the functions:
- char *
- get_string()
- {
-   char *buffer;
-   buffer = malloc(20);
-   strcpy(buffer, "Perl");
- }
- void
- free_string(char *buffer)
- {
-   free(buffer);
- }
-This API returns a string that you are expected to free when you are
-done with it.  (At least they have provided an API for freeing the
-string instead of expecting you to call libc free)!  A simple binding
-to get the string would be:
- $ffi->attach( get_string => [] => 'string' );  # memory leak
- my $str = get_string();
-Which will work to a point, but the memory allocated by get_string
-will leak.  Instead you need to get the opaque pointer, cast it to
-a string and then free it.
- $ffi->attach( get_string => [] => 'opaque' );
- $ffi->attach( free_string => ['opaque'] => 'void' );
- my $ptr = get_string();
- my $str = $ffi->cast( 'opaque' => 'string', $ptr );  # copies the string
- free_string($ptr);
-If you are doing this sort of thing a lot, it can be worth adding a
-custom type:
- $ffi->attach( free_string => ['opaque'] => 'void' );
- $ffi->custom_type( 'my_string' => {
-   native_type => 'opaque',
-   native_to_perl => sub {
-     my($ptr) = @_;
-     my $str = $ffi->cast( 'opaque' => 'string', $ptr ); # copies the string
-     free_string($ptr);
-     $str;
-   }
- });
- $ffi->attach( get_string => [] => 'my_string' );
- my $str = get_string();
-Since version 0.62, pointers and arrays to strings are supported as a
-first class type.  Prior to that L<FFI::Platypus::Type::StringArray>
-and L<FFI::Platypus::Type::StringPointer> could be used, though their
-use in new code is discouraged.
- $ffi->attach( foo => ['string[]'] => 'void' );
- foo( [ 'array', 'of', 'strings' ] );
- $ffi->attach( bar => ['string*'] => 'void' );
- my $string = 'baz';
- bar( \$string );  # $string may be modified.
-Strings are not allowed as return types from closure.  This, again
-is due to the ownership model of scalars in Perl.  (There is no way
-for Perl to know when calling language is done with the memory allocated
-to the string).  Consider the API:
- typedef const char *(*get_message_t)(void);
- void
- print_message(get_message_t get_message)
- {
-   const char *str;
-   str = get_message();
-   printf("message = %s\n", str);
- }
-It feels like this should be able to work:
- $ffi->type('()->string' => 'get_message_t'); # not ok
- $ffi->attach( print_message => ['get_message_t'] => 'void' );
- my $get_message = $ffi->closure(sub {
-   return "my message";
- });
- print_message($get_message);
-If the type declaration for C<get_message_t> were legal, then this
-script would likely segfault or in the very least corrupt memory.
-The problem is that once C<"my message"> is returned from the closure
-Perl doesn't have a reference to it anymore and will free it.
-To do this safely, you have to keep a reference to the scalar around
-and return an opaque pointer to the string using a cast.
- $ffi->type('()->opaque' => 'get_message_t');
- $ffi->attach( print_message => ['get_message_t'] => 'void' );
- my $get_message => $ffi->closure(sub {
-   our $message = "my message";  # needs to be our so that it doesn't
-                                 # get free'd
-   my $ptr = $ffi->cast('string' => 'opaque', $message);
-   return $ptr;
- });
- print_message($get_message);
-Another type of string that you may run into with some APIs is the
-so called "wide" string.  In your C code if you see C<wchar_t*>
-or C<const wchar_t*> or if in Win32 API code you see C<LPWSTR>
-or C<LPCWSTR>.  Most commonly you will see these types when working
-with the Win32 API, but you may see them in Unix as well.  These
-types are intended for dealing with Unicode, but they do not use
-the same UTF-8 format used by Perl internally, so they need to be
-converted.  You can do this manually by allocating the memory
-and using the L<Encode> module, but the easier way is to use
-either L<FFI::Platypus::Type::WideString> or
-L<FFI::Platypus::Lang::Win32>, which handle the memory allocation
-and conversion for you.
-String types can be defined to have a fixed length using a trailing
-parenthetical like so C<string(10)>.  For arguments this has little
-practical effect since the strings are passed as pointers anyway,
-but does impact return values.  If a function that returns a C<string(10)>
-type returns a string that is not NULL terminated, only the first ten bytes
-will be returned in the result.
-Internally fixed length strings are implemented the same as
-classless record types (that is to say C<string(10)> is identically
-internally to C<record(10)*>).
-For the 1.00 Platypus API, the C<string(10)> type was specified as
-a pointer (that is C<string(10)*>).  This was a mistake, but you
-can still use the latter as an alias for the correct form in the
-2.00 API.
-=head2 Pointers and Arrays of Strings
-As of the 1.00 Platypus API, you can specify pointers to strings
-(C<string*>) and arrays of strings (C<string[10]>).  Since strings
-themselves are passed as pointers, this means these types are
-passed in as pointers to pointers.  If the pointer to the string
-is changed then when the function returns the scalar or array
-will be updated as well.
-=head2 Pointer / References
-In C you can pass a pointer to a variable to a function in order
-accomplish the task of pass by reference.  In Perl the same task is
-accomplished by passing a reference (although you can also modify the
-argument stack thus Perl supports proper pass by reference as well).
-With L<FFI::Platypus> you can define a pointer to any native, string
-or record type.  You cannot (at least not yet) define a pointer to
-a pointer or a pointer to an array or any other type not otherwise
-supported.  When passing in a pointer to something you must make sure
-to pass in a reference to a scalar, or C<undef> (C<undef> will be
-translated int C<NULL>).
-If the C code makes a change to the value pointed to by the pointer, the
-scalar will be updated before returning to Perl space.  Example, with C
-code.
- /* foo.c */
- void increment_int(int *value)
- {
-   if(value != NULL)
-     (*value)++;
-   else
-     fprintf(stderr, "NULL pointer!\n");
- }
- # foo.pl
- use FFI::Platypus 2.00;
- my $ffi = FFI::Platypus->new( api => 2 );
- $ffi->lib('libfoo.so'); # change to reflect the dynamic lib
-                         # that contains foo.c
- $ffi->type('int*' => 'int_p');
- $ffi->attach(increment_int => ['int_p'] => 'void');
- my $i = 0;
- increment_int(\$i);   # $i == 1
- increment_int(\$i);   # $i == 2
- increment_int(\$i);   # $i == 3
- increment_int(undef); # prints "NULL pointer!\n"
-Older versions of Platypus did not support pointers to strings or records.
-=head2 Records
-Records are structured data of a fixed length.  In C they are called
-C<struct>s.
-For most C structured data, as long as you do not need to a record
-by value, L<FFI::C> is the better choice.  Briefly, L<FFI::C> supports
-C<struct>, C<union>, and arrays of C<struct> and C<unions>.  L<FFI::C>
-does not support passing by value.  The reminder of this section will
-discuss only the C<record> type.
-To declare a record type, use C<record>:
- $ffi->type( 'record (42)' => 'my_record_of_size_42_bytes' );
-The easiest way to mange records with Platypus is by using
-L<FFI::Platypus::Record> to define a record layout for a record class.
-Here is a brief example:
- package Unix::TimeStruct;
- use FFI::Platypus 2.00;
- use FFI::Platypus::Record;
- record_layout_1(qw(
-     int    tm_sec
-     int    tm_min
-     int    tm_hour
-     int    tm_mday
-     int    tm_mon
-     int    tm_year
-     int    tm_wday
-     int    tm_yday
-     int    tm_isdst
-     long   tm_gmtoff
-     string tm_zone
- ));
- my $ffi = FFI::Platypus->new( api => 2 );
- $ffi->lib(undef);
- # define a record class Unix::TimeStruct and alias it to "tm"
- $ffi->type("record(Unix::TimeStruct)*" => 'tm');
- # attach the C localtime function as a constructor
- $ffi->attach( localtime => ['time_t*'] => 'tm', sub {
-   my($inner, $class, $time) = @_;
-   $time = time unless defined $time;
-   $inner->(\$time);
- });
- package main;
- # now we can actually use our Unix::TimeStruct class
- my $time = Unix::TimeStruct->localtime;
- printf "time is %d:%d:%d %s\n",
-   $time->tm_hour,
-   $time->tm_min,
-   $time->tm_sec,
-   $time->tm_zone;
-For more detailed usage, see L<FFI::Platypus::Record>.
-Platypus does not manage the structure of a record (that is up to you),
-it just keeps track of their size and makes sure that they are copied
-correctly when used as a return type.  A record in Perl is just a string
-of bytes stored as a scalar.  In addition to defining a record layout
-for a record class, there are a number of tools you can use manipulate
-records in Perl, two notable examples are L<pack and unpack|perlpacktut>
-and L<Convert::Binary::C>.
-Here is an example with commentary that uses L<Convert::Binary::C> to
-extract the component time values from the C C<localtime> function, and
-then smushes them back together to get the original C<time_t> (an
-integer).
- use Convert::Binary::C;
- use FFI::Platypus 2.00;
- use Data::Dumper qw( Dumper );
- my $c = Convert::Binary::C->new;
- # Alignment of zero (0) means use
- # the alignment of your CPU
- $c->configure( Alignment => 0 );
- # parse the tm record structure so
- # that Convert::Binary::C knows
- # what to spit out and suck in
- $c->parse(<<ENDC);
- struct tm {
-   int tm_sec;
-   int tm_min;
-   int tm_hour;
-   int tm_mday;
-   int tm_mon;
-   int tm_year;
-   int tm_wday;
-   int tm_yday;
-   int tm_isdst;
-   long int tm_gmtoff;
-   const char *tm_zone;
- };
- ENDC
- # get the size of tm so that we can give it
- # to Platypus
- my $tm_size = $c->sizeof("tm");
- # create the Platypus instance and create the appropriate
- # types and functions
- my $ffi = FFI::Platypus->new( api => 2 );
- $ffi->lib(undef);
- $ffi->type("record($tm_size)*" => 'tm');
- $ffi->attach( [ localtime => 'my_localtime' ] => ['time_t*'] => 'tm'     );
- $ffi->attach( [ time      => 'my_time'      ] => ['tm']      => 'time_t' );
- # ===============================================
- # get the tm struct from the C localtime function
- # note that we pass in a reference to the value that time
- # returns because localtime takes a pointer to time_t
- # for some reason.
- my $time_hashref = $c->unpack( tm => my_localtime(\time) );
- # tm_zone comes back from Convert::Binary::C as an opaque,
- # cast it into a string.  We localize it to just this do
- # block so that it will be a pointer when we pass it back
- # to C land below.
- do {
-   local $time_hashref->{tm_zone} = $ffi->cast(opaque => string => $time_hashref->{tm_zone});
-   print Dumper($time_hashref);
- };
- # ===============================================
- # convert the tm struct back into an epoch value
- my $time = my_time( $c->pack( tm => $time_hashref ) );
- print "time      = $time\n";
- print "perl time = ", time, "\n";
-You can also link a record type to a class.  It will then be accepted
-when blessed into that class as an argument passed into a C function,
-and when it is returned from a C function it will be blessed into that
-class.  Basically:
- $ffi->type( 'record(My::Class)*' => 'my_class' );
- $ffi->attach( my_function1 => [ 'my_class' ] => 'void' );
- $ffi->attach( my_function2 => [ ] => 'my_class' );
-The only thing that your class MUST provide is either a
-C<ffi_record_size> or C<_ffi_record_size> class method that returns the
-size of the record in bytes.
-Contrast a record type which is stored as a scalar string of bytes in
-Perl to an opaque pointer which is stored as an integer in Perl.  Both
-are treated as pointers in C functions.  The situations when you usually
-want to use a record are when you know ahead of time what the size of
-the object that you are working with and probably something about its
-structure.  Because a function that returns a structure copies the
-structure into a Perl data structure, you want to make sure that it is
-okay to copy the record objects that you are dealing with if any of your
-functions will be returning one of them.
-Opaque pointers should be used when you do not know the size of the
-object that you are using, or if the objects are created and free'd
-through an API interface other than C<malloc> and C<free>.
-The examples in this section actually use pointers to records (note
-the trailing star C<*> in the declarations).  Most programming languages
-allow you to pass or return a record as either pass-by-value or as a
-pointer (pass-by-reference).
-C code:
- struct { int a; } foo_t;
- void pass_by_value_example( struct foo_t foo );
- void pass_by_reference_example( struct foo_t *foo );
-Perl code:
- {
-   package Foo;
-   use FFI::Platypus::Record;
-   record_layout_1( int => 'a' );
- }
- $ffi->type( 'Record(Foo)' => 'foo_t' );
- $ffi->attach( pass_by_value_example => [ 'foo_t' ] => 'void' );
- $ffi->attach( pass_by_reference_example => [ 'foo_t*' ] => 'void' );
-As with strings, functions that return a pointer to a record are actually
-copied.
-C code:
- struct foo_t *return_struct_pointer_example();
-Perl code:
- $ffi->attach( return_struct_pointer_example => [] => 'foo_t*' );
- my $foo = return_struct_pointer_example();
- # $foo is a copy of the record returned by the function.
-As with strings, if the API expects you to free the record it returns
-(it is misbehaving a little, but lets set that aside), then you can
-work around this by returning an C<opaque> type, casting to the
-record, and finally freeing the original pointer.
- use FFI::Platypus::Memory qw( free );
- $ffi->attach( return_struct_pointer_example => [] => 'opaque' );
- my $foo_ptr = return_struct_pointer_example();
- my $foo = $ffi->cast( 'opaque' => 'foo_t*', $foo_ptr );
- free $foo_ptr;
-You can pass records into a closure, but care needs to be taken.
-Records passed into a closure are read-only inside the closure,
-including C<string rw> members.  Although you can pass a "pointer"
-to a record into a closure, because of limitations of the
-implementation you actually have a copy, so all records passed
-into closures are passed by-value.
-Note that a record that does not have a class (classless) and is
-defined instead using a length is internally identical to fixed
-strings.  That is to say C<string(10)> and C<record(10)*> are
-identical.
-=head2 Fixed length arrays
-Fixed length arrays of native types and strings are supported by
-L<FFI::Platypus>.  Like pointers, if the values contained in the
-array are updated by the C function these changes will be reflected
-when it returns to Perl space.  An example of using this is the
-Unix C<pipe> command which returns a list of two file descriptors
-as an array.
- use FFI::Platypus 2.00;
- my $ffi = FFI::Platypus->new( api => 2 );
- $ffi->lib(undef);
- $ffi->attach([pipe=>'mypipe'] => ['int[2]'] => 'int');
- my @fd = (0,0);
- mypipe(\@fd);
- my($fd1,$fd2) = @fd;
- print "$fd1 $fd2\n";
-Because of the way records are implemented, an array of records
-does not make sense and is not currently supported.
-=head2 Variable length arrays
-[version 0.22]
-Variable length arrays are supported for argument types can also be
-specified by using the C<[]> notation but by leaving the size empty:
- $ffi->type('int[]' => 'var_int_array');
-When used as an argument type it will probe the array reference that you
-pass in to determine the correct size.  Usually you will need to
-communicate the size of the array to the C code.  One way to do this is
-to pass the length of the array in as an additional argument.  For
-example the C code:
- int
- sum(int *array, int size)
- {
-   int total, i;
-   for (i = 0, total = 0; i < size; i++)
-   {
-     total += array[i];
-   }
-   return total;
- }
-Can be called from Perl like this:
- use FFI::Platypus 2.00;
- my $ffi = FFI::Platypus->new( api => 2 );
- $ffi->lib('./var_array.so');
- $ffi->attach( sum => [ 'int[]', 'int' ] => 'int' );
- my @list = (1..100);
- print sum(\@list, scalar @list), "\n";
-Another method might be to have a special value, such as 0 or NULL
-indicate the termination of the array.
-Because of the way records are implemented, an array of records
-does not make sense and is not currently supported.
-=head2 Closures
-A closure (sometimes called a "callback", we use the C<libffi>
-terminology) is a Perl subroutine that can be called from C.  In order
-to be called from C it needs to be passed to a C function.  To define
-the closure type you need to provide a list of argument types and a
-return type.  Currently only native types (integers, floating point
-values, opaque), strings and records (by-value; you can pass a pointer
-to a record, but due to limitations of the record implementation this
-is actually a copy) are supported as closure argument types, and only
-native types and records (by-value; pointer records and records with
-string pointers cannot be returned from a closure) are supported as
-closure return types.  Inside the closure any records passed in are
-read-only.
-We plan to add other types, though they can be converted using the Platypus
-C<cast> or C<attach_cast> methods.
-Here is an example, with C code:
- /*
-  * closure.c - on Linux compile with: gcc closure.c -shared -o closure.so -fPIC
-  */
- #include <stdio.h>
- typedef int (*closure_t)(int);
- closure_t my_closure = NULL;
- void set_closure(closure_t value)
- {
-   my_closure = value;
- }
- int call_closure(int value)
- {
-   if(my_closure != NULL)
-     return my_closure(value);
-   else
-     fprintf(stderr, "closure is NULL\n");
- }
-And the Perl code:
- use FFI::Platypus 2.00;
- my $ffi = FFI::Platypus->new( api => 2 );
- $ffi->lib('./closure.so');
- $ffi->type('(int)->int' => 'closure_t');
- $ffi->attach(set_closure => ['closure_t'] => 'void');
- $ffi->attach(call_closure => ['int'] => 'int');
- my $closure1 = $ffi->closure(sub { $_[0] * 2 });
- set_closure($closure1);
- print  call_closure(2), "\n"; # prints "4"
- my $closure2 = $ffi->closure(sub { $_[0] * 4 });
- set_closure($closure2);
- print call_closure(2), "\n"; # prints "8"
-If you have a pointer to a function in the form of an C<opaque> type,
-you can pass this in place of a closure type:
- use FFI::Platypus 2.00;
- my $ffi = FFI::Platypus->new( api => 2 );
- $ffi->lib('./closure.so');
- $ffi->type('(int)->int' => 'closure_t');
- $ffi->attach(set_closure => ['closure_t'] => 'void');
- $ffi->attach(call_closure => ['int'] => 'int');
- my $closure = $ffi->closure(sub { $_[0] * 6 });
- my $opaque = $ffi->cast(closure_t => 'opaque', $closure);
- set_closure($opaque);
- print call_closure(2), "\n"; # prints "12"
-The syntax for specifying a closure type is a list of comma separated
-types in parentheticals followed by a narrow arrow C<-E<gt>>, followed
-by the return type for the closure.  For example a closure that takes a
-pointer, an integer and a string and returns an integer would look like
-this:
- $ffi->type('(opaque, int, string) -> int' => 'my_closure_type');
-Care needs to be taken with scoping and closures, because of the way
-Perl and C handle responsibility for allocating memory differently.
-Perl keeps reference counts and frees objects when nothing is
-referencing them.  In C the code that allocates the memory is considered
-responsible for explicitly free'ing the memory for objects it has
-created when they are no longer needed.  When you pass a closure into a
-C function, the C code has a pointer or reference to that object, but it
-has no way up letting Perl know when it is no longer using it. As a
-result, if you do not keep a reference to your closure around it will be
-free'd by Perl and if the C code ever tries to call the closure it will
-probably SIGSEGV.  Thus supposing you have a C function C<set_closure>
-that takes a Perl closure, this is almost always wrong:
- set_closure($ffi->closure({ $_[0] * 2 }));  # BAD
-In some cases, you may want to create a closure shouldn't ever be
-free'd.  For example you are passing a closure into a C function that
-will retain it for the lifetime of your application.  You can use the
-sticky method to keep the closure, without the need to keep a reference
-of the closure:
- {
-   my $closure = $ffi->closure(sub { $_[0] * 2 });
-   $closure->sticky;
-   set_closure($closure); # OKAY
- }
- # closure still exists and is accesible from C, but
- # not from Perl land.
-=head2 Custom Types
-=head3 Custom Types in Perl
-Platypus custom types are the rough analogue to typemaps in the XS
-world.  They offer a method for converting Perl types into native types
-that the C<libffi> can understand and pass on to the C code.
-=head4 Example 1: Integer constants
-Say you have a C header file like this:
- /* possible foo types: */
- #define FOO_STATIC  1
- #define FOO_DYNAMIC 2
- #define FOO_OTHER   3
- typedef int foo_t;
- void foo(foo_t foo);
- foo_t get_foo();
-The challenge is here that once the source is processed by the C
-pre-processor the name/value mappings for these C<FOO_> constants
-are lost.  There is no way to fetch them from the library once it
-is compiled and linked.
-One common way of implementing this would be to create and export
-constants in your Perl module, like this:
- package Foo;
- use FFI::Platypus 2.00;
- use Exporter qw( import );
- our @EXPORT_OK = qw( FOO_STATIC FOO_DYNAMIC FOO_OTHER foo get_foo );
- use constant FOO_STATIC  => 1;
- use constant FOO_DYNAMIC => 2;
- use constant FOO_OTHER   => 3;
- my $ffi = FFI::Platypus->new( api => 2 );
- $ffi->attach(foo     => ['int'] => 'void');
- $ffi->attach(get_foo => []      => 'int');
-Then you could use the module thus:
- use Foo qw( foo FOO_STATIC );
- foo(FOO_STATIC);
-If you didn't want to rely on integer constants or exports, you could
-also define a custom type, and allow strings to be passed into your
-function, like this:
- package Foo;
- use FFI::Platypus 2.00;
- our @EXPORT_OK = qw( foo get_foo );
- my %foo_types = (
-   static  => 1,
-   dynamic => 2,
-   other   => 3,
- );
- my %foo_types_reverse = reverse %foo_types;
- my $ffi = FFI::Platypus->new( api => 2 );
- $ffi->custom_type(foo_t => {
-   native_type    => 'int',
-   native_to_perl => sub {
-     $foo_types{$_[0]};
-   },
-   perl_to_native => sub {
-     $foo_types_reverse{$_[0]};
-   },
- });
- $ffi->attach(foo     => ['foo_t'] => 'void');
- $ffi->attach(get_foo => []        => 'foo_t');
-Now when an argument of type C<foo_t> is called for it will be converted
-from an appropriate string representation, and any function that returns
-a C<foo_t> type will return a string instead of the integer
-representation:
- use Foo;
- foo('static');
-If the library that you are using has a lot of these constants you can
-try using L<Convert::Binary::C> or another C header parser to obtain
-the appropriate name/value pairings for the constants that you need.
-=head4 Example 2: Blessed references
-Supposing you have a C library that uses an opaque pointer with a pseudo
-OO interface, like this:
- typedef struct foo_t;
- foo_t *foo_new();
- void foo_method(foo_t *, int argument);
- void foo_free(foo_t *);
-One approach to adapting this to Perl would be to create a OO Perl
-interface like this:
- package Foo;
- use FFI::Platypus 2.00;
- use FFI::Platypus::API qw( arguments_get_string );
- my $ffi = FFI::Platypus->new( api => 2 );
- $ffi->custom_type(foo_t => {
-   native_type    => 'opaque',
-   native_to_perl => sub {
-     my $class = arguments_get_string(0);
-     bless \$_[0], $class;
-   }
-   perl_to_native => sub { ${$_[0]} },
- });
- $ffi->attach([ foo_new => 'new' ] => [ 'string' ] => 'foo_t' );
- $ffi->attach([ foo_method => 'method' ] => [ 'foo_t', 'int' ] => 'void');
- $ffi->attach([ foo_free => 'DESTROY' ] => [ 'foo_t' ] => 'void');
- my $foo = Foo->new;
-Here we are blessing a reference to the opaque pointer when we return
-the custom type for C<foo_t>, and dereferencing that reference before we
-pass it back in.  The function C<arguments_get_string> queries the C
-arguments to get the class name to make sure the object is blessed into
-the correct class (for more details on the custom type API see
-L<FFI::Platypus::API>), so you can inherit and extend this class like a
-normal Perl class.  This works because the C "constructor" ignores the
-class name that we pass in as the first argument.  If you have a C
-"constructor" like this that takes arguments you'd have to write a
-wrapper for new.
-A good example of a C library that uses this pattern, including
-inheritance is C<libarchive>. Platypus comes with a more extensive
-example in C<examples/archive.pl> that demonstrates this.
-=head4 Example 3: Pointers with pack / unpack
-TODO
-See example L<FFI::Platypus::Type::StringPointer>.
-=head4 Example 4: Custom Type modules and the Custom Type API
-TODO
-See example L<FFI::Platypus::Type::PointerSizeBuffer>.
-=head4 Example 5: Custom Type on CPAN
-You can distribute your own Platypus custom types on CPAN, if you think
-they may be applicable to others.  The default namespace is prefix with
-C<FFI::Platypus::Type::>, though you can stick it anywhere (under your
-own namespace may make more sense if the custom type is specific to your
-application).
-A good example and pattern to follow is
-L<FFI::Platypus::Type::StringArray>.
-=head1 SEE ALSO
-=over 4
-=item L<FFI::Platypus>
-Main platypus documentation.
-=item L<FFI::Platypus::API>
-Custom types API.
-=item L<FFI::Platypus::Type::StringPointer>
-String pointer type.
-=back
-=head1 AUTHOR
-Author: Graham Ollis E<lt>plicease@cpan.orgE<gt>
-Contributors:
-Bakkiaraj Murugesan (bakkiaraj)
-Dylan Cali (calid)
-pipcet
-Zaki Mughal (zmughal)
-Fitz Elliott (felliott)
-Vickenty Fesunov (vyf)
-Gregor Herrmann (gregoa)
-Shlomi Fish (shlomif)
-Damyan Ivanov
-Ilya Pavlov (Ilya33)
-Petr Písař (ppisar)
-Mohammad S Anwar (MANWAR)
-Håkon Hægland (hakonhagland, HAKONH)
-Meredith (merrilymeredith, MHOWARD)
-Diab Jerius (DJERIUS)
-Eric Brine (IKEGAMI)
-szTheory
-José Joaquín Atria (JJATRIA)
-Pete Houston (openstrike, HOUSTON)
-Lukas Mai (MAUKE)
-=head1 COPYRIGHT AND LICENSE
-This software is copyright (c) 2015-2022 by Graham Ollis.
-This is free software; you can redistribute it and/or modify it under
-the same terms as the Perl 5 programming language system itself.
-=cut