1Devel::CallChecker(3) User Contributed Perl DocumentationDevel::CallChecker(3)
2
3
4

NAME

6       Devel::CallChecker - custom op checking attached to subroutines
7

SYNOPSIS

9           # to generate header prior to XS compilation
10
11           perl -MDevel::CallChecker=callchecker0_h \
12               -e 'print callchecker0_h' > callchecker0.h
13
14           # in Perl part of module
15
16           use Devel::CallChecker;
17
18           /* in XS */
19
20           #include "callchecker0.h"
21
22           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

DESCRIPTION

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
37       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

CONSTANTS

45       callchecker0_h
46           Content of a C header file, intended to be named
47           ""callchecker0.h"".  It is to be included in XS code, and "perl.h"
48           must be included first.  When the XS module is loaded at runtime,
49           the "Devel::CallChecker" module must be loaded first.  This will
50           result in the Perl API functions "rv2cv_op_cv",
51           "ck_entersub_args_list", "ck_entersub_args_proto",
52           "ck_entersub_args_proto_or_list", "cv_get_call_checker", and
53           "cv_set_call_checker", as defined below and in the Perl 5.14.0 API,
54           being available to the XS code.
55
56       callchecker_linkable
57           List of names of files that must be used as additional objects when
58           linking an XS module that uses the C functions supplied by this
59           module.  This list will be empty on many platforms.
60

C FUNCTIONS

