Take me over?
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 onsv
and storesobj
in themg_obj
.mg_ptr
is set toptr
, which allows for namespacing.In the OO api
sv
is the dereferenced target, andptr
is the dereferenced$self
.ptr
can beNULL
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 themg_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.