B::Hooks::OP::Annotation(3pm)

1B::Hooks::OP::AnnotatioUns(e3r)Contributed Perl DocumentBa:t:iHoonoks::OP::Annotation(3)
2
3
4

NAME

6       B::Hooks::OP::Annotation - annotate and delegate hooked OPs
7

SYNOPSIS

9           #include "hook_op_check.h"
10           #include "hook_op_annotation.h"
11
12           STATIC OPAnnotationGroup MYMODULE_ANNOTATIONS;
13
14           STATIC void mymodule_mydata_free(pTHX_ void *mydata) {
15               // ...
16           }
17
18           STATIC OP * mymodule_check_entersub(pTHX_ OP *op, void *unused) {
19               MyData * mydata;
20
21               mydata = mymodule_get_mydata(); /* metadata to be associated with this OP */
22               op_annotate(MYMODULE_ANNOTATIONS, op, mydata, mymodule_mydata_free);
23               op->op_ppaddr = mymodule_entersub;
24
25               return op;
26           }
27
28           STATIC OP * mymodule_entersub(pTHX) {
29               OPAnnotation * annotation;
30               MyData * mydata;
31               OP *op = PL_op;
32
33               annotation = op_annotation_get(MYMODULE_ANNOTATIONS, op);
34               mydata = (MyData *)annotation->data;
35
36               // ...
37
38               if (ok) {
39                   return NORMAL;
40               } else if (mymodule_stop_hooking(op)) { /* restore the previous op_ppaddr */
41                   op->op_ppaddr = annotation->op_ppaddr;
42                   op_annotation_delete(MYMODULE_ANNOTATIONS, op);
43                   return op->op_ppaddr(aTHX);
44               } else {
45                   return annotation->op_ppaddr(aTHX); /* delegate to the previous op_ppaddr */
46               }
47           }
48
49           MODULE = mymodule PACKAGE = mymodule
50
51           BOOT:
52               MYMODULE_ANNOTATIONS = op_annotation_group_new();
53
54           void
55           END()
56               CODE:
57                   op_annotation_group_free(aTHX_ MYMODULE_ANNOTATIONS);
58
59           void
60           setup()
61               CODE:
62                   mymodule_hook_op_entersub_id = hook_op_check(
63                       OP_ENTERSUB,
64                       mymodule_check_entersub,
65                       NULL
66                   );
67
68           void
69           teardown()
70               CODE:
71                   hook_op_check_remove(OP_ENTERSUB, mymodule_hook_op_entersub_id);
72

DESCRIPTION

