javonet-ruby-sdk 2.4.10 → 2.4.11

data/lib/javonet-ruby-sdk/Binaries/Perl/MacOs/X64/deps/lib/perl5/darwin-thread-multi-2level/FFI/Platypus/Type.pm

@@ -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.09'; # 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.09
-
-=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