The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.


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


version 0.03



 #include <string.h>
 typedef struct { char buffer[100] } foo_t;
 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;


 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})
 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.


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).


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


Graham Ollis <>


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.