NAME

ExtUtils::Typemaps::Magic - Typemap for storing objects in magic

VERSION

version 0.007

SYNOPSIS

In your typemap

 My::Object     T_MAGIC

In your XS:

 typedef struct object_t* My__Object;

 MODULE = My::Object    PACKAGE = My::Object    PREFIX = object_

 My::Object object_new(int argument)

 int object_baz(My::Object self)

DESCRIPTION

ExtUtils::Typemaps::Magic is a typemap bundle that provides T_MAGIC, a drop-in replacement for T_PTROBJ except that it hides the value of the pointer from pure-perl code by storing it in attached magic. In particular that means the pointer won't be serialized/deserialized (this is usually a good thing because after deserialization the pointer is probably not valid). Note that like T_PTROBJ, you probably need a DESTROY method to destroy and free the buffer, and this is not thread cloning safe without further measures.

DEPENDENCIES

If your module supports perls older than 5.14, it is recommended to include ppport.h to provide mg_findext. E.g.

 #define NEED_mg_findext
 #include "ppport.h"

INCLUSION

To use this typemap template you need to include it into your local typemap. The easiest way to do that is to use the typemap script in App::typemap. E.g.

 typemap --merge ExtUtils::Typemaps::Magic

If you author using Dist::Zilla you can use Dist::Zilla::Plugin::Typemap instead.

Alternatively, you can include it at runtime by adding the following to your XS file:

 INCLUDE_COMMAND: $^X -MExtUtils::Typemaps::Cmd -e "print embeddable_typemap('Magic')"

That does require adding a build time dependency on this module.

AUTHOR

Leon Timmermans <leont@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2023 by Leon Timmermans.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.