File Coverage

blib/lib/Devel/CallChecker.pm
Criterion Covered Total %
statement 14 14 100.0
branch n/a
condition n/a
subroutine 5 5 100.0
pod 1 1 100.0
total 20 20 100.0


line stmt bran cond sub pod time code
1             =head1 NAME
2              
3             Devel::CallChecker - custom op checking attached to subroutines
4              
5             =head1 SYNOPSIS
6              
7             # to generate header prior to XS compilation
8              
9             perl -MDevel::CallChecker=callchecker0_h \
10             -e 'print callchecker0_h' > callchecker0.h
11              
12             # in Perl part of module
13              
14             use Devel::CallChecker;
15              
16             /* in XS */
17              
18             #include "callchecker0.h"
19              
20             cv_get_call_checker(cv, &ckfun, &ckobj);
21             static OP *my_ckfun(pTHX_ OP *o, GV *namegv, SV *ckobj);
22             cv_set_call_checker(cv, my_ckfun, ckobj);
23              
24             =head1 DESCRIPTION
25              
26             This module makes some new features of the Perl 5.14.0 C API available
27             to XS modules running on older versions of Perl. The features are
28             centred around the function C<cv_set_call_checker>, which allows XS
29             code to attach a magical annotation to a Perl subroutine, resulting in
30             resolvable calls to that subroutine being mutated at compile time by
31             arbitrary C code. This module makes C<cv_set_call_checker> and several
32             supporting functions available. (It is possible to achieve the effect
33             of C<cv_set_call_checker> from XS code on much earlier Perl versions,
34             but it is painful to achieve without the centralised facility.)
35              
36             This module provides the implementation of the functions at runtime (on
37             Perls where they are not provided by the core). It also, at compile time,
38             supplies the C header file and link library which provide access to the
39             functions. In normal use, L</callchecker0_h> and L</callchecker_linkable>
40             should be called at build time (not authoring time) for the module that
41             wishes to use the C functions.
42              
43              
44             =cut
45              
46             package Devel::CallChecker;
47              
48 3     3   9219 { use 5.006; }
  3         18  
49 3     3   25 use warnings;
  3         8  
  3         142  
50 3     3   22 use strict;
  3         8  
  3         157  
51              
52             our $VERSION = "0.008";
53              
54 3     3   506 use parent "Exporter";
  3         309  
  3         33  
