NAME

XS::MagicExt - Provides PERL_MAGIC_ext manipulators for XS modules

VERSION

This document describes XS::MagicExt version 0.05.

SYNOPSIS

        # in Makefile.PL
        requires_xs 'XS::MagicExt'; # done by Module::Install::XSUtil

        # in YourModule.pm
        use XS::MagicExt;

        /* Then, in YourModule.xs */

        #include "magic_ext.h"

        static MGVTBL id;

        /* ... */
        void foo(pTHX_ SV* sv){
                SV* obj = newSViv(42);
                /* ... */

                mg = mgx_attach(sv, &id, obj);

                mg = mgx_find(sv, &id);
                mg = MGX_FIND(sv, &id);
                mg = mgx_get(sv, &id);

                if(SvOK(MG_obj(mg))){
                        /* ... */
                }

                mgx_detach(sv, &id);
        }

DESCRIPTION

XS::MagicExt provides MAGIC manipulators for XS modules.

MAGIC manipulators are an interface to sv_magicext(), mg_find(), and sv_unmagic(), which distinguish magic identities from others' MAGICs by MGVTBL.

FUNCTIONS

MAGIC* mgx_attach_with_ptr(SV* sv, MGVTBL* id, SV* obj, void* ptr, I32 len)

Attaches a MAGIC identified by id to sv with obj and ptr / len.

Similar to sv_magicext(sv, obj, PERL_MAGIC_ext, id, ptr, len), but does not increase the refcount of obj.

MAGIC* mgx_attach_with_sv(SV* sv, MGVTBL* id, SV* obj, SV* data)

Attaches a MAGIC identified by id to sv with obj and data, not increasing the refcount of data.

The same as mgx_attach_with_ptr(sv, id, obj, (SV*)ptr, HEf_SVKEY).

MAGIC* mgx_attach(SV* sv, MGVTBL* id, SV* obj)

Attaches a MAGIC identified by id to sv with obj.

The same as mgx_attach_with_ptr(sv, id, obj, NULL, 0).

MAGIC* mgx_find(SV* sv, const MGVTBL* id)

Finds a MAGIC identified by id.

If not found, it will return NULL.

MAGIC* mgx_get(SV* sv, const MGVTBL* id)

Finds a MAGIC identified by id.

If not found, it will die.

void mgx_detach(SV* sv, const MGVTBL* id)

Removes all the MAGICs identified by id.

MACROS

MAGIC* MGX_FIND(SV* sv, const MGVTBL* id)

Checks if sv has any MAGICs, and finds a MAGIC like mgx_find().

SV* MG_obj(MAGIC* mg)

The same as mg->mg_obj.

U16 MG_private(MAGIC* mg)

The same as mg->mg_private.

char* MG_ptr(mg)

The same as mg->mg_ptr.

char* MG_len(mg)

The same as mg->mg_len.

void* MG_vptr(mg)

The same as (void*)mg->mg_ptr.

SV* MG_sv(mg)

The same as (SV*)mg->mg_ptr.

MG_len(mg) must be HEf_SVKEY.

SV* MG_sv_set(mg, sv)

Sets sv to MG_sv(mg), and MG_len(mg) = HEf_SVKEY.

bool MG_ptr_is_sv(mg)

The same as MG_len(mg) == HEf_SVKEY.

DEPENDENCIES

Perl 5.8.1 or later, and a C compiler.

BUGS

No bugs have been reported.

Please report any bugs or feature requests to the author.

SEE ALSO

magic_ext.h.

perlapi.

perlguts.

sv.c.

mg.h.

mg.c.

Module::Install::XSUtil.

AUTHOR

Goro Fuji (gfx) <gfuji(at)cpan.org>.

LICENSE AND COPYRIGHT

Copyright (c) 2009, Goro Fuji (gfx). Some rights reserved.

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