/ 
B-Hooks-OP-Annotation-0.20
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_annotation.h"

STATIC OPAnnotationGroup mymodule_annotations;

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

STATIC OP * mymodule_check_entersub(pTHX_ OP *op, void *unused) {
    OPAnnotation * clobbered;
    MyData * mydata;

    mydata = mymodule_get_mydata(); /* metadata to be associated with this op */

    clobbered = op_annotation_set(mymodule_annotations, op, mydata, mymodule_mydata_free);

    if (clobbered) {
        op_annotation_free(clobbered);
        croak("error: OP already annotated");
    }

    op->op_ppaddr = mymodule_entersub;
    return op;
}

STATIC OP * mymodule_entersub(pTHX) {
    OPAnnotation * annotation;
    MyData * mydata;
    OP *op = PL_op;
    
    annotation = op_annotation_get(mymodule_annotations, op);
    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_delete(mymodule_annotations, op);
        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();

void
END()
    CODE:
        op_annotation_group_free(mymodule_annotations);

void
setup()
    CODE:
        mymodule_hook_op_entersub_id = hook_op_check(
            OP_ENTERSUB,
            mymodule_check_entersub,
            NULL
        );

void
teardown()
    CODE:
        hook_op_check_remove(OP_ENTERSUB, mymodule_hook_op_entersub_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.

B::Hooks::OP::Annotation 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 <use B::OP::Hooks::Annotation> in the Perl module that loads the XS, and 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', B::Hooks::OP::Check
    )->get_makefile_vars();
    \%hash
} || {};

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

TYPES

OPAnnotation

This struct contains three fields:

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

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

  • dtor, a function (of type "OPAnnotationDtor") used to free the metadata

OPAnnotation

This struct contains the metadata associated with a particular OP i.e. the data itself, a destructor for that data, and the op_ppaddr function that was defined when the annotation was created by "op_annotation_set".

OPAnnotationGroup

Annotations are stored in groups. Multiple groups can be created, and each one manages all the annotations associated with it.

Annotations can be removed from the group and freed by calling "op_annotation_delete", and the group and all its members 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 the metadata associated with the OP.

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

FUNCTIONS

op_annotation_group_new

This function creates a new annotation group. Annotation groups manage a collection of annotations and allow them to be freed with "op_annotation_group_free".

OPAnnotationGroup op_annotation_group_new();

op_annotation_set

This function annotates an OP with metadata that can later be recovered with "op_annotation_get". It takes an "OPAnnotationGroup", the current OP, a pointer to the metadata to be associated with the OP, and a destructor for that data. The data can be NULL and the destructor can be NULL if no cleanup is required.

OPAnnotation * op_annotation_set(OPAnnotationGroup group, OP *op, void *data, OPAnnotationDtor dtor);

op_annotation_get

This retrieves the annotation associated with the supplied OP. If an annotation has not been assigned for the OP, it raises a fatal exception.

OPAnnotation * op_annotation_get(OPAnnotationGroup group, OP *op);

op_annotation_delete

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

void op_annotation_delete(OPAnnotationGroup group, OP *op);

op_annotation_free

This calls the destructor (if supplied) on the data (if supplied) and then frees the memory allocated for the annotation. It should only be called on annotations that have been removed from their group and returned from an "op_annotation_set" call.

op_annotation_group_free

This function destroys the annotations in an annotation group and frees the memory allocated for it.

void op_annotation_group_free(OPAnnotationGroup group);

EXPORT

None by default.

VERSION

0.20

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.