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