NAME

Magical::Hooker::Decorate - Decorate an SV using magic hooks

SYNOPSIS

From Perl

        # this object serves as a namespace, you can only get values that were set
        # by it, so you probably want to have a single instance for your module in
        # some global variable
        my $hooker = Magical::Hooker::Decorate->new;

        # associate an SV like this
        $hooker->set(\$var, $decoration);

        # get the associate value like this:
        my $decoration = $hooker->get(\$var);

From C

        magical_hooker_decoration_set(target_sv, decoration_sv, (void *)self);

        decoration_sv = magical_hooker_decoration_get(target_sv, (void *)self);

DESCRIPTION

This module provides a C api and a thin Perl wrapper that lets you associate a value with any SV, much like Hash::Util::FieldHash does.

The decoration will be reference counted, so DESTROY will be called when target disappears.

This lets you do things like:

        $hooker->set($object, Scope::Guard->new(sub {
                warn "object just died";
        });

and of course also access the value of the decoration.

The code was used to associate code references created with newXS with their associated objects in Moose's experimental XS branch.

METHODS

new

Takes no arguments, and returns a handle.

All the association methods use storage that is private to the handle.

set $target, $value

Note that $target is dereferenced before casting magic.

get $target

Returns the value.

clear

Removes the value.

C API

MAGIC *magical_hooker_decoration_set (pTHX_ SV *sv, SV *obj, void *ptr)

Creates a new MAGIC entry on sv and stores obj in the mg_obj. mg_ptr is set to ptr, which allows for namespacing.

In the OO api sv is the dereferenced target, and ptr is the dereferenced $self.

ptr can be NULL but then you're limited to one decoration per SV.

SV *magical_hooker_decoration_get (pTHX_ SV *sv, void *ptr)

Get the mg_obj.

SV *magical_hooker_decoration_clear (pTHX_ SV *sv, void *ptr)

Removes the MAGIC and returns the mg_obj (after mortalizing it).

MAGIC *magical_hooker_decoration_get_mg (pTHX_ SV *sv, void *ptr = NULL)

Get the MAGIC entry in which the decoration is stored.

THANKS

Shawn M Moore (he knows why)

VERSION CONTROL

http://github.com/nothingmuch/magical-hooker-decorate

AUTHOR

Yuval Kogman

COPYRIGHT & LICENSE

        Copyright (c) 2008, 2009 Yuval Kogman. All rights reserved
        This program is free software; you can redistribute
        it and/or modify it under the same terms as Perl itself.