יובל קוג'מן (Yuval Kogman) > Magical-Hooker-Decorate-0.03 > Magical::Hooker::Decorate

Download:
Magical-Hooker-Decorate-0.03.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.03   Source  

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.
syntax highlighting: