NAME

FFI::Platypus::Type::PtrObject - Platypus custom type for an object wrapped around an opaque pointer

VERSION

version 0.03

SYNOPSIS

C:

#include <string.h>

typedef struct { char buffer[100] } foo_t;

void
set(foo_t *self, const char *value)
{
  strncpy(self->buffer, value, 100);
}

const char *
get(foo_t *self)
{
  return self->buffer;
}

foo_t *
clone(foo_t *self)
{
  foo_t *clone;
  clone = malloc(100);
  memcpy(clone->buffer, self->buffer, 100);
  return clone;
}

Perl:

my $ffi = FFI::Platypus->new( api => 1 );
$ffi->bundle;  # See FFI::Platypus::Bundle
$ffi->load_custom_type('::PtrObject', 'foo_t', 'Foo');

package Foo {
  use FFI::Platypus::Memory qw( malloc free );

  sub new
  {
    my $class = shift;
    bless {
      ptr => malloc(100),
    }, $class;
  }

  $ffi->attach( set   => ['foo_t','string']    );
  $ffi->attach( get   => ['foo_t'] => 'string' );
  $ffi->attach( clone => ['foo_t'] => 'foo_t'  );

  sub take_ownership
  {
    my($self) = @_;
    return delete $self->{ptr};
  }

  sub DESTROY
  {
    my($self) = @_;
    if(defined $self->{ptr})
    {
      free($self->{ptr});
    }
  }
}

my $foo = Foo->new;
$foo->set("hello there");
print $foo->get, "\n";    # hello there
my $bar = $foo->clone;
print $bar->get, "\n";    # hello there

Foo::get(undef);    # undef is not a Foo, throws exception

my $baz = bless { ptr => 0xdeadbeaf }, 'Baz';
Foo::get($baz);     # $baz is not a Foo, throws exception

# by calling take ownership, the pointer will be
# removed from $foo, so we now own the pointer.
my $ptr = $foo->take_ownership;

$foo->get;  # $foo no longer owns its pointer, throws an exception

# since $foo no longer is tracking the memory, we should free it
# manually ourselves.
use FFI::Platypus::Memory qw( free );
free $ptr;

# $bar will free its memory when it falls out of scope automatically
# since it still owns its pointer.

DESCRIPTION

This is a helper type for FFI::Platypus that handles type checking for the common pattern where a Perl class is a simple wrapper around an opaque pointer. The class should be implemented as a hash reference, and the pointer itself is expected to be stored on the ptr key. If the caller of the interface (Perl) is responsible for cleaning up the memory, then it normally should be done in the DESTROY method (as above).

If you do not pass in the correct type, it will be detected before the C code is called and an exception will be thrown. (otherwise you would probably get a segment violation SEGV).

CAVEATS

Care needs to be taken that only the responsible party frees its pointers.

AUTHOR

Graham Ollis <plicease@cpan.org>

COPYRIGHT AND LICENSE

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