62       rv2cv_op_cv
63           Examines an op, which is expected to identify a subroutine at
64           runtime, and attempts to determine at compile time which subroutine
65           it identifies.  This is normally used during Perl compilation to
66           determine whether a prototype can be applied to a function call.
67           cvop is the op being considered, normally an "rv2cv" op.  A pointer
68           to the identified subroutine is returned, if it could be determined
69           statically, and a null pointer is returned if it was not possible
70           to determine statically.
71
72           Whether the subroutine is statically identifiable is determined in
73           accordance with the prevailing standards of the Perl version being
74           used.  The same criteria are used that the core uses to determine
75           whether to apply a prototype to a subroutine call.  From version
76           5.11.2 onwards, the subroutine can be determined if the RV that the
77           "rv2cv" is to operate on is provided by a suitable "gv" or "const"
78           op.  Prior to 5.11.2, only a "gv" op will do.  A "gv" op is
79           suitable if the GV's CV slot is populated.  A "const" op is
80           suitable if the constant value must be an RV pointing to a CV.
81           Details of this process may change in future versions of Perl.
82
83           If the "rv2cv" op has the "OPpENTERSUB_AMPER" flag set then no
84           attempt is made to identify the subroutine statically: this flag is
85           used to suppress compile-time magic on a subroutine call, forcing
86           it to use default runtime behaviour.
87
88           If flags has the bit "RV2CVOPCV_MARK_EARLY" set, then the handling
89           of a GV reference is modified.  If a GV was examined and its CV
90           slot was found to be empty, then the "gv" op has the "OPpEARLY_CV"
91           flag set.  If the op is not optimised away, and the CV slot is
92           later populated with a subroutine having a prototype, that flag
93           eventually triggers the warning "called too early to check
94           prototype".
95
96           If flags has the bit "RV2CVOPCV_RETURN_NAME_GV" set, then instead
97           of returning a pointer to the subroutine it returns a pointer to
98           the GV giving the most appropriate name for the subroutine in this
99           context.  Normally this is just the "CvGV" of the subroutine, but
100           for an anonymous ("CvANON") subroutine that is referenced through a
101           GV it will be the referencing GV.  The resulting "GV*" is cast to
102           "CV*" to be returned.  A null pointer is returned as usual if there
103           is no statically-determinable subroutine.
104
105               CV *rv2cv_op_cv(OP *cvop, U32 flags)
106
107       cv_get_call_checker
108           Retrieves the function that will be used to fix up a call to cv.
109           Specifically, the function is applied to an "entersub" op tree for
110           a subroutine call, not marked with "&", where the callee can be
111           identified at compile time as cv.
112
113           The C-level function pointer is returned in *ckfun_p, and an SV
114           argument for it is returned in *ckobj_p.  The function is intended
115           to be called in this manner:
116
117               entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));
118
119           In this call, entersubop is a pointer to the "entersub" op, which
120           may be replaced by the check function, and namegv is a GV supplying
121           the name that should be used by the check function to refer to the
122           callee of the "entersub" op if it needs to emit any diagnostics.
123           It is permitted to apply the check function in non-standard
124           situations, such as to a call to a different subroutine or to a
125           method call.
126
127           By default, the function is Perl_ck_entersub_args_proto_or_list,
128           and the SV parameter is cv itself.  This implements standard
129           prototype processing.  It can be changed, for a particular
130           subroutine, by "cv_set_call_checker".
131
132               void cv_get_call_checker(CV *cv, Perl_call_checker *ckfun_p,
133                       SV **ckobj_p)
134
135       cv_set_call_checker
136           Sets the function that will be used to fix up a call to cv.
137           Specifically, the function is applied to an "entersub" op tree for
138           a subroutine call, not marked with "&", where the callee can be
139           identified at compile time as cv.
140
141           The C-level function pointer is supplied in ckfun, and an SV
142           argument for it is supplied in ckobj.  The function is intended to
143           be called in this manner:
144
145               entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);
146
147           In this call, entersubop is a pointer to the "entersub" op, which
148           may be replaced by the check function, and namegv is a GV supplying
149           the name that should be used by the check function to refer to the
150           callee of the "entersub" op if it needs to emit any diagnostics.
151           It is permitted to apply the check function in non-standard
152           situations, such as to a call to a different subroutine or to a
153           method call.
154
155           The current setting for a particular CV can be retrieved by
156           "cv_get_call_checker".
157
158               void cv_set_call_checker(CV *cv, Perl_call_checker ckfun,
159                       SV *ckobj)
160
161       ck_entersub_args_list
162           Performs the default fixup of the arguments part of an "entersub"
163           op tree.  This consists of applying list context to each of the
164           argument ops.  This is the standard treatment used on a call marked
165           with "&", or a method call, or a call through a subroutine
166           reference, or any other call where the callee can't be identified
167           at compile time, or a call where the callee has no prototype.
168
169               OP *ck_entersub_args_list(OP *entersubop)
170
171       ck_entersub_args_proto
172           Performs the fixup of the arguments part of an "entersub" op tree
173           based on a subroutine prototype.  This makes various modifications
174           to the argument ops, from applying context up to inserting "refgen"
175           ops, and checking the number and syntactic types of arguments, as
176           directed by the prototype.  This is the standard treatment used on
177           a subroutine call, not marked with "&", where the callee can be
178           identified at compile time and has a prototype.
179
180           protosv supplies the subroutine prototype to be applied to the
181           call.  It may be a normal defined scalar, of which the string value
182           will be used.  Alternatively, for convenience, it may be a
183           subroutine object (a "CV*" that has been cast to "SV*") which has a
184           prototype.  The prototype supplied, in whichever form, does not
185           need to match the actual callee referenced by the op tree.
186
187           If the argument ops disagree with the prototype, for example by
188           having an unacceptable number of arguments, a valid op tree is
189           returned anyway.  The error is reflected in the parser state,
190           normally resulting in a single exception at the top level of
191           parsing which covers all the compilation errors that occurred.  In
192           the error message, the callee is referred to by the name defined by
193           the namegv parameter.
194
195               OP *ck_entersub_args_proto(OP *entersubop, GV *namegv,
196                       SV *protosv)
197
198       ck_entersub_args_proto_or_list
199           Performs the fixup of the arguments part of an "entersub" op tree
200           either based on a subroutine prototype or using default list-
201           context processing.  This is the standard treatment used on a
202           subroutine call, not marked with "&", where the callee can be
203           identified at compile time.
204
205           protosv supplies the subroutine prototype to be applied to the
206           call, or indicates that there is no prototype.  It may be a normal
207           scalar, in which case if it is defined then the string value will
208           be used as a prototype, and if it is undefined then there is no
209           prototype.  Alternatively, for convenience, it may be a subroutine
210           object (a "CV*" that has been cast to "SV*"), of which the
211           prototype will be used if it has one.  The prototype (or lack
212           thereof) supplied, in whichever form, does not need to match the
213           actual callee referenced by the op tree.
214
215           If the argument ops disagree with the prototype, for example by
216           having an unacceptable number of arguments, a valid op tree is
217           returned anyway.  The error is reflected in the parser state,
218           normally resulting in a single exception at the top level of
219           parsing which covers all the compilation errors that occurred.  In
220           the error message, the callee is referred to by the name defined by
221           the namegv parameter.
222
223               OP *ck_entersub_args_proto_or_list(OP *entersubop, GV *namegv,
224                       SV *protosv)
225

SEE ALSO

227       B::CallChecker, Devel::CallParser, "cv_set_call_checker" in perlapi
228

AUTHOR

230       Andrew Main (Zefram) <zefram@fysh.org>
231
233       Copyright (C) 2011, 2012, 2013, 2015, 2017 Andrew Main (Zefram)
234       <zefram@fysh.org>
235

LICENSE

237       This module is free software; you can redistribute it and/or modify it
238       under the same terms as Perl itself.
239
240
241
242perl v5.34.0                      2022-01-21             Devel::CallChecker(3)
Impressum