55             our @EXPORT_OK = qw(callchecker0_h callchecker_linkable);
56              
57             {
58             require DynaLoader;
59             local our @ISA = qw(DynaLoader);
60             local *dl_load_flags = sub { 1 };
61             __PACKAGE__->bootstrap($VERSION);
62             }
63              
64             =head1 CONSTANTS
65              
66             =over
67              
68             =item callchecker0_h
69              
70             Content of a C header file, intended to be named "C<callchecker0.h>".
71             It is to be included in XS code, and C<perl.h> must be included first.
72             When the XS module is loaded at runtime, the C<Devel::CallChecker>
73             module must be loaded first. This will result in the Perl API functions
74             C<rv2cv_op_cv>, C<ck_entersub_args_list>, C<ck_entersub_args_proto>,
75             C<ck_entersub_args_proto_or_list>, C<cv_get_call_checker>, and
76             C<cv_set_call_checker>, as defined below and in the Perl 5.14.0 API,
77             being available to the XS code.
78              
79             =item callchecker_linkable
80              
81             List of names of files that must be used as additional objects when
82             linking an XS module that uses the C functions supplied by this module.
83             This list will be empty on many platforms.
84              
85             =cut
86              
87             sub callchecker_linkable() {
88 2     2 1 7471 require DynaLoader::Functions;
89 2         6199 DynaLoader::Functions->VERSION(0.001);
90 2         18 return DynaLoader::Functions::linkable_for_module(__PACKAGE__);
91             }
92              
93             =back
94              
95             =head1 C FUNCTIONS
96              
97             =over
98              
99             =item rv2cv_op_cv
100              
101             Examines an op, which is expected to identify a subroutine at runtime,
102             and attempts to determine at compile time which subroutine it identifies.
103             This is normally used during Perl compilation to determine whether
104             a prototype can be applied to a function call. I<cvop> is the op
105             being considered, normally an C<rv2cv> op. A pointer to the identified
106             subroutine is returned, if it could be determined statically, and a null
107             pointer is returned if it was not possible to determine statically.
108              
109             Whether the subroutine is statically identifiable is determined in
110             accordance with the prevailing standards of the Perl version being used.
111             The same criteria are used that the core uses to determine whether to
112             apply a prototype to a subroutine call. From version 5.11.2 onwards, the
113             subroutine can be determined if the RV that the C<rv2cv> is to operate
114             on is provided by a suitable C<gv> or C<const> op. Prior to 5.11.2,
115             only a C<gv> op will do. A C<gv> op is suitable if the GV's CV slot
116             is populated. A C<const> op is suitable if the constant value must be
117             an RV pointing to a CV. Details of this process may change in future
118             versions of Perl.
119              
120             If the C<rv2cv> op has the C<OPpENTERSUB_AMPER> flag set then no attempt
121             is made to identify the subroutine statically: this flag is used to
122             suppress compile-time magic on a subroutine call, forcing it to use
123             default runtime behaviour.
124              
125             If I<flags> has the bit C<RV2CVOPCV_MARK_EARLY> set, then the handling
126             of a GV reference is modified. If a GV was examined and its CV slot was
127             found to be empty, then the C<gv> op has the C<OPpEARLY_CV> flag set.
128             If the op is not optimised away, and the CV slot is later populated with
129             a subroutine having a prototype, that flag eventually triggers the warning
130             "called too early to check prototype".
131              
132             If I<flags> has the bit C<RV2CVOPCV_RETURN_NAME_GV> set, then instead
133             of returning a pointer to the subroutine it returns a pointer to the
134             GV giving the most appropriate name for the subroutine in this context.
135             Normally this is just the C<CvGV> of the subroutine, but for an anonymous
136             (C<CvANON>) subroutine that is referenced through a GV it will be the
137             referencing GV. The resulting C<GV*> is cast to C<CV*> to be returned.
138             A null pointer is returned as usual if there is no statically-determinable
139             subroutine.
140              
141             CV *rv2cv_op_cv(OP *cvop, U32 flags)
142              
143             =item cv_get_call_checker
144              
145             Retrieves the function that will be used to fix up a call to I<cv>.
146             Specifically, the function is applied to an C<entersub> op tree for a
147             subroutine call, not marked with C<&>, where the callee can be identified
148             at compile time as I<cv>.
149              
150             The C-level function pointer is returned in I<*ckfun_p>, and an SV
151             argument for it is returned in I<*ckobj_p>. The function is intended
152             to be called in this manner:
153              
154             entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));
155              
156             In this call, I<entersubop> is a pointer to the C<entersub> op,
157             which may be replaced by the check function, and I<namegv> is a GV
158             supplying the name that should be used by the check function to refer
159             to the callee of the C<entersub> op if it needs to emit any diagnostics.
160             It is permitted to apply the check function in non-standard situations,
161             such as to a call to a different subroutine or to a method call.
162              
163             By default, the function is
164             L<Perl_ck_entersub_args_proto_or_list|/ck_entersub_args_proto_or_list>,
165             and the SV parameter is I<cv> itself. This implements standard
166             prototype processing. It can be changed, for a particular subroutine,
167             by L</cv_set_call_checker>.
168              
169             void cv_get_call_checker(CV *cv, Perl_call_checker *ckfun_p,
170             SV **ckobj_p)
171              
172             =item cv_set_call_checker
173              
174             Sets the function that will be used to fix up a call to I<cv>.
175             Specifically, the function is applied to an C<entersub> op tree for a
176             subroutine call, not marked with C<&>, where the callee can be identified
177             at compile time as I<cv>.
178              
179             The C-level function pointer is supplied in I<ckfun>, and an SV argument
180             for it is supplied in I<ckobj>. The function is intended to be called
181             in this manner:
182              
183             entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);
184              
185             In this call, I<entersubop> is a pointer to the C<entersub> op,
186             which may be replaced by the check function, and I<namegv> is a GV
187             supplying the name that should be used by the check function to refer
188             to the callee of the C<entersub> op if it needs to emit any diagnostics.
189             It is permitted to apply the check function in non-standard situations,
190             such as to a call to a different subroutine or to a method call.
191              
192             The current setting for a particular CV can be retrieved by
193             L</cv_get_call_checker>.
194              
195             void cv_set_call_checker(CV *cv, Perl_call_checker ckfun,
196             SV *ckobj)
197              
198             =item ck_entersub_args_list
199              
200             Performs the default fixup of the arguments part of an C<entersub>
201             op tree. This consists of applying list context to each of the
202             argument ops. This is the standard treatment used on a call marked
203             with C<&>, or a method call, or a call through a subroutine reference,
204             or any other call where the callee can't be identified at compile time,
205             or a call where the callee has no prototype.
206              
207             OP *ck_entersub_args_list(OP *entersubop)
208              
209             =item ck_entersub_args_proto
210              
211             Performs the fixup of the arguments part of an C<entersub> op tree
212             based on a subroutine prototype. This makes various modifications to
213             the argument ops, from applying context up to inserting C<refgen> ops,
214             and checking the number and syntactic types of arguments, as directed by
215             the prototype. This is the standard treatment used on a subroutine call,
216             not marked with C<&>, where the callee can be identified at compile time
217             and has a prototype.
218              
219             I<protosv> supplies the subroutine prototype to be applied to the call.
220             It may be a normal defined scalar, of which the string value will be used.
221             Alternatively, for convenience, it may be a subroutine object (a C<CV*>
222             that has been cast to C<SV*>) which has a prototype. The prototype
223             supplied, in whichever form, does not need to match the actual callee
224             referenced by the op tree.
225              
226             If the argument ops disagree with the prototype, for example by having
227             an unacceptable number of arguments, a valid op tree is returned anyway.
228             The error is reflected in the parser state, normally resulting in a single
229             exception at the top level of parsing which covers all the compilation
230             errors that occurred. In the error message, the callee is referred to
231             by the name defined by the I<namegv> parameter.
232              
233             OP *ck_entersub_args_proto(OP *entersubop, GV *namegv,
234             SV *protosv)
235              
236             =item ck_entersub_args_proto_or_list
237              
238             Performs the fixup of the arguments part of an C<entersub> op tree either
239             based on a subroutine prototype or using default list-context processing.
240             This is the standard treatment used on a subroutine call, not marked
241             with C<&>, where the callee can be identified at compile time.
242              
243             I<protosv> supplies the subroutine prototype to be applied to the call,
244             or indicates that there is no prototype. It may be a normal scalar,
245             in which case if it is defined then the string value will be used
246             as a prototype, and if it is undefined then there is no prototype.
247             Alternatively, for convenience, it may be a subroutine object (a C<CV*>
248             that has been cast to C<SV*>), of which the prototype will be used if it
249             has one. The prototype (or lack thereof) supplied, in whichever form,
250             does not need to match the actual callee referenced by the op tree.
251              
252             If the argument ops disagree with the prototype, for example by having
253             an unacceptable number of arguments, a valid op tree is returned anyway.
254             The error is reflected in the parser state, normally resulting in a single
255             exception at the top level of parsing which covers all the compilation
256             errors that occurred. In the error message, the callee is referred to
257             by the name defined by the I<namegv> parameter.
258              
259             OP *ck_entersub_args_proto_or_list(OP *entersubop, GV *namegv,
260             SV *protosv)
261              
262             =back
263              
264             =head1 SEE ALSO
265              
266             L<B::CallChecker>,
267             L<Devel::CallParser>,
268             L<perlapi/cv_set_call_checker>
269              
270             =head1 AUTHOR
271              
272             Andrew Main (Zefram) <zefram@fysh.org>
273              
274             =head1 COPYRIGHT
275              
276             Copyright (C) 2011, 2012, 2013, 2015, 2017
277             Andrew Main (Zefram) <zefram@fysh.org>
278              
279             =head1 LICENSE
280              
281             This module is free software; you can redistribute it and/or modify it
282             under the same terms as Perl itself.
283              
284             =cut
285              
286             1;