/ 
B-Hooks-OP-Annotation-0.01
River stage two • 3 direct dependents • 67 total dependents
/ B::Hooks::OP::Annotation

NAME

B::Hooks::OP::Annotation - Annotate and delegate hooked OPs

SYNOPSIS

#include "hook_op_check.h"
#include "hook_op_ppaddr.h"
#include "hook_op_annotation.h"

STATIC OPAnnotationGroup mymodule_annotations;

STATIC void mymodule_mydata_free(pTHX_ void *mydata) {
    // ...
}

STATIC OP * mymodule_check_method_named(pTHX_ OP *op, void *unused) {
    OPAnnotation * annotation;
    MyData * mydata;

    mydata = mymodule_get_mydata(); /* metadata to be associated with this op */
    annotation = op_annotation_new(mymodule_annotations, op->op_ppaddr, mydata);
    hook_op_ppaddr(op, mymodule_method_named, annotation);
}

STATIC OP * mymodule_method_named(pTHX_ OP *op, void *user_data) {
    OPAnnotation * annotation;
    MyData * mydata;
    
    mydata = (MyData *)annotation->data;

    // ...

    if (ok) {
        return NORMAL;
    } else if (mymodule_stop_hooking(op)) { /* restore the previous op_ppaddr */
        op->op_ppaddr = annotation->ppaddr;
        op_annotation_free(annotation);
        return CALL_FPTR(op->op_ppaddr)(aTHX);
    } else {
        return CALL_FPTR(annotation->ppaddr)(aTHX); /* delegate to the previous op_ppaddr */
    }
}

MODULE = mymodule PACKAGE = mymodule

BOOT:
    mymodule_annotations = op_annotation_group_new(mymodule_mydata_free);

void
END()
    CODE:
        op_annotation_group_free(mymodule_annotations);

void
setup()
    CODE:
        mymodule_hook_op_method_named_id = hook_op_check(OP_METHOD_NAMED, mymodule_check_method_named, NULL);

void
teardown()
    CODE:
        hook_op_check_remove(OP_METHOD_NAMED, mymodule_hook_op_method_named_id);

DESCRIPTION

This module provides a way for XS code that hijacks OP op_ppaddr functions to delegate to (or restore) the previous functions, whether assigned by perl or by another module. Typically this should be used in conjunction with B::Hooks::OP::Check and B::Hooks::OP::PPAddr.

This module makes its types and functions available to XS code by utilising ExtUtils::Depends. Modules that wish to use these exports in their XS code should include something like the following in their Makefile.PL:

my $XS_DEPENDENCIES = eval {
    require ExtUtils::Depends;
    my %hash = ExtUtils::Depends->new(
        'Your::XS::Module' => 'B::Hooks::OP::Annotation', # &c. e.g. B::Hooks::OP::Check and/or B::Hooks::OP::PPAddr
    )->get_makefile_vars();
    \%hash
} || {};

WriteMakefile(
    NAME => 'Your::XS::Module',
    # ...
    PREREQ_PM => {
        # ...
        'B::Hooks::OP::Annotation' => 0,
        'ExtUtils::Depends'        => 0,
        # ...
    },
    # ...
    %$XS_DEPENDENCIES,
);

Then use B::Hooks::OP::Annotation in your XS module's corresponding .pm file.

TYPES

OPAnnotation

This struct contains two members:

  • data, a void * containing metadata that should be associated with the current OP

  • ppaddr, the op_ppaddr function (of type "OPAnnotationPPAddr") that is being replaced

OPAnnotationGroup

Annotations are stored in groups. Multiple groups can be created, and each one manages all the annotations associated with it. Groups are initialised with an optional destructor that is used to clean up the values in the data fields of its members. This destructor can be null if no cleanup is needed. Annotations can be removed from the group and freed by calling "op_annotation_free", and the group and all its annotations can be destroyed by calling "op_annotation_group_free".

OPAnnotationPPAddr

This typedef corresponds to the type of perl's op_ppaddr functions i.e.:

typedef  OP *(*OPAnnotationPPAddr)(pTHX);

OPAnnotationDtor

This is the typedef for the destructor used to free or cleanup the user-supplied data:

typedef void (*OPAnnotationDtor)(pTHX_ void *data);

FUNCTIONS

op_annotation_group_new

This function creates a new annotation group. This manages one or more annotations. It takes a destructor (of type "OPAnnotationDtor") as an argument. This is used to free the data pointer of the group's annotations when they're destroyed individually by "op_annotation_free" or collectively by "op_annotation_group_free".

Typically, a group should be created for each different data type held in the data slot of the annotation objects. Thus there might be a group for OPs whose metadata is stored in an AV * and another group for OPs whose metadata is a HV *.

OPAnnotationGroup op_annotation_group_new(OPAnnotationDtor dtor);

op_annotation_new

This function creates a new annotation. It takes an "OPAnnotationGroup", the previous op_ppaddr function and a pointer to the metadata to be associated with the OP as arguments, and returns a pointer to the new annotation.

OPAnnotation * op_annotation_new(OPAnnotationGroup group, OPAnnotationPPAddr ppaddr, void *data);

op_annotation_free

This removes the specified annotation from the group and frees its memory. If a destructor was supplied, then it is called on the value in the data slot.

void op_annotation_free(OPAnnotation *annotation);

op_annotation_group_free

This function frees the memory allocated for the annotation group and its contents. If the destructor supplied in the constructor call was non-null, then it is applied to each annotation's data slot before the group is freed.

void op_annotation_group_free(OPAnnotationGroup group);

EXPORT

None by default.

SEE ALSO

AUTHOR

chocolateboy <chocolate@cpan.org>

COPYRIGHT AND LICENSE

Copyright (c) 2009 chocolateboy

This module is free software.

You may distribute this code under the same terms as Perl itself.