1Devel::CallChecker(3) User Contributed Perl DocumentationDevel::CallChecker(3)
2
6 Devel::CallChecker - custom op checking attached to subroutines
7
9 # to generate header prior to XS compilation
10 perl -MDevel::CallChecker=callchecker0_h \
12 -e 'print callchecker0_h' > callchecker0.h
13 # in Perl part of module
15 use Devel::CallChecker;
17 /* in XS */
19 #include "callchecker0.h"
21 cv_get_call_checker(cv, &ckfun, &ckobj);
23 static OP *my_ckfun(pTHX_ OP *o, GV *namegv, SV *ckobj);
24 cv_set_call_checker(cv, my_ckfun, ckobj);
25
27 This module makes some new features of the Perl 5.14.0 C API available
28 to XS modules running on older versions of Perl. The features are
29 centred around the function "cv_set_call_checker", which allows XS code
30 to attach a magical annotation to a Perl subroutine, resulting in
31 resolvable calls to that subroutine being mutated at compile time by
32 arbitrary C code. This module makes "cv_set_call_checker" and several
33 supporting functions available. (It is possible to achieve the effect
34 of "cv_set_call_checker" from XS code on much earlier Perl versions,
35 but it is painful to achieve without the centralised facility.)
36 This module provides the implementation of the functions at runtime (on
38 Perls where they are not provided by the core), and also at compile
39 time supplies the C header file which provides access to the functions.
40
42 callchecker0_h
43 Content of a C header file, intended to be named
44 ""callchecker0.h"". It is to be included in XS code, and "perl.h"
45 must be included first. When the XS module is loaded at runtime,
46 the "Devel::CallChecker" module must be loaded first. This will
47 result in the Perl API functions "rv2cv_op_cv",
48 "ck_entersub_args_list", "ck_entersub_args_proto",
49 "ck_entersub_args_proto_or_list", "cv_get_call_checker", and
50 "cv_set_call_checker", as defined below and in the Perl 5.14.0 API,
51 being available to the XS code.
52 callchecker_linkable
54 List of names of files that must be used as additional objects when
55 linking an XS module that uses the C functions supplied by this
56 module. This list will be empty on many platforms.
57
59 rv2cv_op_cv
60 Examines an op, which is expected to identify a subroutine at
61 runtime, and attempts to determine at compile time which subroutine
62 it identifies. This is normally used during Perl compilation to
63 determine whether a prototype can be applied to a function call.
64 cvop is the op being considered, normally an "rv2cv" op. A pointer
65 to the identified subroutine is returned, if it could be determined
66 statically, and a null pointer is returned if it was not possible
67 to determine statically.
68 Whether the subroutine is statically identifiable is determined in
70 accordance with the prevailing standards of the Perl version being
71 used. The same criteria are used that the core uses to determine
72 whether to apply a prototype to a subroutine call. From version
73 5.11.2 onwards, the subroutine can be determined if the RV that the
74 "rv2cv" is to operate on is provided by a suitable "gv" or "const"
75 op. Prior to 5.11.2, only a "gv" op will do. A "gv" op is
76 suitable if the GV's CV slot is populated. A "const" op is
77 suitable if the constant value must be an RV pointing to a CV.
78 Details of this process may change in future versions of Perl.
79 If the "rv2cv" op has the "OPpENTERSUB_AMPER" flag set then no
81 attempt is made to identify the subroutine statically: this flag is
82 used to suppress compile-time magic on a subroutine call, forcing
83 it to use default runtime behaviour.
84 If flags has the bit "RV2CVOPCV_MARK_EARLY" set, then the handling
86 of a GV reference is modified. If a GV was examined and its CV
87 slot was found to be empty, then the "gv" op has the "OPpEARLY_CV"
88 flag set. If the op is not optimised away, and the CV slot is
89 later populated with a subroutine having a prototype, that flag
90 eventually triggers the warning "called too early to check
91 prototype".
92 If flags has the bit "RV2CVOPCV_RETURN_NAME_GV" set, then instead
94 of returning a pointer to the subroutine it returns a pointer to
95 the GV giving the most appropriate name for the subroutine in this
96 context. Normally this is just the "CvGV" of the subroutine, but
97 for an anonymous ("CvANON") subroutine that is referenced through a
98 GV it will be the referencing GV. The resulting "GV*" is cast to
99 "CV*" to be returned. A null pointer is returned as usual if there
100 is no statically-determinable subroutine.
101 CV *rv2cv_op_cv(OP *cvop, U32 flags)
103 cv_get_call_checker
105 Retrieves the function that will be used to fix up a call to cv.
106 Specifically, the function is applied to an "entersub" op tree for
107 a subroutine call, not marked with "&", where the callee can be
108 identified at compile time as cv.
109 The C-level function pointer is returned in *ckfun_p, and an SV
111 argument for it is returned in *ckobj_p. The function is intended
112 to be called in this manner:
113 entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));
115 In this call, entersubop is a pointer to the "entersub" op, which
117 may be replaced by the check function, and namegv is a GV supplying
118 the name that should be used by the check function to refer to the
119 callee of the "entersub" op if it needs to emit any diagnostics.
120 It is permitted to apply the check function in non-standard
121 situations, such as to a call to a different subroutine or to a
122 method call.
123 By default, the function is Perl_ck_entersub_args_proto_or_list,
125 and the SV parameter is cv itself. This implements standard
126 prototype processing. It can be changed, for a particular
127 subroutine, by "cv_set_call_checker".
128 void cv_get_call_checker(CV *cv,
130 Perl_call_checker *ckfun_p, SV **ckobj_p)
131 cv_set_call_checker
133 Sets the function that will be used to fix up a call to cv.
134 Specifically, the function is applied to an "entersub" op tree for
135 a subroutine call, not marked with "&", where the callee can be
136 identified at compile time as cv.
137 The C-level function pointer is supplied in ckfun, and an SV
139 argument for it is supplied in ckobj. The function is intended to
140 be called in this manner:
141 entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);
143 In this call, entersubop is a pointer to the "entersub" op, which
145 may be replaced by the check function, and namegv is a GV supplying
146 the name that should be used by the check function to refer to the
147 callee of the "entersub" op if it needs to emit any diagnostics.
148 It is permitted to apply the check function in non-standard
149 situations, such as to a call to a different subroutine or to a
150 method call.
151 The current setting for a particular CV can be retrieved by
153 "cv_get_call_checker".
154 void cv_set_call_checker(CV *cv, Perl_call_checker ckfun,
156 SV *ckobj)
157 ck_entersub_args_list
159 Performs the default fixup of the arguments part of an "entersub"
160 op tree. This consists of applying list context to each of the
161 argument ops. This is the standard treatment used on a call marked
162 with "&", or a method call, or a call through a subroutine
163 reference, or any other call where the callee can't be identified
164 at compile time, or a call where the callee has no prototype.
165 OP *ck_entersub_args_list(OP *entersubop)
167 ck_entersub_args_proto
169 Performs the fixup of the arguments part of an "entersub" op tree
170 based on a subroutine prototype. This makes various modifications
171 to the argument ops, from applying context up to inserting "refgen"
172 ops, and checking the number and syntactic types of arguments, as
173 directed by the prototype. This is the standard treatment used on
174 a subroutine call, not marked with "&", where the callee can be
175 identified at compile time and has a prototype.
176 protosv supplies the subroutine prototype to be applied to the
178 call. It may be a normal defined scalar, of which the string value
179 will be used. Alternatively, for convenience, it may be a
180 subroutine object (a "CV*" that has been cast to "SV*") which has a
181 prototype. The prototype supplied, in whichever form, does not
182 need to match the actual callee referenced by the op tree.
183 If the argument ops disagree with the prototype, for example by
185 having an unacceptable number of arguments, a valid op tree is
186 returned anyway. The error is reflected in the parser state,
187 normally resulting in a single exception at the top level of
188 parsing which covers all the compilation errors that occurred. In
189 the error message, the callee is referred to by the name defined by
190 the namegv parameter.
191 OP *ck_entersub_args_proto(OP *entersubop, GV *namegv,
193 SV *protosv)
194 ck_entersub_args_proto_or_list
196 Performs the fixup of the arguments part of an "entersub" op tree
197 either based on a subroutine prototype or using default list-
198 context processing. This is the standard treatment used on a
199 subroutine call, not marked with "&", where the callee can be
200 identified at compile time.
201 protosv supplies the subroutine prototype to be applied to the
203 call, or indicates that there is no prototype. It may be a normal
204 scalar, in which case if it is defined then the string value will
205 be used as a prototype, and if it is undefined then there is no
206 prototype. Alternatively, for convenience, it may be a subroutine
207 object (a "CV*" that has been cast to "SV*"), of which the
208 prototype will be used if it has one. The prototype (or lack
209 thereof) supplied, in whichever form, does not need to match the
210 actual callee referenced by the op tree.
211 If the argument ops disagree with the prototype, for example by
213 having an unacceptable number of arguments, a valid op tree is
214 returned anyway. The error is reflected in the parser state,
215 normally resulting in a single exception at the top level of
216 parsing which covers all the compilation errors that occurred. In
217 the error message, the callee is referred to by the name defined by
218 the namegv parameter.
219 OP *ck_entersub_args_proto_or_list(OP *entersubop,
221 GV *namegv, SV *protosv)
222
224 Devel::CallParser, "cv_set_call_checker" in perlapi
225
227 Andrew Main (Zefram) <zefram@fysh.org>
228
230 Copyright (C) 2011 Andrew Main (Zefram) <zefram@fysh.org>
231
233 This module is free software; you can redistribute it and/or modify it
234 under the same terms as Perl itself.
235perl v5.12.4 2011-09-19 Devel::CallChecker(3)