/ 
FFI-C-0.15
River stage two • 11 direct dependents • 25 total dependents
/ FFI::C::Util

NAME

FFI::C::Util - Utility functions for dealing with structured C data

VERSION

version 0.15

SYNOPSIS

use FFI::C::Util qw( perl_to_c take );
use FFI::C::StructDef;
use FFI::Platypus::Memory qw( free );

my $def = FFI::C::StructDef->new(
  members => [
    x => 'uint8',
    y => 'sint64',
  ],
);
my $inst = $def->create;

# initalize members
perl_to_c($inst, { x => 1, y => 2 });

# take ownership
my $ptr = take $inst;

# since we took ownership, we are responsible for freeing the memory:
free $ptr;

DESCRIPTION

This module provides some useful utility functions for dealing with the various def instances provided by FFI::C

FUNCTIONS

perl_to_c

perl_to_c $instance, \%values;  # for Struct/Union
perl_to_c $instance, \@values;  # for Array

This function initializes the members of an instance.

c_to_perl

my $perl = c_to_perl $instance;

This function takes an instance and returns the nested members as Perl data structures.

owned

my $bool = owned $instance;

Returns true of the $instance owns its allocated memory. That is, it will free up the allocated memory when it falls out of scope. Reasons an instance might not be owned are:

the instance is nested inside another object that owns the memory
the instance was returned from a C function that owns the memory
ownership was taken away by the take function below.

take

my $ptr = take $instance;

This function takes ownership of the instance pointer, and returns the opaque pointer. This means a couple of things:

$instance will not free its data automatically

You should call free on it manually to free the memory it is using.

$instance cannot be used anymore

So don't try to get/set any of its members, or pass it into a function.

The returned pointer can be cast into something else or passed into a function that takes an opaque argument.

addressof

[version 0.11]

my $ptr = addressof $instance;

This function returns the address (as an opaque type) of the instance object. This is similar to take above in that it gets you the address of the object, but doesn't take ownership of it, so care needs to be taken when using $ptr that the object is still allocated.

set_array_count

set_array_count $inst, $count;

This function sets the element count on a variable array returned from C (where normally there is no way to know from just the return value). If you try to set a count on a non-array or a fixed sized array an exception will be thrown.

SEE ALSO

FFI::C
FFI::C::Array
FFI::C::ArrayDef
FFI::C::Def
FFI::C::File
FFI::C::PosixFile
FFI::C::Struct
FFI::C::StructDef
FFI::C::Union
FFI::C::UnionDef
FFI::C::Util
FFI::Platypus::Record

AUTHOR

Graham Ollis <plicease@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2020-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.