74       This module provides a way for XS code that hijacks OP "op_ppaddr"
75       functions to delegate to (or restore) the previous functions, whether
76       assigned by perl or by another module. Typically this should be used in
77       conjunction with B::Hooks::OP::Check.
78
79       "B::Hooks::OP::Annotation" makes its types and functions available to
80       XS code by means of ExtUtils::Depends. Modules that wish to use these
81       exports in their XS code should "use B::OP::Hooks::Annotation" in the
82       Perl module that loads the XS, and include something like the following
83       in their Makefile.PL:
84
85           use ExtUtils::MakeMaker;
86           use ExtUtils::Depends;
87
88           our %XS_PREREQUISITES = (
89               'B::Hooks::OP::Annotation' => '0.44',
90               'B::Hooks::OP::Check'      => '0.15',
91           );
92
93           our %XS_DEPENDENCIES = ExtUtils::Depends->new(
94               'Your::XS::Module',
95                keys(%XS_PREREQUISITES)
96           )->get_makefile_vars();
97
98           WriteMakefile(
99               NAME          => 'Your::XS::Module',
100               VERSION_FROM  => 'lib/Your/XS/Module.pm',
101               PREREQ_PM => {
102                   'B::Hooks::EndOfScope' => '0.07',
103                   %XS_PREREQUISITES
104               },
105               ($ExtUtils::MakeMaker::VERSION >= 6.46 ?
106                   (META_MERGE => {
107                       configure_requires => {
108                           'ExtUtils::Depends' => '0.301',
109                           %XS_PREREQUISITES
110                       }})
111                   : ()
112               ),
113               %XS_DEPENDENCIES,
114               # ...
115           );
116
117   TYPES
118       OPAnnotation
119
120       This struct contains the metadata associated with a particular OP i.e.
121       the data itself, a destructor for that data, and the "op_ppaddr"
122       function that was defined when the annotation was created by
123       "op_annotate" or "op_annotation_new".
124
125       •   "op_ppaddr", the OP's previous "op_ppaddr" function (of type
126           "OPAnnotationPPAddr")
127
128       •   "data", a "void *" to metadata that should be associated with the
129           OP
130
131       •   "dtor", a function (of type "OPAnnotationDtor") used to free the
132           metadata
133
134       The fields are all read/write and can be modified after the annotation
135       has been created.
136
137       OPAnnotationGroup
138
139       Annotations are stored in groups. Multiple groups can be created, and
140       each one manages all of the annotations associated with it.
141
142       Annotations can be removed from the group and freed by calling
143       "op_annotation_delete", and the group and all its members can be
144       destroyed by calling "op_annotation_group_free".
145
146       OPAnnotationPPAddr
147
148       This typedef corresponds to the type of perl's "op_ppaddr" functions
149       i.e.
150
151           typedef  OP *(*OPAnnotationPPAddr)(pTHX);
152
153       OPAnnotationDtor
154
155       This is the typedef for the destructor used to free the metadata
156       associated with the OP.
157
158           typedef void (*OPAnnotationDtor)(pTHX_ void *data);
159
160   FUNCTIONS
161       op_annotation_new
162
163       This function creates and returns a new OP annotation.
164
165       It takes an "OPAnnotationGroup", an OP, a pointer to the metadata to be
166       associated with the OP, and a destructor for that data. The data can be
167       NULL and the destructor can be NULL if no cleanup is required.
168
169       If an annotation has already been assigned for the OP, then it is
170       replaced by the new annotation, and the old annotation is freed,
171       triggering the destruction of its data (if supplied) by its destructor
172       (if supplied).
173
174           OPAnnotation * op_annotation_new(
175               OPAnnotationGroup group,
176               OP *op,
177               void *data,
178               OPAnnotationDtor dtor
179           );
180
181       op_annotate
182
183       This function is a void version of "op_annotation_new" for cases where
184       the new annotation is not needed.
185
186           void op_annotate(
187               OPAnnotationGroup group,
188               OP *op,
189               void *data,
190               OPAnnotationDtor dtor
191           );
192
193       op_annotation_get
194
195       This retrieves the annotation associated with the supplied OP. If an
196       annotation has not been assigned for the OP, it raises a fatal
197       exception.
198
199           OPAnnotation * op_annotation_get(OPAnnotationGroup group, OP *op);
200
201       op_annotation_delete
202
203       This removes the specified annotation from the group and frees its
204       memory. If a destructor was supplied, it is called on the value in the
205       "data" field (if supplied).
206
207           void op_annotation_delete(pTHX_ OPAnnotationGroup group, OP *op);
208
209       op_annotation_group_new
210
211       This function creates a new annotation group.
212
213           OPAnnotationGroup op_annotation_group_new(void);
214
215       op_annotation_group_free
216
217       This function destroys the annotations in an annotation group and frees
218       the memory allocated for the group.
219
220           void op_annotation_group_free(pTHX_ OPAnnotationGroup group);
221

EXPORT

223       None by default.
224

VERSION

226       0.44
227

AUTHOR

234       chocolateboy <chocolate@cpan.org>
235

COPYRIGHT AND LICENSE

237       Copyright (c) 2009-2011 chocolateboy
238
239       This module is free software.
240
241       You may distribute this code under the same terms as Perl itself.
242
243
244
245perl v5.38.0                      2023-07-20       B::Hooks::OP::Annotation(3)