NAME

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

VERSION

version 0.006

SYNOPSIS

In your typemap

My::Object	T_MAGICEXT

In your XS:

static const MGVTBL My__Object_magic = {
    .svt_dup  = object_dup,
    .svt_free = object_free
};

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::MagicExt is a typemap bundle that provides T_MAGICEXT, a typemap that stores the object just like T_MAGIC does, but additionally attaches a magic vtable (type MGVTBL) with the name ${type}_magic (e.g. My__Object_magic for a value of type My::Object) 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) {
    struct Object* object = (struct Object*)magic->mg_ptr;
    object_refcount_increment(object);
    return 0;
}

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

This is useful to create objects that handle thread cloning correctly and effectively. If the object may be destructed by another thread, it should be allocated with the PerlSharedMem_malloc family of allocators.

DEPENDENCIES

This typemap requires ExtUtils::ParseXS 3.50 or higher as a build dependency.

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::MagicExt

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('MagicExt')"

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.