/ 
ExtUtils-Typemaps-Magic-0.002
River stage zero No dependents
/ ExtUtils::Typemaps::Magic

NAME

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

VERSION

version 0.002

SYNOPSIS

use ExtUtils::Typemaps::Magic;
# First, read my own type maps:
my $private_map = ExtUtils::Typemaps->new(file => 'my.map');

# Then, get the Magic set and merge it into my maps
my $map = ExtUtils::Typemaps::Magic->new;
$private_map->merge(typemap => $map);

# Now, write the combined map to an output file
$private_map->write(file => 'typemap');

DESCRIPTION

ExtUtils::Typemaps::Magic is an ExtUtils::Typemaps subclass that provides two magic based mappings for objects.

T_MAGIC

This is essentially 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 thing because after deserialization the pointer is probably not valid).

T_MAGICEXT

This stores the object just like T_MAGIC does, but additionally attaches a magic vtable (type MGVTBL) with the name ${type}_magic (e.g. Foo__Bar_magic for a value of type Foo::Bar) to the value. This is mainly useful for adding free (destruction) and dup (thread cloning) callbacks. The details of how these work is explained in perlguts, but it might look something like this:

static int object_dup(pTHX_ MAGIC* magic, CLONE_PARAMS* params) {
    PERL_UNUSED_VAR(params);
    object_refcount_increment((struct Object*)magic->mg_ptr);
    return 0;
}

static int object_free(pTHX_ SV* sv, MAGIC* magic) {
    PERL_UNUSED_VAR(sv);
    object_refcount_decrement((struct Object*)magic->mg_ptr);
    return 0;
}

static const MGVTBL My__Object_magic = { NULL, NULL, NULL, NULL, object_free, NULL, object_dup, NULL };

This is useful to create objects that handle thread cloning correctly and effectively.

DEPENDENCIES

The T_MAGICEXT typemap requires ExtUtils::ParseXS 3.50 or higher.

On perls older than 5.14, this will require ppport.h to provide mg_findext.

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.