This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Reformat code in .pm files in bignum distribution.
[perl5.git] / pod / perlcall.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
3perlcall - Perl calling conventions from C
4
5=head1 DESCRIPTION
6
d1b91892 7The purpose of this document is to show you how to call Perl subroutines
5f05dabc 8directly from C, i.e., how to write I<callbacks>.
a0d0e21e 9
d1b91892
AD
10Apart from discussing the C interface provided by Perl for writing
11callbacks the document uses a series of examples to show how the
12interface actually works in practice. In addition some techniques for
13coding callbacks are covered.
a0d0e21e 14
d1b91892 15Examples where callbacks are necessary include
a0d0e21e
LW
16
17=over 5
18
d1b91892 19=item * An Error Handler
a0d0e21e
LW
20
21You have created an XSUB interface to an application's C API.
22
23A fairly common feature in applications is to allow you to define a C
d1b91892
AD
24function that will be called whenever something nasty occurs. What we
25would like is to be able to specify a Perl subroutine that will be
26called instead.
a0d0e21e 27
95e84303 28=item * An Event-Driven Program
a0d0e21e 29
d1b91892 30The classic example of where callbacks are used is when writing an
b0b54b5e 31event driven program, such as for an X11 application. In this case
184e9718 32you register functions to be called whenever specific events occur,
5f05dabc 33e.g., a mouse button is pressed, the cursor moves into a window or a
d1b91892 34menu item is selected.
a0d0e21e
LW
35
36=back
37
d1b91892
AD
38Although the techniques described here are applicable when embedding
39Perl in a C program, this is not the primary goal of this document.
40There are other details that must be considered and are specific to
41embedding Perl. For details on embedding Perl in C refer to
42L<perlembed>.
a0d0e21e 43
d1b91892 44Before you launch yourself head first into the rest of this document,
02f6dca1
FC
45it would be a good idea to have read the following two documents--L<perlxs>
46and L<perlguts>.
a0d0e21e 47
4929bf7b 48=head1 THE CALL_ FUNCTIONS
a0d0e21e 49
d1b91892
AD
50Although this stuff is easier to explain using examples, you first need
51be aware of a few important definitions.
a0d0e21e 52
d1b91892
AD
53Perl has a number of C functions that allow you to call Perl
54subroutines. They are
a0d0e21e 55
4358a253
SS
56 I32 call_sv(SV* sv, I32 flags);
57 I32 call_pv(char *subname, I32 flags);
58 I32 call_method(char *methname, I32 flags);
5aaab254 59 I32 call_argv(char *subname, I32 flags, char **argv);
a0d0e21e 60
4929bf7b 61The key function is I<call_sv>. All the other functions are
d1b91892 62fairly simple wrappers which make it easier to call Perl subroutines in
4929bf7b 63special cases. At the end of the day they will all call I<call_sv>
5f05dabc 64to invoke the Perl subroutine.
d1b91892 65
4929bf7b 66All the I<call_*> functions have a C<flags> parameter which is
d1b91892
AD
67used to pass a bit mask of options to Perl. This bit mask operates
68identically for each of the functions. The settings available in the
69bit mask are discussed in L<FLAG VALUES>.
70
71Each of the functions will now be discussed in turn.
72
73=over 5
74
4929bf7b 75=item call_sv
d1b91892 76
02f6dca1 77I<call_sv> takes two parameters. The first, C<sv>, is an SV*.
d1b91892
AD
78This allows you to specify the Perl subroutine to be called either as a
79C string (which has first been converted to an SV) or a reference to a
4929bf7b
GS
80subroutine. The section, I<Using call_sv>, shows how you can make
81use of I<call_sv>.
d1b91892 82
4929bf7b 83=item call_pv
d1b91892 84
4929bf7b 85The function, I<call_pv>, is similar to I<call_sv> except it
d1b91892 86expects its first parameter to be a C char* which identifies the Perl
4929bf7b 87subroutine you want to call, e.g., C<call_pv("fred", 0)>. If the
d1b91892 88subroutine you want to call is in another package, just include the
5f05dabc 89package name in the string, e.g., C<"pkg::fred">.
d1b91892 90
4929bf7b 91=item call_method
d1b91892 92
4929bf7b 93The function I<call_method> is used to call a method from a Perl
d1b91892
AD
94class. The parameter C<methname> corresponds to the name of the method
95to be called. Note that the class that the method belongs to is passed
96on the Perl stack rather than in the parameter list. This class can be
97either the name of the class (for a static method) or a reference to an
98object (for a virtual method). See L<perlobj> for more information on
4929bf7b
GS
99static and virtual methods and L<Using call_method> for an example
100of using I<call_method>.
d1b91892 101
4929bf7b 102=item call_argv
d1b91892 103
4929bf7b 104I<call_argv> calls the Perl subroutine specified by the C string
d1b91892 105stored in the C<subname> parameter. It also takes the usual C<flags>
02f6dca1 106parameter. The final parameter, C<argv>, consists of a NULL-terminated
d1b91892 107list of C strings to be passed as parameters to the Perl subroutine.
4929bf7b 108See I<Using call_argv>.
d1b91892
AD
109
110=back
111
112All the functions return an integer. This is a count of the number of
113items returned by the Perl subroutine. The actual items returned by the
114subroutine are stored on the Perl stack.
115
116As a general rule you should I<always> check the return value from
117these functions. Even if you are expecting only a particular number of
118values to be returned from the Perl subroutine, there is nothing to
19799a22 119stop someone from doing something unexpected--don't say you haven't
d1b91892
AD
120been warned.
121
122=head1 FLAG VALUES
123
0b06a753
NT
124The C<flags> parameter in all the I<call_*> functions is one of G_VOID,
125G_SCALAR, or G_ARRAY, which indicate the call context, OR'ed together
126with a bit mask of any combination of the other G_* symbols defined below.
d1b91892 127
54310121 128=head2 G_VOID
129
130Calls the Perl subroutine in a void context.
131
132This flag has 2 effects:
133
134=over 5
135
136=item 1.
137
138It indicates to the subroutine being called that it is executing in
139a void context (if it executes I<wantarray> the result will be the
140undefined value).
141
142=item 2.
143
144It ensures that nothing is actually returned from the subroutine.
145
146=back
147
4929bf7b 148The value returned by the I<call_*> function indicates how many
02f6dca1 149items have been returned by the Perl subroutine--in this case it will
54310121 150be 0.
151
152
d1b91892
AD
153=head2 G_SCALAR
154
155Calls the Perl subroutine in a scalar context. This is the default
4929bf7b 156context flag setting for all the I<call_*> functions.
d1b91892 157
184e9718 158This flag has 2 effects:
d1b91892
AD
159
160=over 5
161
162=item 1.
163
184e9718 164It indicates to the subroutine being called that it is executing in a
d1b91892 165scalar context (if it executes I<wantarray> the result will be false).
a0d0e21e 166
d1b91892
AD
167=item 2.
168
184e9718 169It ensures that only a scalar is actually returned from the subroutine.
d1b91892
AD
170The subroutine can, of course, ignore the I<wantarray> and return a
171list anyway. If so, then only the last element of the list will be
172returned.
173
174=back
175
4929bf7b 176The value returned by the I<call_*> function indicates how many
d1b91892
AD
177items have been returned by the Perl subroutine - in this case it will
178be either 0 or 1.
a0d0e21e 179
d1b91892 180If 0, then you have specified the G_DISCARD flag.
a0d0e21e 181
d1b91892
AD
182If 1, then the item actually returned by the Perl subroutine will be
183stored on the Perl stack - the section I<Returning a Scalar> shows how
184to access this value on the stack. Remember that regardless of how
185many items the Perl subroutine returns, only the last one will be
186accessible from the stack - think of the case where only one value is
187returned as being a list with only one element. Any other items that
188were returned will not exist by the time control returns from the
4929bf7b 189I<call_*> function. The section I<Returning a list in a scalar
54310121 190context> shows an example of this behavior.
a0d0e21e 191
a0d0e21e 192
d1b91892 193=head2 G_ARRAY
a0d0e21e 194
d1b91892 195Calls the Perl subroutine in a list context.
a0d0e21e 196
184e9718 197As with G_SCALAR, this flag has 2 effects:
a0d0e21e
LW
198
199=over 5
200
d1b91892
AD
201=item 1.
202
90fdbbb7
DC
203It indicates to the subroutine being called that it is executing in a
204list context (if it executes I<wantarray> the result will be true).
a0d0e21e 205
d1b91892 206=item 2.
a0d0e21e 207
184e9718 208It ensures that all items returned from the subroutine will be
4929bf7b 209accessible when control returns from the I<call_*> function.
a0d0e21e 210
d1b91892 211=back
a0d0e21e 212
4929bf7b 213The value returned by the I<call_*> function indicates how many
d1b91892 214items have been returned by the Perl subroutine.
a0d0e21e 215
184e9718 216If 0, then you have specified the G_DISCARD flag.
a0d0e21e 217
d1b91892
AD
218If not 0, then it will be a count of the number of items returned by
219the subroutine. These items will be stored on the Perl stack. The
220section I<Returning a list of values> gives an example of using the
221G_ARRAY flag and the mechanics of accessing the returned items from the
222Perl stack.
a0d0e21e 223
d1b91892 224=head2 G_DISCARD
a0d0e21e 225
4929bf7b 226By default, the I<call_*> functions place the items returned from
d1b91892
AD
227by the Perl subroutine on the stack. If you are not interested in
228these items, then setting this flag will make Perl get rid of them
229automatically for you. Note that it is still possible to indicate a
230context to the Perl subroutine by using either G_SCALAR or G_ARRAY.
a0d0e21e 231
d1b91892 232If you do not set this flag then it is I<very> important that you make
5f05dabc 233sure that any temporaries (i.e., parameters passed to the Perl
d1b91892
AD
234subroutine and values returned from the subroutine) are disposed of
235yourself. The section I<Returning a Scalar> gives details of how to
5f05dabc 236dispose of these temporaries explicitly and the section I<Using Perl to
d1b91892
AD
237dispose of temporaries> discusses the specific circumstances where you
238can ignore the problem and let Perl deal with it for you.
a0d0e21e 239
d1b91892 240=head2 G_NOARGS
a0d0e21e 241
4929bf7b 242Whenever a Perl subroutine is called using one of the I<call_*>
d1b91892
AD
243functions, it is assumed by default that parameters are to be passed to
244the subroutine. If you are not passing any parameters to the Perl
245subroutine, you can save a bit of time by setting this flag. It has
246the effect of not creating the C<@_> array for the Perl subroutine.
a0d0e21e 247
d1b91892
AD
248Although the functionality provided by this flag may seem
249straightforward, it should be used only if there is a good reason to do
02f6dca1 250so. The reason for being cautious is that, even if you have specified
d1b91892
AD
251the G_NOARGS flag, it is still possible for the Perl subroutine that
252has been called to think that you have passed it parameters.
a0d0e21e 253
d1b91892
AD
254In fact, what can happen is that the Perl subroutine you have called
255can access the C<@_> array from a previous Perl subroutine. This will
4929bf7b 256occur when the code that is executing the I<call_*> function has
d1b91892
AD
257itself been called from another Perl subroutine. The code below
258illustrates this
a0d0e21e 259
84f709e7
JH
260 sub fred
261 { print "@_\n" }
a0d0e21e 262
84f709e7
JH
263 sub joe
264 { &fred }
a0d0e21e 265
4358a253 266 &joe(1,2,3);
a0d0e21e
LW
267
268This will print
269
d1b91892
AD
270 1 2 3
271
272What has happened is that C<fred> accesses the C<@_> array which
273belongs to C<joe>.
a0d0e21e 274
a0d0e21e 275
54310121 276=head2 G_EVAL
a0d0e21e 277
d1b91892 278It is possible for the Perl subroutine you are calling to terminate
5f05dabc 279abnormally, e.g., by calling I<die> explicitly or by not actually
268118b2
HS
280existing. By default, when either of these events occurs, the
281process will terminate immediately. If you want to trap this
d1b91892
AD
282type of event, specify the G_EVAL flag. It will put an I<eval { }>
283around the subroutine call.
a0d0e21e 284
4929bf7b 285Whenever control returns from the I<call_*> function you need to
d1b91892
AD
286check the C<$@> variable as you would in a normal Perl script.
287
4929bf7b 288The value returned from the I<call_*> function is dependent on
d1b91892 289what other flags have been specified and whether an error has
184e9718 290occurred. Here are all the different cases that can occur:
d1b91892
AD
291
292=over 5
293
294=item *
295
4929bf7b 296If the I<call_*> function returns normally, then the value
d1b91892
AD
297returned is as specified in the previous sections.
298
299=item *
300
301If G_DISCARD is specified, the return value will always be 0.
302
303=item *
304
305If G_ARRAY is specified I<and> an error has occurred, the return value
306will always be 0.
307
308=item *
a0d0e21e 309
d1b91892
AD
310If G_SCALAR is specified I<and> an error has occurred, the return value
311will be 1 and the value on the top of the stack will be I<undef>. This
312means that if you have already detected the error by checking C<$@> and
313you want the program to continue, you must remember to pop the I<undef>
314from the stack.
a0d0e21e
LW
315
316=back
317
54310121 318See I<Using G_EVAL> for details on using G_EVAL.
d1b91892 319
c07a80fd 320=head2 G_KEEPERR
321
7ce09284
Z
322Using the G_EVAL flag described above will always set C<$@>: clearing
323it if there was no error, and setting it to describe the error if there
324was an error in the called code. This is what you want if your intention
325is to handle possible errors, but sometimes you just want to trap errors
326and stop them interfering with the rest of the program.
327
328This scenario will mostly be applicable to code that is meant to be called
329from within destructors, asynchronous callbacks, and signal handlers.
330In such situations, where the code being called has little relation to the
331surrounding dynamic context, the main program needs to be insulated from
332errors in the called code, even if they can't be handled intelligently.
333It may also be useful to do this with code for C<__DIE__> or C<__WARN__>
334hooks, and C<tie> functions.
c07a80fd 335
336The G_KEEPERR flag is meant to be used in conjunction with G_EVAL in
be064c4a
DM
337I<call_*> functions that are used to implement such code, or with
338C<eval_sv>. This flag has no effect on the C<call_*> functions when
339G_EVAL is not used.
c07a80fd 340
7ce09284
Z
341When G_KEEPERR is used, any error in the called code will terminate the
342call as usual, and the error will not propagate beyond the call (as usual
343for G_EVAL), but it will not go into C<$@>. Instead the error will be
344converted into a warning, prefixed with the string "\t(in cleanup)".
345This can be disabled using C<no warnings 'misc'>. If there is no error,
346C<$@> will not be cleared.
c07a80fd 347
be064c4a
DM
348Note that the G_KEEPERR flag does not propagate into inner evals; these
349may still set C<$@>.
350
c07a80fd 351The G_KEEPERR flag was introduced in Perl version 5.002.
352
353See I<Using G_KEEPERR> for an example of a situation that warrants the
354use of this flag.
355
54310121 356=head2 Determining the Context
d1b91892
AD
357
358As mentioned above, you can determine the context of the currently
54310121 359executing subroutine in Perl with I<wantarray>. The equivalent test
360can be made in C by using the C<GIMME_V> macro, which returns
90fdbbb7 361C<G_ARRAY> if you have been called in a list context, C<G_SCALAR> if
02f6dca1 362in a scalar context, or C<G_VOID> if in a void context (i.e., the
54310121 363return value will not be used). An older version of this macro is
364called C<GIMME>; in a void context it returns C<G_SCALAR> instead of
365C<G_VOID>. An example of using the C<GIMME_V> macro is shown in
366section I<Using GIMME_V>.
d1b91892 367
a0d0e21e
LW
368=head1 EXAMPLES
369
02f6dca1 370Enough of the definition talk! Let's have a few examples.
a0d0e21e 371
d1b91892
AD
372Perl provides many macros to assist in accessing the Perl stack.
373Wherever possible, these macros should always be used when interfacing
5f05dabc 374to Perl internals. We hope this should make the code less vulnerable
d1b91892 375to any changes made to Perl in the future.
a0d0e21e 376
d1b91892 377Another point worth noting is that in the first series of examples I
4929bf7b 378have made use of only the I<call_pv> function. This has been done
d1b91892 379to keep the code simpler and ease you into the topic. Wherever
4929bf7b
GS
380possible, if the choice is between using I<call_pv> and
381I<call_sv>, you should always try to use I<call_sv>. See
382I<Using call_sv> for details.
a0d0e21e 383
02f6dca1 384=head2 No Parameters, Nothing Returned
a0d0e21e 385
d1b91892
AD
386This first trivial example will call a Perl subroutine, I<PrintUID>, to
387print out the UID of the process.
a0d0e21e 388
84f709e7
JH
389 sub PrintUID
390 {
4358a253 391 print "UID is $<\n";
a0d0e21e
LW
392 }
393
d1b91892 394and here is a C function to call it
a0d0e21e 395
d1b91892 396 static void
a0d0e21e
LW
397 call_PrintUID()
398 {
4358a253 399 dSP;
a0d0e21e 400
4358a253
SS
401 PUSHMARK(SP);
402 call_pv("PrintUID", G_DISCARD|G_NOARGS);
a0d0e21e
LW
403 }
404
02f6dca1 405Simple, eh?
a0d0e21e 406
02f6dca1 407A few points to note about this example:
a0d0e21e
LW
408
409=over 5
410
d1b91892 411=item 1.
a0d0e21e 412
924508f0 413Ignore C<dSP> and C<PUSHMARK(SP)> for now. They will be discussed in
d1b91892 414the next example.
a0d0e21e
LW
415
416=item 2.
417
d1b91892
AD
418We aren't passing any parameters to I<PrintUID> so G_NOARGS can be
419specified.
a0d0e21e 420
d1b91892 421=item 3.
a0d0e21e
LW
422
423We aren't interested in anything returned from I<PrintUID>, so
5f05dabc 424G_DISCARD is specified. Even if I<PrintUID> was changed to
a0d0e21e 425return some value(s), having specified G_DISCARD will mean that they
4929bf7b 426will be wiped by the time control returns from I<call_pv>.
a0d0e21e 427
d1b91892 428=item 4.
a0d0e21e 429
4929bf7b 430As I<call_pv> is being used, the Perl subroutine is specified as a
d1b91892
AD
431C string. In this case the subroutine name has been 'hard-wired' into the
432code.
a0d0e21e
LW
433
434=item 5.
435
d1b91892 436Because we specified G_DISCARD, it is not necessary to check the value
4929bf7b 437returned from I<call_pv>. It will always be 0.
a0d0e21e
LW
438
439=back
440
d1b91892 441=head2 Passing Parameters
a0d0e21e 442
d1b91892 443Now let's make a slightly more complex example. This time we want to
19799a22
GS
444call a Perl subroutine, C<LeftString>, which will take 2 parameters--a
445string ($s) and an integer ($n). The subroutine will simply
446print the first $n characters of the string.
a0d0e21e 447
02f6dca1 448So the Perl subroutine would look like this:
a0d0e21e 449
84f709e7
JH
450 sub LeftString
451 {
4358a253
SS
452 my($s, $n) = @_;
453 print substr($s, 0, $n), "\n";
a0d0e21e
LW
454 }
455
02f6dca1 456The C function required to call I<LeftString> would look like this:
a0d0e21e
LW
457
458 static void
459 call_LeftString(a, b)
4358a253
SS
460 char * a;
461 int b;
a0d0e21e 462 {
4358a253 463 dSP;
a0d0e21e 464
4358a253
SS
465 ENTER;
466 SAVETMPS;
9b6570b4 467
4358a253 468 PUSHMARK(SP);
a0d0e21e
LW
469 XPUSHs(sv_2mortal(newSVpv(a, 0)));
470 XPUSHs(sv_2mortal(newSViv(b)));
4358a253 471 PUTBACK;
a0d0e21e 472
4929bf7b 473 call_pv("LeftString", G_DISCARD);
9b6570b4 474
4358a253
SS
475 FREETMPS;
476 LEAVE;
a0d0e21e
LW
477 }
478
a0d0e21e
LW
479Here are a few notes on the C function I<call_LeftString>.
480
481=over 5
482
d1b91892 483=item 1.
a0d0e21e 484
d1b91892
AD
485Parameters are passed to the Perl subroutine using the Perl stack.
486This is the purpose of the code beginning with the line C<dSP> and
1e62ac33 487ending with the line C<PUTBACK>. The C<dSP> declares a local copy
924508f0
GS
488of the stack pointer. This local copy should B<always> be accessed
489as C<SP>.
a0d0e21e 490
d1b91892 491=item 2.
a0d0e21e
LW
492
493If you are going to put something onto the Perl stack, you need to know
19799a22 494where to put it. This is the purpose of the macro C<dSP>--it declares
d1b91892 495and initializes a I<local> copy of the Perl stack pointer.
a0d0e21e
LW
496
497All the other macros which will be used in this example require you to
d1b91892 498have used this macro.
a0d0e21e 499
d1b91892
AD
500The exception to this rule is if you are calling a Perl subroutine
501directly from an XSUB function. In this case it is not necessary to
19799a22 502use the C<dSP> macro explicitly--it will be declared for you
d1b91892 503automatically.
a0d0e21e 504
d1b91892 505=item 3.
a0d0e21e
LW
506
507Any parameters to be pushed onto the stack should be bracketed by the
d1b91892 508C<PUSHMARK> and C<PUTBACK> macros. The purpose of these two macros, in
5f05dabc 509this context, is to count the number of parameters you are
510pushing automatically. Then whenever Perl is creating the C<@_> array for the
d1b91892
AD
511subroutine, it knows how big to make it.
512
513The C<PUSHMARK> macro tells Perl to make a mental note of the current
514stack pointer. Even if you aren't passing any parameters (like the
02f6dca1 515example shown in the section I<No Parameters, Nothing Returned>) you
d1b91892 516must still call the C<PUSHMARK> macro before you can call any of the
4929bf7b 517I<call_*> functions--Perl still needs to know that there are no
d1b91892
AD
518parameters.
519
520The C<PUTBACK> macro sets the global copy of the stack pointer to be
02f6dca1 521the same as our local copy. If we didn't do this, I<call_pv>
19799a22 522wouldn't know where the two parameters we pushed were--remember that
d1b91892
AD
523up to now all the stack pointer manipulation we have done is with our
524local copy, I<not> the global copy.
525
526=item 4.
527
a0d0e21e 528Next, we come to XPUSHs. This is where the parameters actually get
d1b91892
AD
529pushed onto the stack. In this case we are pushing a string and an
530integer.
a0d0e21e 531
54310121 532See L<perlguts/"XSUBs and the Argument Stack"> for details
d1b91892 533on how the XPUSH macros work.
a0d0e21e 534
087fe227 535=item 5.
a0d0e21e 536
9b6570b4
AB
537Because we created temporary values (by means of sv_2mortal() calls)
538we will have to tidy up the Perl stack and dispose of mortal SVs.
539
540This is the purpose of
541
4358a253
SS
542 ENTER;
543 SAVETMPS;
9b6570b4
AB
544
545at the start of the function, and
546
4358a253
SS
547 FREETMPS;
548 LEAVE;
9b6570b4
AB
549
550at the end. The C<ENTER>/C<SAVETMPS> pair creates a boundary for any
551temporaries we create. This means that the temporaries we get rid of
552will be limited to those which were created after these calls.
553
554The C<FREETMPS>/C<LEAVE> pair will get rid of any values returned by
555the Perl subroutine (see next example), plus it will also dump the
556mortal SVs we have created. Having C<ENTER>/C<SAVETMPS> at the
557beginning of the code makes sure that no other mortals are destroyed.
558
02f6dca1 559Think of these macros as working a bit like C<{> and C<}> in Perl
9b6570b4
AB
560to limit the scope of local variables.
561
02f6dca1 562See the section I<Using Perl to Dispose of Temporaries> for details of
9b6570b4
AB
563an alternative to using these macros.
564
087fe227 565=item 6.
9b6570b4 566
087fe227
JA
567Finally, I<LeftString> can now be called via the I<call_pv> function.
568The only flag specified this time is G_DISCARD. Because we are passing
5692 parameters to the Perl subroutine this time, we have not specified
570G_NOARGS.
a0d0e21e
LW
571
572=back
573
d1b91892 574=head2 Returning a Scalar
a0d0e21e 575
d1b91892
AD
576Now for an example of dealing with the items returned from a Perl
577subroutine.
a0d0e21e 578
5f05dabc 579Here is a Perl subroutine, I<Adder>, that takes 2 integer parameters
d1b91892 580and simply returns their sum.
a0d0e21e 581
84f709e7
JH
582 sub Adder
583 {
4358a253
SS
584 my($a, $b) = @_;
585 $a + $b;
a0d0e21e
LW
586 }
587
5f05dabc 588Because we are now concerned with the return value from I<Adder>, the C
d1b91892 589function required to call it is now a bit more complex.
a0d0e21e
LW
590
591 static void
592 call_Adder(a, b)
4358a253
SS
593 int a;
594 int b;
a0d0e21e 595 {
4358a253
SS
596 dSP;
597 int count;
a0d0e21e 598
4358a253 599 ENTER;
a0d0e21e
LW
600 SAVETMPS;
601
4358a253 602 PUSHMARK(SP);
a0d0e21e
LW
603 XPUSHs(sv_2mortal(newSViv(a)));
604 XPUSHs(sv_2mortal(newSViv(b)));
4358a253 605 PUTBACK;
a0d0e21e 606
4929bf7b 607 count = call_pv("Adder", G_SCALAR);
a0d0e21e 608
4358a253 609 SPAGAIN;
a0d0e21e 610
d1b91892 611 if (count != 1)
4358a253 612 croak("Big trouble\n");
a0d0e21e 613
4358a253 614 printf ("The sum of %d and %d is %d\n", a, b, POPi);
a0d0e21e 615
4358a253
SS
616 PUTBACK;
617 FREETMPS;
618 LEAVE;
a0d0e21e
LW
619 }
620
a0d0e21e
LW
621Points to note this time are
622
623=over 5
624
54310121 625=item 1.
a0d0e21e 626
02f6dca1 627The only flag specified this time was G_SCALAR. That means that the C<@_>
d1b91892 628array will be created and that the value returned by I<Adder> will
4929bf7b 629still exist after the call to I<call_pv>.
a0d0e21e 630
a0d0e21e
LW
631=item 2.
632
a0d0e21e
LW
633The purpose of the macro C<SPAGAIN> is to refresh the local copy of the
634stack pointer. This is necessary because it is possible that the memory
ed874981 635allocated to the Perl stack has been reallocated during the
4929bf7b 636I<call_pv> call.
a0d0e21e 637
d1b91892 638If you are making use of the Perl stack pointer in your code you must
54310121 639always refresh the local copy using SPAGAIN whenever you make use
4929bf7b 640of the I<call_*> functions or any other Perl internal function.
a0d0e21e 641
9b6570b4 642=item 3.
a0d0e21e 643
d1b91892 644Although only a single value was expected to be returned from I<Adder>,
4929bf7b 645it is still good practice to check the return code from I<call_pv>
d1b91892 646anyway.
a0d0e21e 647
d1b91892
AD
648Expecting a single value is not quite the same as knowing that there
649will be one. If someone modified I<Adder> to return a list and we
650didn't check for that possibility and take appropriate action the Perl
651stack would end up in an inconsistent state. That is something you
5f05dabc 652I<really> don't want to happen ever.
a0d0e21e 653
9b6570b4 654=item 4.
a0d0e21e 655
d1b91892
AD
656The C<POPi> macro is used here to pop the return value from the stack.
657In this case we wanted an integer, so C<POPi> was used.
a0d0e21e
LW
658
659
d1b91892
AD
660Here is the complete list of POP macros available, along with the types
661they return.
a0d0e21e 662
d1b91892
AD
663 POPs SV
664 POPp pointer
665 POPn double
666 POPi integer
667 POPl long
a0d0e21e 668
9b6570b4 669=item 5.
a0d0e21e 670
d1b91892
AD
671The final C<PUTBACK> is used to leave the Perl stack in a consistent
672state before exiting the function. This is necessary because when we
673popped the return value from the stack with C<POPi> it updated only our
674local copy of the stack pointer. Remember, C<PUTBACK> sets the global
675stack pointer to be the same as our local copy.
a0d0e21e
LW
676
677=back
678
679
02f6dca1 680=head2 Returning a List of Values
a0d0e21e 681
d1b91892
AD
682Now, let's extend the previous example to return both the sum of the
683parameters and the difference.
a0d0e21e 684
d1b91892 685Here is the Perl subroutine
a0d0e21e 686
84f709e7
JH
687 sub AddSubtract
688 {
4358a253
SS
689 my($a, $b) = @_;
690 ($a+$b, $a-$b);
a0d0e21e
LW
691 }
692
a0d0e21e
LW
693and this is the C function
694
695 static void
696 call_AddSubtract(a, b)
4358a253
SS
697 int a;
698 int b;
a0d0e21e 699 {
4358a253
SS
700 dSP;
701 int count;
a0d0e21e 702
4358a253 703 ENTER;
a0d0e21e
LW
704 SAVETMPS;
705
4358a253 706 PUSHMARK(SP);
a0d0e21e
LW
707 XPUSHs(sv_2mortal(newSViv(a)));
708 XPUSHs(sv_2mortal(newSViv(b)));
4358a253 709 PUTBACK;
a0d0e21e 710
4929bf7b 711 count = call_pv("AddSubtract", G_ARRAY);
a0d0e21e 712
4358a253 713 SPAGAIN;
a0d0e21e 714
d1b91892 715 if (count != 2)
4358a253 716 croak("Big trouble\n");
a0d0e21e 717
4358a253
SS
718 printf ("%d - %d = %d\n", a, b, POPi);
719 printf ("%d + %d = %d\n", a, b, POPi);
a0d0e21e 720
4358a253
SS
721 PUTBACK;
722 FREETMPS;
723 LEAVE;
a0d0e21e
LW
724 }
725
d1b91892
AD
726If I<call_AddSubtract> is called like this
727
4358a253 728 call_AddSubtract(7, 4);
d1b91892
AD
729
730then here is the output
731
732 7 - 4 = 3
733 7 + 4 = 11
a0d0e21e
LW
734
735Notes
736
737=over 5
738
739=item 1.
740
90fdbbb7 741We wanted list context, so G_ARRAY was used.
a0d0e21e
LW
742
743=item 2.
744
d1b91892
AD
745Not surprisingly C<POPi> is used twice this time because we were
746retrieving 2 values from the stack. The important thing to note is that
747when using the C<POP*> macros they come off the stack in I<reverse>
748order.
a0d0e21e
LW
749
750=back
751
02f6dca1 752=head2 Returning a List in a Scalar Context
d1b91892
AD
753
754Say the Perl subroutine in the previous section was called in a scalar
755context, like this
756
757 static void
758 call_AddSubScalar(a, b)
4358a253
SS
759 int a;
760 int b;
d1b91892 761 {
4358a253
SS
762 dSP;
763 int count;
764 int i;
d1b91892 765
4358a253 766 ENTER;
d1b91892
AD
767 SAVETMPS;
768
4358a253 769 PUSHMARK(SP);
d1b91892
AD
770 XPUSHs(sv_2mortal(newSViv(a)));
771 XPUSHs(sv_2mortal(newSViv(b)));
4358a253 772 PUTBACK;
d1b91892 773
4929bf7b 774 count = call_pv("AddSubtract", G_SCALAR);
d1b91892 775
4358a253 776 SPAGAIN;
d1b91892 777
4358a253 778 printf ("Items Returned = %d\n", count);
d1b91892 779
4358a253
SS
780 for (i = 1; i <= count; ++i)
781 printf ("Value %d = %d\n", i, POPi);
d1b91892 782
4358a253
SS
783 PUTBACK;
784 FREETMPS;
785 LEAVE;
d1b91892
AD
786 }
787
788The other modification made is that I<call_AddSubScalar> will print the
789number of items returned from the Perl subroutine and their value (for
790simplicity it assumes that they are integer). So if
791I<call_AddSubScalar> is called
792
4358a253 793 call_AddSubScalar(7, 4);
d1b91892
AD
794
795then the output will be
796
797 Items Returned = 1
798 Value 1 = 3
799
800In this case the main point to note is that only the last item in the
48052fe5 801list is returned from the subroutine. I<AddSubtract> actually made it back to
d1b91892
AD
802I<call_AddSubScalar>.
803
804
02f6dca1 805=head2 Returning Data from Perl via the Parameter List
a0d0e21e 806
48052fe5
FC
807It is also possible to return values directly via the parameter
808list--whether it is actually desirable to do it is another matter entirely.
a0d0e21e 809
d1b91892
AD
810The Perl subroutine, I<Inc>, below takes 2 parameters and increments
811each directly.
a0d0e21e 812
84f709e7
JH
813 sub Inc
814 {
4358a253
SS
815 ++ $_[0];
816 ++ $_[1];
a0d0e21e
LW
817 }
818
819and here is a C function to call it.
820
821 static void
822 call_Inc(a, b)
4358a253
SS
823 int a;
824 int b;
a0d0e21e 825 {
4358a253
SS
826 dSP;
827 int count;
828 SV * sva;
829 SV * svb;
a0d0e21e 830
4358a253 831 ENTER;
a0d0e21e
LW
832 SAVETMPS;
833
4358a253
SS
834 sva = sv_2mortal(newSViv(a));
835 svb = sv_2mortal(newSViv(b));
a0d0e21e 836
4358a253 837 PUSHMARK(SP);
a0d0e21e
LW
838 XPUSHs(sva);
839 XPUSHs(svb);
4358a253 840 PUTBACK;
a0d0e21e 841
4929bf7b 842 count = call_pv("Inc", G_DISCARD);
a0d0e21e
LW
843
844 if (count != 0)
d1b91892 845 croak ("call_Inc: expected 0 values from 'Inc', got %d\n",
4358a253 846 count);
a0d0e21e 847
4358a253
SS
848 printf ("%d + 1 = %d\n", a, SvIV(sva));
849 printf ("%d + 1 = %d\n", b, SvIV(svb));
a0d0e21e 850
4358a253
SS
851 FREETMPS;
852 LEAVE;
a0d0e21e
LW
853 }
854
d1b91892 855To be able to access the two parameters that were pushed onto the stack
4929bf7b 856after they return from I<call_pv> it is necessary to make a note
19799a22 857of their addresses--thus the two variables C<sva> and C<svb>.
a0d0e21e 858
d1b91892
AD
859The reason this is necessary is that the area of the Perl stack which
860held them will very likely have been overwritten by something else by
4929bf7b 861the time control returns from I<call_pv>.
a0d0e21e
LW
862
863
864
865
d1b91892 866=head2 Using G_EVAL
a0d0e21e 867
d1b91892
AD
868Now an example using G_EVAL. Below is a Perl subroutine which computes
869the difference of its 2 parameters. If this would result in a negative
870result, the subroutine calls I<die>.
a0d0e21e 871
84f709e7
JH
872 sub Subtract
873 {
4358a253 874 my ($a, $b) = @_;
a0d0e21e 875
4358a253 876 die "death can be fatal\n" if $a < $b;
a0d0e21e 877
4358a253 878 $a - $b;
a0d0e21e
LW
879 }
880
881and some C to call it
882
883 static void
884 call_Subtract(a, b)
4358a253
SS
885 int a;
886 int b;
a0d0e21e 887 {
4358a253
SS
888 dSP;
889 int count;
a0d0e21e 890
4358a253 891 ENTER;
a0d0e21e
LW
892 SAVETMPS;
893
4358a253 894 PUSHMARK(SP);
a0d0e21e
LW
895 XPUSHs(sv_2mortal(newSViv(a)));
896 XPUSHs(sv_2mortal(newSViv(b)));
4358a253 897 PUTBACK;
a0d0e21e 898
4929bf7b 899 count = call_pv("Subtract", G_EVAL|G_SCALAR);
a0d0e21e 900
4358a253 901 SPAGAIN;
d1b91892
AD
902
903 /* Check the eval first */
9cde0e7f 904 if (SvTRUE(ERRSV))
d1b91892 905 {
1c5b513e 906 printf ("Uh oh - %s\n", SvPV_nolen(ERRSV));
4358a253 907 POPs;
d1b91892
AD
908 }
909 else
910 {
911 if (count != 1)
912 croak("call_Subtract: wanted 1 value from 'Subtract', got %d\n",
4358a253 913 count);
a0d0e21e 914
4358a253 915 printf ("%d - %d = %d\n", a, b, POPi);
d1b91892 916 }
a0d0e21e 917
4358a253
SS
918 PUTBACK;
919 FREETMPS;
920 LEAVE;
a0d0e21e
LW
921 }
922
923If I<call_Subtract> is called thus
924
d1b91892 925 call_Subtract(4, 5)
a0d0e21e
LW
926
927the following will be printed
928
d1b91892 929 Uh oh - death can be fatal
a0d0e21e
LW
930
931Notes
932
933=over 5
934
935=item 1.
936
d1b91892
AD
937We want to be able to catch the I<die> so we have used the G_EVAL
938flag. Not specifying this flag would mean that the program would
939terminate immediately at the I<die> statement in the subroutine
940I<Subtract>.
a0d0e21e
LW
941
942=item 2.
943
54310121 944The code
a0d0e21e 945
9cde0e7f 946 if (SvTRUE(ERRSV))
d1b91892 947 {
1c5b513e 948 printf ("Uh oh - %s\n", SvPV_nolen(ERRSV));
4358a253 949 POPs;
d1b91892 950 }
a0d0e21e 951
d1b91892 952is the direct equivalent of this bit of Perl
a0d0e21e 953
4358a253 954 print "Uh oh - $@\n" if $@;
a0d0e21e 955
9cde0e7f
GS
956C<PL_errgv> is a perl global of type C<GV *> that points to the
957symbol table entry containing the error. C<ERRSV> therefore
c07a80fd 958refers to the C equivalent of C<$@>.
959
d1b91892 960=item 3.
a0d0e21e 961
d1b91892 962Note that the stack is popped using C<POPs> in the block where
9cde0e7f 963C<SvTRUE(ERRSV)> is true. This is necessary because whenever a
4929bf7b 964I<call_*> function invoked with G_EVAL|G_SCALAR returns an error,
5f05dabc 965the top of the stack holds the value I<undef>. Because we want the
d1b91892 966program to continue after detecting this error, it is essential that
6c818a50 967the stack be tidied up by removing the I<undef>.
a0d0e21e
LW
968
969=back
970
971
c07a80fd 972=head2 Using G_KEEPERR
973
974Consider this rather facetious example, where we have used an XS
975version of the call_Subtract example above inside a destructor:
976
977 package Foo;
84f709e7 978 sub new { bless {}, $_[0] }
54310121 979 sub Subtract {
84f709e7 980 my($a,$b) = @_;
4358a253 981 die "death can be fatal" if $a < $b;
84f709e7 982 $a - $b;
c07a80fd 983 }
84f709e7
JH
984 sub DESTROY { call_Subtract(5, 4); }
985 sub foo { die "foo dies"; }
c07a80fd 986
987 package main;
7ce09284
Z
988 {
989 my $foo = Foo->new;
990 eval { $foo->foo };
991 }
c07a80fd 992 print "Saw: $@" if $@; # should be, but isn't
993
994This example will fail to recognize that an error occurred inside the
995C<eval {}>. Here's why: the call_Subtract code got executed while perl
7ce09284 996was cleaning up temporaries when exiting the outer braced block, and because
4929bf7b 997call_Subtract is implemented with I<call_pv> using the G_EVAL
c07a80fd 998flag, it promptly reset C<$@>. This results in the failure of the
999outermost test for C<$@>, and thereby the failure of the error trap.
1000
4929bf7b 1001Appending the G_KEEPERR flag, so that the I<call_pv> call in
c07a80fd 1002call_Subtract reads:
1003
4929bf7b 1004 count = call_pv("Subtract", G_EVAL|G_SCALAR|G_KEEPERR);
c07a80fd 1005
1006will preserve the error and restore reliable error handling.
1007
4929bf7b 1008=head2 Using call_sv
a0d0e21e 1009
d1b91892
AD
1010In all the previous examples I have 'hard-wired' the name of the Perl
1011subroutine to be called from C. Most of the time though, it is more
1012convenient to be able to specify the name of the Perl subroutine from
1013within the Perl script.
a0d0e21e
LW
1014
1015Consider the Perl code below
1016
84f709e7
JH
1017 sub fred
1018 {
4358a253 1019 print "Hello there\n";
d1b91892
AD
1020 }
1021
4358a253 1022 CallSubPV("fred");
d1b91892
AD
1023
1024Here is a snippet of XSUB which defines I<CallSubPV>.
1025
1026 void
1027 CallSubPV(name)
1028 char * name
1029 CODE:
4358a253
SS
1030 PUSHMARK(SP);
1031 call_pv(name, G_DISCARD|G_NOARGS);
a0d0e21e 1032
54310121 1033That is fine as far as it goes. The thing is, the Perl subroutine
94a37a2f
BF
1034can be specified as only a string, however, Perl allows references
1035to subroutines and anonymous subroutines.
4929bf7b 1036This is where I<call_sv> is useful.
d1b91892
AD
1037
1038The code below for I<CallSubSV> is identical to I<CallSubPV> except
1039that the C<name> parameter is now defined as an SV* and we use
4929bf7b 1040I<call_sv> instead of I<call_pv>.
d1b91892
AD
1041
1042 void
1043 CallSubSV(name)
1044 SV * name
1045 CODE:
4358a253
SS
1046 PUSHMARK(SP);
1047 call_sv(name, G_DISCARD|G_NOARGS);
a0d0e21e 1048
1d45ec27 1049Because we are using an SV to call I<fred> the following can all be used:
a0d0e21e 1050
4358a253
SS
1051 CallSubSV("fred");
1052 CallSubSV(\&fred);
1053 $ref = \&fred;
1054 CallSubSV($ref);
1055 CallSubSV( sub { print "Hello there\n" } );
a0d0e21e 1056
4929bf7b 1057As you can see, I<call_sv> gives you much greater flexibility in
d1b91892
AD
1058how you can specify the Perl subroutine.
1059
1d45ec27 1060You should note that, if it is necessary to store the SV (C<name> in the
d1b91892 1061example above) which corresponds to the Perl subroutine so that it can
5f05dabc 1062be used later in the program, it not enough just to store a copy of the
1d45ec27 1063pointer to the SV. Say the code above had been like this:
d1b91892 1064
4358a253 1065 static SV * rememberSub;
d1b91892
AD
1066
1067 void
1068 SaveSub1(name)
1069 SV * name
1070 CODE:
4358a253 1071 rememberSub = name;
d1b91892
AD
1072
1073 void
1074 CallSavedSub1()
1075 CODE:
4358a253
SS
1076 PUSHMARK(SP);
1077 call_sv(rememberSub, G_DISCARD|G_NOARGS);
a0d0e21e 1078
1d45ec27 1079The reason this is wrong is that, by the time you come to use the
d1b91892
AD
1080pointer C<rememberSub> in C<CallSavedSub1>, it may or may not still refer
1081to the Perl subroutine that was recorded in C<SaveSub1>. This is
1d45ec27 1082particularly true for these cases:
a0d0e21e 1083
4358a253
SS
1084 SaveSub1(\&fred);
1085 CallSavedSub1();
a0d0e21e 1086
4358a253
SS
1087 SaveSub1( sub { print "Hello there\n" } );
1088 CallSavedSub1();
a0d0e21e 1089
1d45ec27 1090By the time each of the C<SaveSub1> statements above has been executed,
54310121 1091the SV*s which corresponded to the parameters will no longer exist.
d1b91892 1092Expect an error message from Perl of the form
a0d0e21e 1093
d1b91892 1094 Can't use an undefined value as a subroutine reference at ...
a0d0e21e 1095
d1b91892 1096for each of the C<CallSavedSub1> lines.
a0d0e21e 1097
54310121 1098Similarly, with this code
a0d0e21e 1099
4358a253
SS
1100 $ref = \&fred;
1101 SaveSub1($ref);
1102 $ref = 47;
1103 CallSavedSub1();
a0d0e21e 1104
54310121 1105you can expect one of these messages (which you actually get is dependent on
1106the version of Perl you are using)
a0d0e21e 1107
d1b91892
AD
1108 Not a CODE reference at ...
1109 Undefined subroutine &main::47 called ...
a0d0e21e 1110
19799a22 1111The variable $ref may have referred to the subroutine C<fred>
d1b91892 1112whenever the call to C<SaveSub1> was made but by the time
5f05dabc 1113C<CallSavedSub1> gets called it now holds the number C<47>. Because we
d1b91892 1114saved only a pointer to the original SV in C<SaveSub1>, any changes to
19799a22 1115$ref will be tracked by the pointer C<rememberSub>. This means that
d1b91892
AD
1116whenever C<CallSavedSub1> gets called, it will attempt to execute the
1117code which is referenced by the SV* C<rememberSub>. In this case
1118though, it now refers to the integer C<47>, so expect Perl to complain
1119loudly.
a0d0e21e 1120
1d45ec27 1121A similar but more subtle problem is illustrated with this code:
a0d0e21e 1122
4358a253
SS
1123 $ref = \&fred;
1124 SaveSub1($ref);
1125 $ref = \&joe;
1126 CallSavedSub1();
a0d0e21e 1127
1d45ec27 1128This time whenever C<CallSavedSub1> gets called it will execute the Perl
54310121 1129subroutine C<joe> (assuming it exists) rather than C<fred> as was
d1b91892 1130originally requested in the call to C<SaveSub1>.
a0d0e21e 1131
d1b91892 1132To get around these problems it is necessary to take a full copy of the
1d45ec27 1133SV. The code below shows C<SaveSub2> modified to do that.
a0d0e21e 1134
4358a253 1135 static SV * keepSub = (SV*)NULL;
d1b91892
AD
1136
1137 void
1138 SaveSub2(name)
1139 SV * name
1140 CODE:
1141 /* Take a copy of the callback */
1142 if (keepSub == (SV*)NULL)
1143 /* First time, so create a new SV */
4358a253 1144 keepSub = newSVsv(name);
d1b91892
AD
1145 else
1146 /* Been here before, so overwrite */
4358a253 1147 SvSetSV(keepSub, name);
d1b91892
AD
1148
1149 void
1150 CallSavedSub2()
1151 CODE:
4358a253
SS
1152 PUSHMARK(SP);
1153 call_sv(keepSub, G_DISCARD|G_NOARGS);
d1b91892 1154
5f05dabc 1155To avoid creating a new SV every time C<SaveSub2> is called,
d1b91892
AD
1156the function first checks to see if it has been called before. If not,
1157then space for a new SV is allocated and the reference to the Perl
1d45ec27
FC
1158subroutine C<name> is copied to the variable C<keepSub> in one
1159operation using C<newSVsv>. Thereafter, whenever C<SaveSub2> is called,
d1b91892
AD
1160the existing SV, C<keepSub>, is overwritten with the new value using
1161C<SvSetSV>.
1162
4929bf7b 1163=head2 Using call_argv
d1b91892
AD
1164
1165Here is a Perl subroutine which prints whatever parameters are passed
1166to it.
1167
84f709e7
JH
1168 sub PrintList
1169 {
4358a253 1170 my(@list) = @_;
d1b91892 1171
84f709e7 1172 foreach (@list) { print "$_\n" }
d1b91892
AD
1173 }
1174
1d45ec27 1175And here is an example of I<call_argv> which will call
d1b91892
AD
1176I<PrintList>.
1177
4358a253 1178 static char * words[] = {"alpha", "beta", "gamma", "delta", NULL};
d1b91892
AD
1179
1180 static void
1181 call_PrintList()
1182 {
4358a253 1183 dSP;
d1b91892 1184
4358a253 1185 call_argv("PrintList", G_DISCARD, words);
d1b91892
AD
1186 }
1187
1188Note that it is not necessary to call C<PUSHMARK> in this instance.
4929bf7b 1189This is because I<call_argv> will do it for you.
d1b91892 1190
4929bf7b 1191=head2 Using call_method
a0d0e21e 1192
1d45ec27 1193Consider the following Perl code:
a0d0e21e 1194
d1b91892 1195 {
4358a253 1196 package Mine;
84f709e7
JH
1197
1198 sub new
1199 {
4358a253 1200 my($type) = shift;
84f709e7
JH
1201 bless [@_]
1202 }
1203
1204 sub Display
1205 {
4358a253
SS
1206 my ($self, $index) = @_;
1207 print "$index: $$self[$index]\n";
84f709e7
JH
1208 }
1209
1210 sub PrintID
1211 {
4358a253
SS
1212 my($class) = @_;
1213 print "This is Class $class version 1.0\n";
84f709e7 1214 }
d1b91892
AD
1215 }
1216
5f05dabc 1217It implements just a very simple class to manage an array. Apart from
d1b91892 1218the constructor, C<new>, it declares methods, one static and one
5f05dabc 1219virtual. The static method, C<PrintID>, prints out simply the class
d1b91892 1220name and a version number. The virtual method, C<Display>, prints out a
1d45ec27 1221single element of the array. Here is an all-Perl example of using it.
d1b91892 1222
797f796a 1223 $a = Mine->new('red', 'green', 'blue');
4358a253 1224 $a->Display(1);
797f796a 1225 Mine->PrintID;
a0d0e21e 1226
d1b91892 1227will print
a0d0e21e 1228
d1b91892 1229 1: green
54310121 1230 This is Class Mine version 1.0
a0d0e21e 1231
d1b91892 1232Calling a Perl method from C is fairly straightforward. The following
1d45ec27 1233things are required:
a0d0e21e 1234
d1b91892
AD
1235=over 5
1236
1237=item *
1238
1d45ec27
FC
1239A reference to the object for a virtual method or the name of the class
1240for a static method
d1b91892
AD
1241
1242=item *
1243
1d45ec27 1244The name of the method
d1b91892
AD
1245
1246=item *
1247
1d45ec27 1248Any other parameters specific to the method
d1b91892
AD
1249
1250=back
1251
1252Here is a simple XSUB which illustrates the mechanics of calling both
1253the C<PrintID> and C<Display> methods from C.
1254
1255 void
1256 call_Method(ref, method, index)
1257 SV * ref
1258 char * method
1259 int index
1260 CODE:
924508f0 1261 PUSHMARK(SP);
d1b91892 1262 XPUSHs(ref);
4358a253 1263 XPUSHs(sv_2mortal(newSViv(index)));
d1b91892
AD
1264 PUTBACK;
1265
4358a253 1266 call_method(method, G_DISCARD);
d1b91892
AD
1267
1268 void
1269 call_PrintID(class, method)
1270 char * class
1271 char * method
1272 CODE:
924508f0 1273 PUSHMARK(SP);
4358a253 1274 XPUSHs(sv_2mortal(newSVpv(class, 0)));
d1b91892
AD
1275 PUTBACK;
1276
4358a253 1277 call_method(method, G_DISCARD);
d1b91892
AD
1278
1279
1d45ec27 1280So the methods C<PrintID> and C<Display> can be invoked like this:
d1b91892 1281
797f796a 1282 $a = Mine->new('red', 'green', 'blue');
4358a253
SS
1283 call_Method($a, 'Display', 1);
1284 call_PrintID('Mine', 'PrintID');
d1b91892 1285
1d45ec27 1286The only thing to note is that, in both the static and virtual methods,
19799a22 1287the method name is not passed via the stack--it is used as the first
4929bf7b 1288parameter to I<call_method>.
d1b91892 1289
54310121 1290=head2 Using GIMME_V
d1b91892 1291
54310121 1292Here is a trivial XSUB which prints the context in which it is
d1b91892
AD
1293currently executing.
1294
1295 void
1296 PrintContext()
1297 CODE:
54310121 1298 I32 gimme = GIMME_V;
1299 if (gimme == G_VOID)
4358a253 1300 printf ("Context is Void\n");
54310121 1301 else if (gimme == G_SCALAR)
4358a253 1302 printf ("Context is Scalar\n");
d1b91892 1303 else
4358a253 1304 printf ("Context is Array\n");
d1b91892 1305
1d45ec27 1306And here is some Perl to test it.
d1b91892 1307
4358a253
SS
1308 PrintContext;
1309 $a = PrintContext;
1310 @a = PrintContext;
d1b91892
AD
1311
1312The output from that will be
1313
54310121 1314 Context is Void
d1b91892
AD
1315 Context is Scalar
1316 Context is Array
1317
02f6dca1 1318=head2 Using Perl to Dispose of Temporaries
d1b91892
AD
1319
1320In the examples given to date, any temporaries created in the callback
4929bf7b 1321(i.e., parameters passed on the stack to the I<call_*> function or
1d45ec27 1322values returned via the stack) have been freed by one of these methods:
d1b91892
AD
1323
1324=over 5
1325
1326=item *
1327
1d45ec27 1328Specifying the G_DISCARD flag with I<call_*>
d1b91892
AD
1329
1330=item *
1331
1d45ec27 1332Explicitly using the C<ENTER>/C<SAVETMPS>--C<FREETMPS>/C<LEAVE> pairing
d1b91892
AD
1333
1334=back
1335
1336There is another method which can be used, namely letting Perl do it
1337for you automatically whenever it regains control after the callback
1338has terminated. This is done by simply not using the
1339
4358a253
SS
1340 ENTER;
1341 SAVETMPS;
d1b91892 1342 ...
4358a253
SS
1343 FREETMPS;
1344 LEAVE;
d1b91892
AD
1345
1346sequence in the callback (and not, of course, specifying the G_DISCARD
1347flag).
1348
1349If you are going to use this method you have to be aware of a possible
1350memory leak which can arise under very specific circumstances. To
1351explain these circumstances you need to know a bit about the flow of
1352control between Perl and the callback routine.
1353
1354The examples given at the start of the document (an error handler and
1355an event driven program) are typical of the two main sorts of flow
1356control that you are likely to encounter with callbacks. There is a
1357very important distinction between them, so pay attention.
1358
1359In the first example, an error handler, the flow of control could be as
1360follows. You have created an interface to an external library.
1361Control can reach the external library like this
1362
1363 perl --> XSUB --> external library
1364
1365Whilst control is in the library, an error condition occurs. You have
1366previously set up a Perl callback to handle this situation, so it will
1367get executed. Once the callback has finished, control will drop back to
1368Perl again. Here is what the flow of control will be like in that
1369situation
1370
1371 perl --> XSUB --> external library
1372 ...
1373 error occurs
1374 ...
4929bf7b 1375 external library --> call_* --> perl
d1b91892 1376 |
4929bf7b 1377 perl <-- XSUB <-- external library <-- call_* <----+
d1b91892 1378
4929bf7b 1379After processing of the error using I<call_*> is completed,
d1b91892
AD
1380control reverts back to Perl more or less immediately.
1381
1382In the diagram, the further right you go the more deeply nested the
1383scope is. It is only when control is back with perl on the extreme
1384left of the diagram that you will have dropped back to the enclosing
1385scope and any temporaries you have left hanging around will be freed.
1386
1387In the second example, an event driven program, the flow of control
1388will be more like this
1389
1390 perl --> XSUB --> event handler
1391 ...
4929bf7b 1392 event handler --> call_* --> perl
d1b91892 1393 |
4929bf7b 1394 event handler <-- call_* <----+
d1b91892 1395 ...
4929bf7b 1396 event handler --> call_* --> perl
d1b91892 1397 |
4929bf7b 1398 event handler <-- call_* <----+
d1b91892 1399 ...
4929bf7b 1400 event handler --> call_* --> perl
d1b91892 1401 |
4929bf7b 1402 event handler <-- call_* <----+
d1b91892
AD
1403
1404In this case the flow of control can consist of only the repeated
1405sequence
1406
4929bf7b 1407 event handler --> call_* --> perl
d1b91892 1408
54310121 1409for practically the complete duration of the program. This means that
1410control may I<never> drop back to the surrounding scope in Perl at the
1411extreme left.
d1b91892
AD
1412
1413So what is the big problem? Well, if you are expecting Perl to tidy up
1414those temporaries for you, you might be in for a long wait. For Perl
5f05dabc 1415to dispose of your temporaries, control must drop back to the
d1b91892 1416enclosing scope at some stage. In the event driven scenario that may
1d45ec27 1417never happen. This means that, as time goes on, your program will
d1b91892
AD
1418create more and more temporaries, none of which will ever be freed. As
1419each of these temporaries consumes some memory your program will
19799a22 1420eventually consume all the available memory in your system--kapow!
d1b91892 1421
19799a22 1422So here is the bottom line--if you are sure that control will revert
d1b91892 1423back to the enclosing Perl scope fairly quickly after the end of your
5f05dabc 1424callback, then it isn't absolutely necessary to dispose explicitly of
d1b91892
AD
1425any temporaries you may have created. Mind you, if you are at all
1426uncertain about what to do, it doesn't do any harm to tidy up anyway.
1427
1428
02f6dca1 1429=head2 Strategies for Storing Callback Context Information
d1b91892
AD
1430
1431
1432Potentially one of the trickiest problems to overcome when designing a
1433callback interface can be figuring out how to store the mapping between
1434the C callback function and the Perl equivalent.
1435
1436To help understand why this can be a real problem first consider how a
1437callback is set up in an all C environment. Typically a C API will
1438provide a function to register a callback. This will expect a pointer
1439to a function as one of its parameters. Below is a call to a
1440hypothetical function C<register_fatal> which registers the C function
1441to get called when a fatal error occurs.
1442
4358a253 1443 register_fatal(cb1);
d1b91892
AD
1444
1445The single parameter C<cb1> is a pointer to a function, so you must
1446have defined C<cb1> in your code, say something like this
1447
1448 static void
1449 cb1()
1450 {
4358a253
SS
1451 printf ("Fatal Error\n");
1452 exit(1);
d1b91892
AD
1453 }
1454
1455Now change that to call a Perl subroutine instead
1456
1457 static SV * callback = (SV*)NULL;
1458
1459 static void
1460 cb1()
1461 {
4358a253 1462 dSP;
d1b91892 1463
4358a253 1464 PUSHMARK(SP);
d1b91892
AD
1465
1466 /* Call the Perl sub to process the callback */
4358a253 1467 call_sv(callback, G_DISCARD);
d1b91892
AD
1468 }
1469
1470
1471 void
1472 register_fatal(fn)
1473 SV * fn
1474 CODE:
1475 /* Remember the Perl sub */
1476 if (callback == (SV*)NULL)
4358a253 1477 callback = newSVsv(fn);
d1b91892 1478 else
4358a253 1479 SvSetSV(callback, fn);
d1b91892
AD
1480
1481 /* register the callback with the external library */
4358a253 1482 register_fatal(cb1);
d1b91892
AD
1483
1484where the Perl equivalent of C<register_fatal> and the callback it
1485registers, C<pcb1>, might look like this
1486
1487 # Register the sub pcb1
4358a253 1488 register_fatal(\&pcb1);
d1b91892 1489
84f709e7
JH
1490 sub pcb1
1491 {
4358a253 1492 die "I'm dying...\n";
d1b91892
AD
1493 }
1494
1495The mapping between the C callback and the Perl equivalent is stored in
1496the global variable C<callback>.
1497
5f05dabc 1498This will be adequate if you ever need to have only one callback
d1b91892
AD
1499registered at any time. An example could be an error handler like the
1500code sketched out above. Remember though, repeated calls to
1501C<register_fatal> will replace the previously registered callback
1502function with the new one.
1503
1504Say for example you want to interface to a library which allows asynchronous
1505file i/o. In this case you may be able to register a callback whenever
1506a read operation has completed. To be of any use we want to be able to
1507call separate Perl subroutines for each file that is opened. As it
1508stands, the error handler example above would not be adequate as it
1509allows only a single callback to be defined at any time. What we
1510require is a means of storing the mapping between the opened file and
1511the Perl subroutine we want to be called for that file.
1512
1513Say the i/o library has a function C<asynch_read> which associates a C
19799a22 1514function C<ProcessRead> with a file handle C<fh>--this assumes that it
d1b91892
AD
1515has also provided some routine to open the file and so obtain the file
1516handle.
1517
1518 asynch_read(fh, ProcessRead)
1519
1520This may expect the C I<ProcessRead> function of this form
1521
1522 void
1523 ProcessRead(fh, buffer)
4358a253
SS
1524 int fh;
1525 char * buffer;
d1b91892 1526 {
54310121 1527 ...
d1b91892
AD
1528 }
1529
1530To provide a Perl interface to this library we need to be able to map
1531between the C<fh> parameter and the Perl subroutine we want called. A
1532hash is a convenient mechanism for storing this mapping. The code
1533below shows a possible implementation
1534
4358a253 1535 static HV * Mapping = (HV*)NULL;
a0d0e21e 1536
d1b91892
AD
1537 void
1538 asynch_read(fh, callback)
1539 int fh
1540 SV * callback
1541 CODE:
1542 /* If the hash doesn't already exist, create it */
1543 if (Mapping == (HV*)NULL)
4358a253 1544 Mapping = newHV();
d1b91892
AD
1545
1546 /* Save the fh -> callback mapping */
4358a253 1547 hv_store(Mapping, (char*)&fh, sizeof(fh), newSVsv(callback), 0);
d1b91892
AD
1548
1549 /* Register with the C Library */
4358a253 1550 asynch_read(fh, asynch_read_if);
d1b91892
AD
1551
1552and C<asynch_read_if> could look like this
1553
1554 static void
1555 asynch_read_if(fh, buffer)
4358a253
SS
1556 int fh;
1557 char * buffer;
d1b91892 1558 {
4358a253
SS
1559 dSP;
1560 SV ** sv;
d1b91892
AD
1561
1562 /* Get the callback associated with fh */
4358a253 1563 sv = hv_fetch(Mapping, (char*)&fh , sizeof(fh), FALSE);
d1b91892 1564 if (sv == (SV**)NULL)
4358a253 1565 croak("Internal error...\n");
d1b91892 1566
4358a253
SS
1567 PUSHMARK(SP);
1568 XPUSHs(sv_2mortal(newSViv(fh)));
1569 XPUSHs(sv_2mortal(newSVpv(buffer, 0)));
1570 PUTBACK;
d1b91892
AD
1571
1572 /* Call the Perl sub */
4358a253 1573 call_sv(*sv, G_DISCARD);
d1b91892
AD
1574 }
1575
1576For completeness, here is C<asynch_close>. This shows how to remove
1577the entry from the hash C<Mapping>.
1578
1579 void
1580 asynch_close(fh)
1581 int fh
1582 CODE:
1583 /* Remove the entry from the hash */
4358a253 1584 (void) hv_delete(Mapping, (char*)&fh, sizeof(fh), G_DISCARD);
a0d0e21e 1585
d1b91892 1586 /* Now call the real asynch_close */
4358a253 1587 asynch_close(fh);
a0d0e21e 1588
d1b91892
AD
1589So the Perl interface would look like this
1590
84f709e7
JH
1591 sub callback1
1592 {
4358a253 1593 my($handle, $buffer) = @_;
d1b91892 1594 }
a0d0e21e 1595
d1b91892 1596 # Register the Perl callback
4358a253 1597 asynch_read($fh, \&callback1);
a0d0e21e 1598
4358a253 1599 asynch_close($fh);
d1b91892
AD
1600
1601The mapping between the C callback and Perl is stored in the global
1602hash C<Mapping> this time. Using a hash has the distinct advantage that
1603it allows an unlimited number of callbacks to be registered.
1604
1605What if the interface provided by the C callback doesn't contain a
1606parameter which allows the file handle to Perl subroutine mapping? Say
1607in the asynchronous i/o package, the callback function gets passed only
1608the C<buffer> parameter like this
1609
1610 void
1611 ProcessRead(buffer)
4358a253 1612 char * buffer;
d1b91892
AD
1613 {
1614 ...
1615 }
a0d0e21e 1616
d1b91892
AD
1617Without the file handle there is no straightforward way to map from the
1618C callback to the Perl subroutine.
a0d0e21e 1619
54310121 1620In this case a possible way around this problem is to predefine a
d1b91892
AD
1621series of C functions to act as the interface to Perl, thus
1622
1623 #define MAX_CB 3
1624 #define NULL_HANDLE -1
4358a253 1625 typedef void (*FnMap)();
d1b91892
AD
1626
1627 struct MapStruct {
4358a253
SS
1628 FnMap Function;
1629 SV * PerlSub;
1630 int Handle;
1631 };
d1b91892 1632
4358a253
SS
1633 static void fn1();
1634 static void fn2();
1635 static void fn3();
d1b91892
AD
1636
1637 static struct MapStruct Map [MAX_CB] =
1638 {
1639 { fn1, NULL, NULL_HANDLE },
1640 { fn2, NULL, NULL_HANDLE },
1641 { fn3, NULL, NULL_HANDLE }
4358a253 1642 };
d1b91892
AD
1643
1644 static void
1645 Pcb(index, buffer)
4358a253
SS
1646 int index;
1647 char * buffer;
d1b91892 1648 {
4358a253 1649 dSP;
d1b91892 1650
4358a253
SS
1651 PUSHMARK(SP);
1652 XPUSHs(sv_2mortal(newSVpv(buffer, 0)));
1653 PUTBACK;
d1b91892
AD
1654
1655 /* Call the Perl sub */
4358a253 1656 call_sv(Map[index].PerlSub, G_DISCARD);
d1b91892
AD
1657 }
1658
1659 static void
1660 fn1(buffer)
4358a253 1661 char * buffer;
d1b91892 1662 {
4358a253 1663 Pcb(0, buffer);
d1b91892
AD
1664 }
1665
1666 static void
1667 fn2(buffer)
4358a253 1668 char * buffer;
d1b91892 1669 {
4358a253 1670 Pcb(1, buffer);
d1b91892
AD
1671 }
1672
1673 static void
1674 fn3(buffer)
4358a253 1675 char * buffer;
d1b91892 1676 {
4358a253 1677 Pcb(2, buffer);
d1b91892
AD
1678 }
1679
1680 void
1681 array_asynch_read(fh, callback)
1682 int fh
1683 SV * callback
1684 CODE:
4358a253
SS
1685 int index;
1686 int null_index = MAX_CB;
d1b91892
AD
1687
1688 /* Find the same handle or an empty entry */
4358a253 1689 for (index = 0; index < MAX_CB; ++index)
d1b91892
AD
1690 {
1691 if (Map[index].Handle == fh)
4358a253 1692 break;
d1b91892
AD
1693
1694 if (Map[index].Handle == NULL_HANDLE)
4358a253 1695 null_index = index;
d1b91892
AD
1696 }
1697
1698 if (index == MAX_CB && null_index == MAX_CB)
4358a253 1699 croak ("Too many callback functions registered\n");
d1b91892
AD
1700
1701 if (index == MAX_CB)
4358a253 1702 index = null_index;
d1b91892
AD
1703
1704 /* Save the file handle */
4358a253 1705 Map[index].Handle = fh;
d1b91892
AD
1706
1707 /* Remember the Perl sub */
1708 if (Map[index].PerlSub == (SV*)NULL)
4358a253 1709 Map[index].PerlSub = newSVsv(callback);
d1b91892 1710 else
4358a253 1711 SvSetSV(Map[index].PerlSub, callback);
d1b91892 1712
4358a253 1713 asynch_read(fh, Map[index].Function);
d1b91892
AD
1714
1715 void
1716 array_asynch_close(fh)
1717 int fh
1718 CODE:
4358a253 1719 int index;
d1b91892
AD
1720
1721 /* Find the file handle */
4358a253 1722 for (index = 0; index < MAX_CB; ++ index)
d1b91892 1723 if (Map[index].Handle == fh)
4358a253 1724 break;
d1b91892
AD
1725
1726 if (index == MAX_CB)
4358a253 1727 croak ("could not close fh %d\n", fh);
d1b91892 1728
4358a253
SS
1729 Map[index].Handle = NULL_HANDLE;
1730 SvREFCNT_dec(Map[index].PerlSub);
1731 Map[index].PerlSub = (SV*)NULL;
d1b91892 1732
4358a253 1733 asynch_close(fh);
d1b91892 1734
5f05dabc 1735In this case the functions C<fn1>, C<fn2>, and C<fn3> are used to
d1b91892 1736remember the Perl subroutine to be called. Each of the functions holds
4a6725af 1737a separate hard-wired index which is used in the function C<Pcb> to
d1b91892
AD
1738access the C<Map> array and actually call the Perl subroutine.
1739
1740There are some obvious disadvantages with this technique.
1741
1742Firstly, the code is considerably more complex than with the previous
1743example.
1744
4a6725af 1745Secondly, there is a hard-wired limit (in this case 3) to the number of
d1b91892
AD
1746callbacks that can exist simultaneously. The only way to increase the
1747limit is by modifying the code to add more functions and then
54310121 1748recompiling. None the less, as long as the number of functions is
d1b91892
AD
1749chosen with some care, it is still a workable solution and in some
1750cases is the only one available.
1751
1752To summarize, here are a number of possible methods for you to consider
1753for storing the mapping between C and the Perl callback
1754
1755=over 5
1756
1757=item 1. Ignore the problem - Allow only 1 callback
1758
1759For a lot of situations, like interfacing to an error handler, this may
1760be a perfectly adequate solution.
1761
1762=item 2. Create a sequence of callbacks - hard wired limit
1763
1764If it is impossible to tell from the parameters passed back from the C
1765callback what the context is, then you may need to create a sequence of C
1766callback interface functions, and store pointers to each in an array.
1767
1768=item 3. Use a parameter to map to the Perl callback
1769
1770A hash is an ideal mechanism to store the mapping between C and Perl.
1771
1772=back
a0d0e21e 1773
a0d0e21e
LW
1774
1775=head2 Alternate Stack Manipulation
1776
a0d0e21e 1777
d1b91892
AD
1778Although I have made use of only the C<POP*> macros to access values
1779returned from Perl subroutines, it is also possible to bypass these
8e07c86e 1780macros and read the stack using the C<ST> macro (See L<perlxs> for a
d1b91892
AD
1781full description of the C<ST> macro).
1782
1d45ec27 1783Most of the time the C<POP*> macros should be adequate; the main
d1b91892
AD
1784problem with them is that they force you to process the returned values
1785in sequence. This may not be the most suitable way to process the
1786values in some cases. What we want is to be able to access the stack in
1787a random order. The C<ST> macro as used when coding an XSUB is ideal
1788for this purpose.
1789
1d45ec27
FC
1790The code below is the example given in the section I<Returning a List
1791of Values> recoded to use C<ST> instead of C<POP*>.
d1b91892
AD
1792
1793 static void
1794 call_AddSubtract2(a, b)
4358a253
SS
1795 int a;
1796 int b;
d1b91892 1797 {
4358a253
SS
1798 dSP;
1799 I32 ax;
1800 int count;
d1b91892 1801
4358a253 1802 ENTER;
d1b91892
AD
1803 SAVETMPS;
1804
4358a253 1805 PUSHMARK(SP);
d1b91892
AD
1806 XPUSHs(sv_2mortal(newSViv(a)));
1807 XPUSHs(sv_2mortal(newSViv(b)));
4358a253 1808 PUTBACK;
d1b91892 1809
4929bf7b 1810 count = call_pv("AddSubtract", G_ARRAY);
d1b91892 1811
4358a253
SS
1812 SPAGAIN;
1813 SP -= count;
1814 ax = (SP - PL_stack_base) + 1;
d1b91892
AD
1815
1816 if (count != 2)
4358a253 1817 croak("Big trouble\n");
a0d0e21e 1818
4358a253
SS
1819 printf ("%d + %d = %d\n", a, b, SvIV(ST(0)));
1820 printf ("%d - %d = %d\n", a, b, SvIV(ST(1)));
d1b91892 1821
4358a253
SS
1822 PUTBACK;
1823 FREETMPS;
1824 LEAVE;
d1b91892
AD
1825 }
1826
1827Notes
1828
1829=over 5
1830
1831=item 1.
1832
1833Notice that it was necessary to define the variable C<ax>. This is
1834because the C<ST> macro expects it to exist. If we were in an XSUB it
1835would not be necessary to define C<ax> as it is already defined for
1d45ec27 1836us.
d1b91892
AD
1837
1838=item 2.
1839
1840The code
1841
4358a253
SS
1842 SPAGAIN;
1843 SP -= count;
1844 ax = (SP - PL_stack_base) + 1;
d1b91892
AD
1845
1846sets the stack up so that we can use the C<ST> macro.
1847
1848=item 3.
1849
1850Unlike the original coding of this example, the returned
1851values are not accessed in reverse order. So C<ST(0)> refers to the
54310121 1852first value returned by the Perl subroutine and C<ST(count-1)>
d1b91892
AD
1853refers to the last.
1854
1855=back
a0d0e21e 1856
02f6dca1 1857=head2 Creating and Calling an Anonymous Subroutine in C
8f183262 1858
4929bf7b 1859As we've already shown, C<call_sv> can be used to invoke an
c2611fb3
GS
1860anonymous subroutine. However, our example showed a Perl script
1861invoking an XSUB to perform this operation. Let's see how it can be
8f183262
DM
1862done inside our C code:
1863
8f183262
DM
1864 ...
1865
4929bf7b 1866 SV *cvrv = eval_pv("sub { print 'You will not find me cluttering any namespace!' }", TRUE);
8f183262
DM
1867
1868 ...
1869
4929bf7b 1870 call_sv(cvrv, G_VOID|G_NOARGS);
8f183262 1871
4929bf7b
GS
1872C<eval_pv> is used to compile the anonymous subroutine, which
1873will be the return value as well (read more about C<eval_pv> in
4a4eefd0 1874L<perlapi/eval_pv>). Once this code reference is in hand, it
8f183262
DM
1875can be mixed in with all the previous examples we've shown.
1876
9850bf21
RH
1877=head1 LIGHTWEIGHT CALLBACKS
1878
1879Sometimes you need to invoke the same subroutine repeatedly.
1880This usually happens with a function that acts on a list of
1881values, such as Perl's built-in sort(). You can pass a
1882comparison function to sort(), which will then be invoked
1883for every pair of values that needs to be compared. The first()
1884and reduce() functions from L<List::Util> follow a similar
1885pattern.
1886
1887In this case it is possible to speed up the routine (often
1888quite substantially) by using the lightweight callback API.
1889The idea is that the calling context only needs to be
1890created and destroyed once, and the sub can be called
1891arbitrarily many times in between.
1892
ac036724 1893It is usual to pass parameters using global variables (typically
1894$_ for one parameter, or $a and $b for two parameters) rather
9850bf21
RH
1895than via @_. (It is possible to use the @_ mechanism if you know
1896what you're doing, though there is as yet no supported API for
1897it. It's also inherently slower.)
1898
1899The pattern of macro calls is like this:
1900
82f35e8b 1901 dMULTICALL; /* Declare local variables */
9850bf21 1902 I32 gimme = G_SCALAR; /* context of the call: G_SCALAR,
782a81f5 1903 * G_ARRAY, or G_VOID */
9850bf21 1904
82f35e8b
RH
1905 PUSH_MULTICALL(cv); /* Set up the context for calling cv,
1906 and set local vars appropriately */
9850bf21
RH
1907
1908 /* loop */ {
1909 /* set the value(s) af your parameter variables */
1910 MULTICALL; /* Make the actual call */
1911 } /* end of loop */
1912
1913 POP_MULTICALL; /* Tear down the calling context */
1914
1915For some concrete examples, see the implementation of the
1916first() and reduce() functions of List::Util 1.18. There you
1917will also find a header file that emulates the multicall API
1918on older versions of perl.
1919
a0d0e21e
LW
1920=head1 SEE ALSO
1921
8e07c86e 1922L<perlxs>, L<perlguts>, L<perlembed>
a0d0e21e
LW
1923
1924=head1 AUTHOR
1925
0536e0eb 1926Paul Marquess
a0d0e21e 1927
d1b91892
AD
1928Special thanks to the following people who assisted in the creation of
1929the document.
a0d0e21e 1930
c07a80fd 1931Jeff Okamoto, Tim Bunce, Nick Gianniotis, Steve Kelem, Gurusamy Sarathy
1932and Larry Wall.
a0d0e21e
LW
1933
1934=head1 DATE
1935
137443ea 1936Version 1.3, 14th Apr 1997