1Devel::CallChecker(3pm)User Contributed Perl DocumentatioDnevel::CallChecker(3pm)
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). It also, at compile
39 time, supplies the C header file and link library which provide access
40 to the functions. In normal use, "callchecker0_h" and
41 "callchecker_linkable" should be called at build time (not authoring
42 time) for the module that wishes to use the C functions.
43 The purpose of this module is specifically to provide the Perl 5.14.0
45 version of the "cv_set_call_checker" API to earlier Perl versions where
46 the core doesn't have "cv_set_call_checker" at all. This module does
47 not attempt to backport later refinements of the "cv_set_call_checker"
48 API. Thus an XS module that uses this module can be sure of having at
49 least the Perl 5.14.0 version of "cv_set_call_checker" available,
50 regardless of which Perl version it is running on, but cannot be sure
51 of having any more refined version of the API available. Such a module
52 will have access to the core's version of the API as normal on Perl
53 versions where the core supplies it, and is free to use the ordinary
54 mechanisms of Perl version portability to manage the differences
55 between versions of the API.
56
58 callchecker0_h
59 Content of a C header file, intended to be named
60 ""callchecker0.h"". It is to be included in XS code, and "perl.h"
61 must be included first. When the XS module is loaded at runtime,
62 the "Devel::CallChecker" module must be loaded first. This will
63 result in the Perl API functions "rv2cv_op_cv",
64 "ck_entersub_args_list", "ck_entersub_args_proto",
65 "ck_entersub_args_proto_or_list", "cv_get_call_checker", and
66 "cv_set_call_checker", as defined below and in the Perl 5.14.0 API,
67 being available to the XS code.
68 callchecker_linkable
70 List of names of files that must be used as additional objects when
71 linking an XS module that uses the C functions supplied by this
72 module. This list will be empty on many platforms.
73
75 rv2cv_op_cv
76 Examines an op, which is expected to identify a subroutine at
77 runtime, and attempts to determine at compile time which subroutine
78 it identifies. This is normally used during Perl compilation to
79 determine whether a prototype can be applied to a function call.
80 cvop is the op being considered, normally an "rv2cv" op. A pointer
81 to the identified subroutine is returned, if it could be determined
82 statically, and a null pointer is returned if it was not possible
83 to determine statically.
84 Whether the subroutine is statically identifiable is determined in
86 accordance with the prevailing standards of the Perl version being
87 used. The same criteria are used that the core uses to determine
88 whether to apply a prototype to a subroutine call. From version
89 5.11.2 onwards, the subroutine can be determined if the RV that the
90 "rv2cv" is to operate on is provided by a suitable "gv" or "const"
91 op. Prior to 5.11.2, only a "gv" op will do. A "gv" op is
92 suitable if the GV's CV slot is populated. A "const" op is
93 suitable if the constant value is an RV pointing to a CV. Details
94 of this process may change in future versions of Perl.
95 If the "rv2cv" op has the "OPpENTERSUB_AMPER" flag set then no
97 attempt is made to identify the subroutine statically: this flag is
98 used to suppress compile-time magic on a subroutine call, forcing
99 it to use default runtime behaviour.
100 If flags has the bit "RV2CVOPCV_MARK_EARLY" set, then the handling
102 of a GV reference is modified. If a GV was examined and its CV
103 slot was found to be empty, then the "gv" op has the "OPpEARLY_CV"
104 flag set. If the op is not optimised away, and the CV slot is
105 later populated with a subroutine having a prototype, that flag
106 eventually triggers the warning "called too early to check
107 prototype".
108 If flags has the bit "RV2CVOPCV_RETURN_NAME_GV" set, then instead
110 of returning a pointer to the subroutine it returns a pointer to
111 the GV giving the most appropriate name for the subroutine in this
112 context. Normally this is just the "CvGV" of the subroutine, but
113 for an anonymous ("CvANON") subroutine that is referenced through a
114 GV it will be the referencing GV. The resulting "GV*" is cast to
115 "CV*" to be returned. A null pointer is returned as usual if there
116 is no statically-determinable subroutine.
117 CV *rv2cv_op_cv(OP *cvop, U32 flags)
119 cv_get_call_checker
121 Retrieves the function that will be used to fix up a call to cv.
122 Specifically, the function is applied to an "entersub" op tree for
123 a subroutine call, not marked with "&", where the callee can be
124 identified at compile time as cv.
125 The C-level function pointer is returned in *ckfun_p, and an SV
127 argument for it is returned in *ckobj_p. The function is intended
128 to be called in this manner:
129 entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));
131 In this call, entersubop is a pointer to the "entersub" op, which
133 may be replaced by the check function, and namegv is a GV supplying
134 the name that should be used by the check function to refer to the
135 callee of the "entersub" op if it needs to emit any diagnostics.
136 It is permitted to apply the check function in non-standard
137 situations, such as to a call to a different subroutine or to a
138 method call.
139 By default, the function is Perl_ck_entersub_args_proto_or_list,
141 and the SV parameter is cv itself. This implements standard
142 prototype processing. It can be changed, for a particular
143 subroutine, by "cv_set_call_checker".
144 void cv_get_call_checker(CV *cv, Perl_call_checker *ckfun_p,
146 SV **ckobj_p)
147 cv_set_call_checker
149 Sets the function that will be used to fix up a call to cv.
150 Specifically, the function is applied to an "entersub" op tree for
151 a subroutine call, not marked with "&", where the callee can be
152 identified at compile time as cv.
153 The C-level function pointer is supplied in ckfun, and an SV
155 argument for it is supplied in ckobj. The function is intended to
156 be called in this manner:
157 entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);
159 In this call, entersubop is a pointer to the "entersub" op, which
161 may be replaced by the check function, and namegv is a GV supplying
162 the name that should be used by the check function to refer to the
163 callee of the "entersub" op if it needs to emit any diagnostics.
164 It is permitted to apply the check function in non-standard
165 situations, such as to a call to a different subroutine or to a
166 method call.
167 The current setting for a particular CV can be retrieved by
169 "cv_get_call_checker".
170 void cv_set_call_checker(CV *cv, Perl_call_checker ckfun,
172 SV *ckobj)
173 ck_entersub_args_list
175 Performs the default fixup of the arguments part of an "entersub"
176 op tree. This consists of applying list context to each of the
177 argument ops. This is the standard treatment used on a call marked
178 with "&", or a method call, or a call through a subroutine
179 reference, or any other call where the callee can't be identified
180 at compile time, or a call where the callee has no prototype.
181 OP *ck_entersub_args_list(OP *entersubop)
183 ck_entersub_args_proto
185 Performs the fixup of the arguments part of an "entersub" op tree
186 based on a subroutine prototype. This makes various modifications
187 to the argument ops, from applying context up to inserting "refgen"
188 ops, and checking the number and syntactic types of arguments, as
189 directed by the prototype. This is the standard treatment used on
190 a subroutine call, not marked with "&", where the callee can be
191 identified at compile time and has a prototype.
192 protosv supplies the subroutine prototype to be applied to the
194 call. It may be a normal defined scalar, of which the string value
195 will be used. Alternatively, for convenience, it may be a
196 subroutine object (a "CV*" that has been cast to "SV*") which has a
197 prototype. The prototype supplied, in whichever form, does not
198 need to match the actual callee referenced by the op tree.
199 If the argument ops disagree with the prototype, for example by
201 having an unacceptable number of arguments, a valid op tree is
202 returned anyway. The error is reflected in the parser state,
203 normally resulting in a single exception at the top level of
204 parsing which covers all the compilation errors that occurred. In
205 the error message, the callee is referred to by the name defined by
206 the namegv parameter.
207 OP *ck_entersub_args_proto(OP *entersubop, GV *namegv,
209 SV *protosv)
210 ck_entersub_args_proto_or_list
212 Performs the fixup of the arguments part of an "entersub" op tree
213 either based on a subroutine prototype or using default list-
214 context processing. This is the standard treatment used on a
215 subroutine call, not marked with "&", where the callee can be
216 identified at compile time.
217 protosv supplies the subroutine prototype to be applied to the
219 call, or indicates that there is no prototype. It may be a normal
220 scalar, in which case if it is defined then the string value will
221 be used as a prototype, and if it is undefined then there is no
222 prototype. Alternatively, for convenience, it may be a subroutine
223 object (a "CV*" that has been cast to "SV*"), of which the
224 prototype will be used if it has one. The prototype (or lack
225 thereof) supplied, in whichever form, does not need to match the
226 actual callee referenced by the op tree.
227 If the argument ops disagree with the prototype, for example by
229 having an unacceptable number of arguments, a valid op tree is
230 returned anyway. The error is reflected in the parser state,
231 normally resulting in a single exception at the top level of
232 parsing which covers all the compilation errors that occurred. In
233 the error message, the callee is referred to by the name defined by
234 the namegv parameter.
235 OP *ck_entersub_args_proto_or_list(OP *entersubop, GV *namegv,
237 SV *protosv)
238
240 B::CallChecker, Devel::CallParser, "cv_set_call_checker" in perlapi
241
243 Andrew Main (Zefram) <zefram@fysh.org>
244
246 Copyright (C) 2011, 2012, 2013, 2015, 2017, 2023 Andrew Main (Zefram)
247 <zefram@fysh.org>
248
250 This module is free software; you can redistribute it and/or modify it
251 under the same terms as Perl itself.
252perl v5.38.0 2023-07-20 Devel::CallChecker(3pm)