diff options
Diffstat (limited to 'contrib/perl5/pod/perlcall.pod')
| -rw-r--r-- | contrib/perl5/pod/perlcall.pod | 1959 |
1 files changed, 1959 insertions, 0 deletions
diff --git a/contrib/perl5/pod/perlcall.pod b/contrib/perl5/pod/perlcall.pod new file mode 100644 index 0000000..c239cfe --- /dev/null +++ b/contrib/perl5/pod/perlcall.pod @@ -0,0 +1,1959 @@ +=head1 NAME + +perlcall - Perl calling conventions from C + +=head1 DESCRIPTION + +The purpose of this document is to show you how to call Perl subroutines +directly from C, i.e., how to write I<callbacks>. + +Apart from discussing the C interface provided by Perl for writing +callbacks the document uses a series of examples to show how the +interface actually works in practice. In addition some techniques for +coding callbacks are covered. + +Examples where callbacks are necessary include + +=over 5 + +=item * An Error Handler + +You have created an XSUB interface to an application's C API. + +A fairly common feature in applications is to allow you to define a C +function that will be called whenever something nasty occurs. What we +would like is to be able to specify a Perl subroutine that will be +called instead. + +=item * An Event Driven Program + +The classic example of where callbacks are used is when writing an +event driven program like for an X windows application. In this case +you register functions to be called whenever specific events occur, +e.g., a mouse button is pressed, the cursor moves into a window or a +menu item is selected. + +=back + +Although the techniques described here are applicable when embedding +Perl in a C program, this is not the primary goal of this document. +There are other details that must be considered and are specific to +embedding Perl. For details on embedding Perl in C refer to +L<perlembed>. + +Before you launch yourself head first into the rest of this document, +it would be a good idea to have read the following two documents - +L<perlxs> and L<perlguts>. + +=head1 THE PERL_CALL FUNCTIONS + +Although this stuff is easier to explain using examples, you first need +be aware of a few important definitions. + +Perl has a number of C functions that allow you to call Perl +subroutines. They are + + I32 perl_call_sv(SV* sv, I32 flags) ; + I32 perl_call_pv(char *subname, I32 flags) ; + I32 perl_call_method(char *methname, I32 flags) ; + I32 perl_call_argv(char *subname, I32 flags, register char **argv) ; + +The key function is I<perl_call_sv>. All the other functions are +fairly simple wrappers which make it easier to call Perl subroutines in +special cases. At the end of the day they will all call I<perl_call_sv> +to invoke the Perl subroutine. + +All the I<perl_call_*> functions have a C<flags> parameter which is +used to pass a bit mask of options to Perl. This bit mask operates +identically for each of the functions. The settings available in the +bit mask are discussed in L<FLAG VALUES>. + +Each of the functions will now be discussed in turn. + +=over 5 + +=item B<perl_call_sv> + +I<perl_call_sv> takes two parameters, the first, C<sv>, is an SV*. +This allows you to specify the Perl subroutine to be called either as a +C string (which has first been converted to an SV) or a reference to a +subroutine. The section, I<Using perl_call_sv>, shows how you can make +use of I<perl_call_sv>. + +=item B<perl_call_pv> + +The function, I<perl_call_pv>, is similar to I<perl_call_sv> except it +expects its first parameter to be a C char* which identifies the Perl +subroutine you want to call, e.g., C<perl_call_pv("fred", 0)>. If the +subroutine you want to call is in another package, just include the +package name in the string, e.g., C<"pkg::fred">. + +=item B<perl_call_method> + +The function I<perl_call_method> is used to call a method from a Perl +class. The parameter C<methname> corresponds to the name of the method +to be called. Note that the class that the method belongs to is passed +on the Perl stack rather than in the parameter list. This class can be +either the name of the class (for a static method) or a reference to an +object (for a virtual method). See L<perlobj> for more information on +static and virtual methods and L<Using perl_call_method> for an example +of using I<perl_call_method>. + +=item B<perl_call_argv> + +I<perl_call_argv> calls the Perl subroutine specified by the C string +stored in the C<subname> parameter. It also takes the usual C<flags> +parameter. The final parameter, C<argv>, consists of a NULL terminated +list of C strings to be passed as parameters to the Perl subroutine. +See I<Using perl_call_argv>. + +=back + +All the functions return an integer. This is a count of the number of +items returned by the Perl subroutine. The actual items returned by the +subroutine are stored on the Perl stack. + +As a general rule you should I<always> check the return value from +these functions. Even if you are expecting only a particular number of +values to be returned from the Perl subroutine, there is nothing to +stop someone from doing something unexpected - don't say you haven't +been warned. + +=head1 FLAG VALUES + +The C<flags> parameter in all the I<perl_call_*> functions is a bit mask +which can consist of any combination of the symbols defined below, +OR'ed together. + + +=head2 G_VOID + +Calls the Perl subroutine in a void context. + +This flag has 2 effects: + +=over 5 + +=item 1. + +It indicates to the subroutine being called that it is executing in +a void context (if it executes I<wantarray> the result will be the +undefined value). + +=item 2. + +It ensures that nothing is actually returned from the subroutine. + +=back + +The value returned by the I<perl_call_*> function indicates how many +items have been returned by the Perl subroutine - in this case it will +be 0. + + +=head2 G_SCALAR + +Calls the Perl subroutine in a scalar context. This is the default +context flag setting for all the I<perl_call_*> functions. + +This flag has 2 effects: + +=over 5 + +=item 1. + +It indicates to the subroutine being called that it is executing in a +scalar context (if it executes I<wantarray> the result will be false). + +=item 2. + +It ensures that only a scalar is actually returned from the subroutine. +The subroutine can, of course, ignore the I<wantarray> and return a +list anyway. If so, then only the last element of the list will be +returned. + +=back + +The value returned by the I<perl_call_*> function indicates how many +items have been returned by the Perl subroutine - in this case it will +be either 0 or 1. + +If 0, then you have specified the G_DISCARD flag. + +If 1, then the item actually returned by the Perl subroutine will be +stored on the Perl stack - the section I<Returning a Scalar> shows how +to access this value on the stack. Remember that regardless of how +many items the Perl subroutine returns, only the last one will be +accessible from the stack - think of the case where only one value is +returned as being a list with only one element. Any other items that +were returned will not exist by the time control returns from the +I<perl_call_*> function. The section I<Returning a list in a scalar +context> shows an example of this behavior. + + +=head2 G_ARRAY + +Calls the Perl subroutine in a list context. + +As with G_SCALAR, this flag has 2 effects: + +=over 5 + +=item 1. + +It indicates to the subroutine being called that it is executing in an +array context (if it executes I<wantarray> the result will be true). + + +=item 2. + +It ensures that all items returned from the subroutine will be +accessible when control returns from the I<perl_call_*> function. + +=back + +The value returned by the I<perl_call_*> function indicates how many +items have been returned by the Perl subroutine. + +If 0, then you have specified the G_DISCARD flag. + +If not 0, then it will be a count of the number of items returned by +the subroutine. These items will be stored on the Perl stack. The +section I<Returning a list of values> gives an example of using the +G_ARRAY flag and the mechanics of accessing the returned items from the +Perl stack. + +=head2 G_DISCARD + +By default, the I<perl_call_*> functions place the items returned from +by the Perl subroutine on the stack. If you are not interested in +these items, then setting this flag will make Perl get rid of them +automatically for you. Note that it is still possible to indicate a +context to the Perl subroutine by using either G_SCALAR or G_ARRAY. + +If you do not set this flag then it is I<very> important that you make +sure that any temporaries (i.e., parameters passed to the Perl +subroutine and values returned from the subroutine) are disposed of +yourself. The section I<Returning a Scalar> gives details of how to +dispose of these temporaries explicitly and the section I<Using Perl to +dispose of temporaries> discusses the specific circumstances where you +can ignore the problem and let Perl deal with it for you. + +=head2 G_NOARGS + +Whenever a Perl subroutine is called using one of the I<perl_call_*> +functions, it is assumed by default that parameters are to be passed to +the subroutine. If you are not passing any parameters to the Perl +subroutine, you can save a bit of time by setting this flag. It has +the effect of not creating the C<@_> array for the Perl subroutine. + +Although the functionality provided by this flag may seem +straightforward, it should be used only if there is a good reason to do +so. The reason for being cautious is that even if you have specified +the G_NOARGS flag, it is still possible for the Perl subroutine that +has been called to think that you have passed it parameters. + +In fact, what can happen is that the Perl subroutine you have called +can access the C<@_> array from a previous Perl subroutine. This will +occur when the code that is executing the I<perl_call_*> function has +itself been called from another Perl subroutine. The code below +illustrates this + + sub fred + { print "@_\n" } + + sub joe + { &fred } + + &joe(1,2,3) ; + +This will print + + 1 2 3 + +What has happened is that C<fred> accesses the C<@_> array which +belongs to C<joe>. + + +=head2 G_EVAL + +It is possible for the Perl subroutine you are calling to terminate +abnormally, e.g., by calling I<die> explicitly or by not actually +existing. By default, when either of these events occurs, the +process will terminate immediately. If you want to trap this +type of event, specify the G_EVAL flag. It will put an I<eval { }> +around the subroutine call. + +Whenever control returns from the I<perl_call_*> function you need to +check the C<$@> variable as you would in a normal Perl script. + +The value returned from the I<perl_call_*> function is dependent on +what other flags have been specified and whether an error has +occurred. Here are all the different cases that can occur: + +=over 5 + +=item * + +If the I<perl_call_*> function returns normally, then the value +returned is as specified in the previous sections. + +=item * + +If G_DISCARD is specified, the return value will always be 0. + +=item * + +If G_ARRAY is specified I<and> an error has occurred, the return value +will always be 0. + +=item * + +If G_SCALAR is specified I<and> an error has occurred, the return value +will be 1 and the value on the top of the stack will be I<undef>. This +means that if you have already detected the error by checking C<$@> and +you want the program to continue, you must remember to pop the I<undef> +from the stack. + +=back + +See I<Using G_EVAL> for details on using G_EVAL. + +=head2 G_KEEPERR + +You may have noticed that using the G_EVAL flag described above will +B<always> clear the C<$@> variable and set it to a string describing +the error iff there was an error in the called code. This unqualified +resetting of C<$@> can be problematic in the reliable identification of +errors using the C<eval {}> mechanism, because the possibility exists +that perl will call other code (end of block processing code, for +example) between the time the error causes C<$@> to be set within +C<eval {}>, and the subsequent statement which checks for the value of +C<$@> gets executed in the user's script. + +This scenario will mostly be applicable to code that is meant to be +called from within destructors, asynchronous callbacks, signal +handlers, C<__DIE__> or C<__WARN__> hooks, and C<tie> functions. In +such situations, you will not want to clear C<$@> at all, but simply to +append any new errors to any existing value of C<$@>. + +The G_KEEPERR flag is meant to be used in conjunction with G_EVAL in +I<perl_call_*> functions that are used to implement such code. This flag +has no effect when G_EVAL is not used. + +When G_KEEPERR is used, any errors in the called code will be prefixed +with the string "\t(in cleanup)", and appended to the current value +of C<$@>. + +The G_KEEPERR flag was introduced in Perl version 5.002. + +See I<Using G_KEEPERR> for an example of a situation that warrants the +use of this flag. + +=head2 Determining the Context + +As mentioned above, you can determine the context of the currently +executing subroutine in Perl with I<wantarray>. The equivalent test +can be made in C by using the C<GIMME_V> macro, which returns +C<G_ARRAY> if you have been called in an array context, C<G_SCALAR> if +in a scalar context, or C<G_VOID> if in a void context (i.e. the +return value will not be used). An older version of this macro is +called C<GIMME>; in a void context it returns C<G_SCALAR> instead of +C<G_VOID>. An example of using the C<GIMME_V> macro is shown in +section I<Using GIMME_V>. + +=head1 KNOWN PROBLEMS + +This section outlines all known problems that exist in the +I<perl_call_*> functions. + +=over 5 + +=item 1. + +If you are intending to make use of both the G_EVAL and G_SCALAR flags +in your code, use a version of Perl greater than 5.000. There is a bug +in version 5.000 of Perl which means that the combination of these two +flags will not work as described in the section I<FLAG VALUES>. + +Specifically, if the two flags are used when calling a subroutine and +that subroutine does not call I<die>, the value returned by +I<perl_call_*> will be wrong. + + +=item 2. + +In Perl 5.000 and 5.001 there is a problem with using I<perl_call_*> if +the Perl sub you are calling attempts to trap a I<die>. + +The symptom of this problem is that the called Perl sub will continue +to completion, but whenever it attempts to pass control back to the +XSUB, the program will immediately terminate. + +For example, say you want to call this Perl sub + + sub fred + { + eval { die "Fatal Error" ; } + print "Trapped error: $@\n" + if $@ ; + } + +via this XSUB + + void + Call_fred() + CODE: + PUSHMARK(SP) ; + perl_call_pv("fred", G_DISCARD|G_NOARGS) ; + fprintf(stderr, "back in Call_fred\n") ; + +When C<Call_fred> is executed it will print + + Trapped error: Fatal Error + +As control never returns to C<Call_fred>, the C<"back in Call_fred"> +string will not get printed. + +To work around this problem, you can either upgrade to Perl 5.002 or +higher, or use the G_EVAL flag with I<perl_call_*> as shown below + + void + Call_fred() + CODE: + PUSHMARK(SP) ; + perl_call_pv("fred", G_EVAL|G_DISCARD|G_NOARGS) ; + fprintf(stderr, "back in Call_fred\n") ; + +=back + + + +=head1 EXAMPLES + +Enough of the definition talk, let's have a few examples. + +Perl provides many macros to assist in accessing the Perl stack. +Wherever possible, these macros should always be used when interfacing +to Perl internals. We hope this should make the code less vulnerable +to any changes made to Perl in the future. + +Another point worth noting is that in the first series of examples I +have made use of only the I<perl_call_pv> function. This has been done +to keep the code simpler and ease you into the topic. Wherever +possible, if the choice is between using I<perl_call_pv> and +I<perl_call_sv>, you should always try to use I<perl_call_sv>. See +I<Using perl_call_sv> for details. + +=head2 No Parameters, Nothing returned + +This first trivial example will call a Perl subroutine, I<PrintUID>, to +print out the UID of the process. + + sub PrintUID + { + print "UID is $<\n" ; + } + +and here is a C function to call it + + static void + call_PrintUID() + { + dSP ; + + PUSHMARK(SP) ; + perl_call_pv("PrintUID", G_DISCARD|G_NOARGS) ; + } + +Simple, eh. + +A few points to note about this example. + +=over 5 + +=item 1. + +Ignore C<dSP> and C<PUSHMARK(SP)> for now. They will be discussed in +the next example. + +=item 2. + +We aren't passing any parameters to I<PrintUID> so G_NOARGS can be +specified. + +=item 3. + +We aren't interested in anything returned from I<PrintUID>, so +G_DISCARD is specified. Even if I<PrintUID> was changed to +return some value(s), having specified G_DISCARD will mean that they +will be wiped by the time control returns from I<perl_call_pv>. + +=item 4. + +As I<perl_call_pv> is being used, the Perl subroutine is specified as a +C string. In this case the subroutine name has been 'hard-wired' into the +code. + +=item 5. + +Because we specified G_DISCARD, it is not necessary to check the value +returned from I<perl_call_pv>. It will always be 0. + +=back + +=head2 Passing Parameters + +Now let's make a slightly more complex example. This time we want to +call a Perl subroutine, C<LeftString>, which will take 2 parameters - a +string (C<$s>) and an integer (C<$n>). The subroutine will simply +print the first C<$n> characters of the string. + +So the Perl subroutine would look like this + + sub LeftString + { + my($s, $n) = @_ ; + print substr($s, 0, $n), "\n" ; + } + +The C function required to call I<LeftString> would look like this. + + static void + call_LeftString(a, b) + char * a ; + int b ; + { + dSP ; + + ENTER ; + SAVETMPS ; + + PUSHMARK(SP) ; + XPUSHs(sv_2mortal(newSVpv(a, 0))); + XPUSHs(sv_2mortal(newSViv(b))); + PUTBACK ; + + perl_call_pv("LeftString", G_DISCARD); + + FREETMPS ; + LEAVE ; + } + +Here are a few notes on the C function I<call_LeftString>. + +=over 5 + +=item 1. + +Parameters are passed to the Perl subroutine using the Perl stack. +This is the purpose of the code beginning with the line C<dSP> and +ending with the line C<PUTBACK>. The C<dSP> declares a local copy +of the stack pointer. This local copy should B<always> be accessed +as C<SP>. + +=item 2. + +If you are going to put something onto the Perl stack, you need to know +where to put it. This is the purpose of the macro C<dSP> - it declares +and initializes a I<local> copy of the Perl stack pointer. + +All the other macros which will be used in this example require you to +have used this macro. + +The exception to this rule is if you are calling a Perl subroutine +directly from an XSUB function. In this case it is not necessary to +use the C<dSP> macro explicitly - it will be declared for you +automatically. + +=item 3. + +Any parameters to be pushed onto the stack should be bracketed by the +C<PUSHMARK> and C<PUTBACK> macros. The purpose of these two macros, in +this context, is to count the number of parameters you are +pushing automatically. Then whenever Perl is creating the C<@_> array for the +subroutine, it knows how big to make it. + +The C<PUSHMARK> macro tells Perl to make a mental note of the current +stack pointer. Even if you aren't passing any parameters (like the +example shown in the section I<No Parameters, Nothing returned>) you +must still call the C<PUSHMARK> macro before you can call any of the +I<perl_call_*> functions - Perl still needs to know that there are no +parameters. + +The C<PUTBACK> macro sets the global copy of the stack pointer to be +the same as our local copy. If we didn't do this I<perl_call_pv> +wouldn't know where the two parameters we pushed were - remember that +up to now all the stack pointer manipulation we have done is with our +local copy, I<not> the global copy. + +=item 4. + +The only flag specified this time is G_DISCARD. Because we are passing 2 +parameters to the Perl subroutine this time, we have not specified +G_NOARGS. + +=item 5. + +Next, we come to XPUSHs. This is where the parameters actually get +pushed onto the stack. In this case we are pushing a string and an +integer. + +See L<perlguts/"XSUBs and the Argument Stack"> for details +on how the XPUSH macros work. + +=item 6. + +Because we created temporary values (by means of sv_2mortal() calls) +we will have to tidy up the Perl stack and dispose of mortal SVs. + +This is the purpose of + + ENTER ; + SAVETMPS ; + +at the start of the function, and + + FREETMPS ; + LEAVE ; + +at the end. The C<ENTER>/C<SAVETMPS> pair creates a boundary for any +temporaries we create. This means that the temporaries we get rid of +will be limited to those which were created after these calls. + +The C<FREETMPS>/C<LEAVE> pair will get rid of any values returned by +the Perl subroutine (see next example), plus it will also dump the +mortal SVs we have created. Having C<ENTER>/C<SAVETMPS> at the +beginning of the code makes sure that no other mortals are destroyed. + +Think of these macros as working a bit like using C<{> and C<}> in Perl +to limit the scope of local variables. + +See the section I<Using Perl to dispose of temporaries> for details of +an alternative to using these macros. + +=item 7. + +Finally, I<LeftString> can now be called via the I<perl_call_pv> +function. + +=back + +=head2 Returning a Scalar + +Now for an example of dealing with the items returned from a Perl +subroutine. + +Here is a Perl subroutine, I<Adder>, that takes 2 integer parameters +and simply returns their sum. + + sub Adder + { + my($a, $b) = @_ ; + $a + $b ; + } + +Because we are now concerned with the return value from I<Adder>, the C +function required to call it is now a bit more complex. + + static void + call_Adder(a, b) + int a ; + int b ; + { + dSP ; + int count ; + + ENTER ; + SAVETMPS; + + PUSHMARK(SP) ; + XPUSHs(sv_2mortal(newSViv(a))); + XPUSHs(sv_2mortal(newSViv(b))); + PUTBACK ; + + count = perl_call_pv("Adder", G_SCALAR); + + SPAGAIN ; + + if (count != 1) + croak("Big trouble\n") ; + + printf ("The sum of %d and %d is %d\n", a, b, POPi) ; + + PUTBACK ; + FREETMPS ; + LEAVE ; + } + +Points to note this time are + +=over 5 + +=item 1. + +The only flag specified this time was G_SCALAR. That means the C<@_> +array will be created and that the value returned by I<Adder> will +still exist after the call to I<perl_call_pv>. + +=item 2. + +The purpose of the macro C<SPAGAIN> is to refresh the local copy of the +stack pointer. This is necessary because it is possible that the memory +allocated to the Perl stack has been reallocated whilst in the +I<perl_call_pv> call. + +If you are making use of the Perl stack pointer in your code you must +always refresh the local copy using SPAGAIN whenever you make use +of the I<perl_call_*> functions or any other Perl internal function. + +=item 3. + +Although only a single value was expected to be returned from I<Adder>, +it is still good practice to check the return code from I<perl_call_pv> +anyway. + +Expecting a single value is not quite the same as knowing that there +will be one. If someone modified I<Adder> to return a list and we +didn't check for that possibility and take appropriate action the Perl +stack would end up in an inconsistent state. That is something you +I<really> don't want to happen ever. + +=item 4. + +The C<POPi> macro is used here to pop the return value from the stack. +In this case we wanted an integer, so C<POPi> was used. + + +Here is the complete list of POP macros available, along with the types +they return. + + POPs SV + POPp pointer + POPn double + POPi integer + POPl long + +=item 5. + +The final C<PUTBACK> is used to leave the Perl stack in a consistent +state before exiting the function. This is necessary because when we +popped the return value from the stack with C<POPi> it updated only our +local copy of the stack pointer. Remember, C<PUTBACK> sets the global +stack pointer to be the same as our local copy. + +=back + + +=head2 Returning a list of values + +Now, let's extend the previous example to return both the sum of the +parameters and the difference. + +Here is the Perl subroutine + + sub AddSubtract + { + my($a, $b) = @_ ; + ($a+$b, $a-$b) ; + } + +and this is the C function + + static void + call_AddSubtract(a, b) + int a ; + int b ; + { + dSP ; + int count ; + + ENTER ; + SAVETMPS; + + PUSHMARK(SP) ; + XPUSHs(sv_2mortal(newSViv(a))); + XPUSHs(sv_2mortal(newSViv(b))); + PUTBACK ; + + count = perl_call_pv("AddSubtract", G_ARRAY); + + SPAGAIN ; + + if (count != 2) + croak("Big trouble\n") ; + + printf ("%d - %d = %d\n", a, b, POPi) ; + printf ("%d + %d = %d\n", a, b, POPi) ; + + PUTBACK ; + FREETMPS ; + LEAVE ; + } + +If I<call_AddSubtract> is called like this + + call_AddSubtract(7, 4) ; + +then here is the output + + 7 - 4 = 3 + 7 + 4 = 11 + +Notes + +=over 5 + +=item 1. + +We wanted array context, so G_ARRAY was used. + +=item 2. + +Not surprisingly C<POPi> is used twice this time because we were +retrieving 2 values from the stack. The important thing to note is that +when using the C<POP*> macros they come off the stack in I<reverse> +order. + +=back + +=head2 Returning a list in a scalar context + +Say the Perl subroutine in the previous section was called in a scalar +context, like this + + static void + call_AddSubScalar(a, b) + int a ; + int b ; + { + dSP ; + int count ; + int i ; + + ENTER ; + SAVETMPS; + + PUSHMARK(SP) ; + XPUSHs(sv_2mortal(newSViv(a))); + XPUSHs(sv_2mortal(newSViv(b))); + PUTBACK ; + + count = perl_call_pv("AddSubtract", G_SCALAR); + + SPAGAIN ; + + printf ("Items Returned = %d\n", count) ; + + for (i = 1 ; i <= count ; ++i) + printf ("Value %d = %d\n", i, POPi) ; + + PUTBACK ; + FREETMPS ; + LEAVE ; + } + +The other modification made is that I<call_AddSubScalar> will print the +number of items returned from the Perl subroutine and their value (for +simplicity it assumes that they are integer). So if +I<call_AddSubScalar> is called + + call_AddSubScalar(7, 4) ; + +then the output will be + + Items Returned = 1 + Value 1 = 3 + +In this case the main point to note is that only the last item in the +list is returned from the subroutine, I<AddSubtract> actually made it back to +I<call_AddSubScalar>. + + +=head2 Returning Data from Perl via the parameter list + +It is also possible to return values directly via the parameter list - +whether it is actually desirable to do it is another matter entirely. + +The Perl subroutine, I<Inc>, below takes 2 parameters and increments +each directly. + + sub Inc + { + ++ $_[0] ; + ++ $_[1] ; + } + +and here is a C function to call it. + + static void + call_Inc(a, b) + int a ; + int b ; + { + dSP ; + int count ; + SV * sva ; + SV * svb ; + + ENTER ; + SAVETMPS; + + sva = sv_2mortal(newSViv(a)) ; + svb = sv_2mortal(newSViv(b)) ; + + PUSHMARK(SP) ; + XPUSHs(sva); + XPUSHs(svb); + PUTBACK ; + + count = perl_call_pv("Inc", G_DISCARD); + + if (count != 0) + croak ("call_Inc: expected 0 values from 'Inc', got %d\n", + count) ; + + printf ("%d + 1 = %d\n", a, SvIV(sva)) ; + printf ("%d + 1 = %d\n", b, SvIV(svb)) ; + + FREETMPS ; + LEAVE ; + } + +To be able to access the two parameters that were pushed onto the stack +after they return from I<perl_call_pv> it is necessary to make a note +of their addresses - thus the two variables C<sva> and C<svb>. + +The reason this is necessary is that the area of the Perl stack which +held them will very likely have been overwritten by something else by +the time control returns from I<perl_call_pv>. + + + + +=head2 Using G_EVAL + +Now an example using G_EVAL. Below is a Perl subroutine which computes +the difference of its 2 parameters. If this would result in a negative +result, the subroutine calls I<die>. + + sub Subtract + { + my ($a, $b) = @_ ; + + die "death can be fatal\n" if $a < $b ; + + $a - $b ; + } + +and some C to call it + + static void + call_Subtract(a, b) + int a ; + int b ; + { + dSP ; + int count ; + + ENTER ; + SAVETMPS; + + PUSHMARK(SP) ; + XPUSHs(sv_2mortal(newSViv(a))); + XPUSHs(sv_2mortal(newSViv(b))); + PUTBACK ; + + count = perl_call_pv("Subtract", G_EVAL|G_SCALAR); + + SPAGAIN ; + + /* Check the eval first */ + if (SvTRUE(ERRSV)) + { + printf ("Uh oh - %s\n", SvPV(ERRSV, PL_na)) ; + POPs ; + } + else + { + if (count != 1) + croak("call_Subtract: wanted 1 value from 'Subtract', got %d\n", + count) ; + + printf ("%d - %d = %d\n", a, b, POPi) ; + } + + PUTBACK ; + FREETMPS ; + LEAVE ; + } + +If I<call_Subtract> is called thus + + call_Subtract(4, 5) + +the following will be printed + + Uh oh - death can be fatal + +Notes + +=over 5 + +=item 1. + +We want to be able to catch the I<die> so we have used the G_EVAL +flag. Not specifying this flag would mean that the program would +terminate immediately at the I<die> statement in the subroutine +I<Subtract>. + +=item 2. + +The code + + if (SvTRUE(ERRSV)) + { + printf ("Uh oh - %s\n", SvPV(ERRSV, PL_na)) ; + POPs ; + } + +is the direct equivalent of this bit of Perl + + print "Uh oh - $@\n" if $@ ; + +C<PL_errgv> is a perl global of type C<GV *> that points to the +symbol table entry containing the error. C<ERRSV> therefore +refers to the C equivalent of C<$@>. + +=item 3. + +Note that the stack is popped using C<POPs> in the block where +C<SvTRUE(ERRSV)> is true. This is necessary because whenever a +I<perl_call_*> function invoked with G_EVAL|G_SCALAR returns an error, +the top of the stack holds the value I<undef>. Because we want the +program to continue after detecting this error, it is essential that +the stack is tidied up by removing the I<undef>. + +=back + + +=head2 Using G_KEEPERR + +Consider this rather facetious example, where we have used an XS +version of the call_Subtract example above inside a destructor: + + package Foo; + sub new { bless {}, $_[0] } + sub Subtract { + my($a,$b) = @_; + die "death can be fatal" if $a < $b ; + $a - $b; + } + sub DESTROY { call_Subtract(5, 4); } + sub foo { die "foo dies"; } + + package main; + eval { Foo->new->foo }; + print "Saw: $@" if $@; # should be, but isn't + +This example will fail to recognize that an error occurred inside the +C<eval {}>. Here's why: the call_Subtract code got executed while perl +was cleaning up temporaries when exiting the eval block, and because +call_Subtract is implemented with I<perl_call_pv> using the G_EVAL +flag, it promptly reset C<$@>. This results in the failure of the +outermost test for C<$@>, and thereby the failure of the error trap. + +Appending the G_KEEPERR flag, so that the I<perl_call_pv> call in +call_Subtract reads: + + count = perl_call_pv("Subtract", G_EVAL|G_SCALAR|G_KEEPERR); + +will preserve the error and restore reliable error handling. + +=head2 Using perl_call_sv + +In all the previous examples I have 'hard-wired' the name of the Perl +subroutine to be called from C. Most of the time though, it is more +convenient to be able to specify the name of the Perl subroutine from +within the Perl script. + +Consider the Perl code below + + sub fred + { + print "Hello there\n" ; + } + + CallSubPV("fred") ; + +Here is a snippet of XSUB which defines I<CallSubPV>. + + void + CallSubPV(name) + char * name + CODE: + PUSHMARK(SP) ; + perl_call_pv(name, G_DISCARD|G_NOARGS) ; + +That is fine as far as it goes. The thing is, the Perl subroutine +can be specified as only a string. For Perl 4 this was adequate, +but Perl 5 allows references to subroutines and anonymous subroutines. +This is where I<perl_call_sv> is useful. + +The code below for I<CallSubSV> is identical to I<CallSubPV> except +that the C<name> parameter is now defined as an SV* and we use +I<perl_call_sv> instead of I<perl_call_pv>. + + void + CallSubSV(name) + SV * name + CODE: + PUSHMARK(SP) ; + perl_call_sv(name, G_DISCARD|G_NOARGS) ; + +Because we are using an SV to call I<fred> the following can all be used + + CallSubSV("fred") ; + CallSubSV(\&fred) ; + $ref = \&fred ; + CallSubSV($ref) ; + CallSubSV( sub { print "Hello there\n" } ) ; + +As you can see, I<perl_call_sv> gives you much greater flexibility in +how you can specify the Perl subroutine. + +You should note that if it is necessary to store the SV (C<name> in the +example above) which corresponds to the Perl subroutine so that it can +be used later in the program, it not enough just to store a copy of the +pointer to the SV. Say the code above had been like this + + static SV * rememberSub ; + + void + SaveSub1(name) + SV * name + CODE: + rememberSub = name ; + + void + CallSavedSub1() + CODE: + PUSHMARK(SP) ; + perl_call_sv(rememberSub, G_DISCARD|G_NOARGS) ; + +The reason this is wrong is that by the time you come to use the +pointer C<rememberSub> in C<CallSavedSub1>, it may or may not still refer +to the Perl subroutine that was recorded in C<SaveSub1>. This is +particularly true for these cases + + SaveSub1(\&fred) ; + CallSavedSub1() ; + + SaveSub1( sub { print "Hello there\n" } ) ; + CallSavedSub1() ; + +By the time each of the C<SaveSub1> statements above have been executed, +the SV*s which corresponded to the parameters will no longer exist. +Expect an error message from Perl of the form + + Can't use an undefined value as a subroutine reference at ... + +for each of the C<CallSavedSub1> lines. + +Similarly, with this code + + $ref = \&fred ; + SaveSub1($ref) ; + $ref = 47 ; + CallSavedSub1() ; + +you can expect one of these messages (which you actually get is dependent on +the version of Perl you are using) + + Not a CODE reference at ... + Undefined subroutine &main::47 called ... + +The variable C<$ref> may have referred to the subroutine C<fred> +whenever the call to C<SaveSub1> was made but by the time +C<CallSavedSub1> gets called it now holds the number C<47>. Because we +saved only a pointer to the original SV in C<SaveSub1>, any changes to +C<$ref> will be tracked by the pointer C<rememberSub>. This means that +whenever C<CallSavedSub1> gets called, it will attempt to execute the +code which is referenced by the SV* C<rememberSub>. In this case +though, it now refers to the integer C<47>, so expect Perl to complain +loudly. + +A similar but more subtle problem is illustrated with this code + + $ref = \&fred ; + SaveSub1($ref) ; + $ref = \&joe ; + CallSavedSub1() ; + +This time whenever C<CallSavedSub1> get called it will execute the Perl +subroutine C<joe> (assuming it exists) rather than C<fred> as was +originally requested in the call to C<SaveSub1>. + +To get around these problems it is necessary to take a full copy of the +SV. The code below shows C<SaveSub2> modified to do that + + static SV * keepSub = (SV*)NULL ; + + void + SaveSub2(name) + SV * name + CODE: + /* Take a copy of the callback */ + if (keepSub == (SV*)NULL) + /* First time, so create a new SV */ + keepSub = newSVsv(name) ; + else + /* Been here before, so overwrite */ + SvSetSV(keepSub, name) ; + + void + CallSavedSub2() + CODE: + PUSHMARK(SP) ; + perl_call_sv(keepSub, G_DISCARD|G_NOARGS) ; + +To avoid creating a new SV every time C<SaveSub2> is called, +the function first checks to see if it has been called before. If not, +then space for a new SV is allocated and the reference to the Perl +subroutine, C<name> is copied to the variable C<keepSub> in one +operation using C<newSVsv>. Thereafter, whenever C<SaveSub2> is called +the existing SV, C<keepSub>, is overwritten with the new value using +C<SvSetSV>. + +=head2 Using perl_call_argv + +Here is a Perl subroutine which prints whatever parameters are passed +to it. + + sub PrintList + { + my(@list) = @_ ; + + foreach (@list) { print "$_\n" } + } + +and here is an example of I<perl_call_argv> which will call +I<PrintList>. + + static char * words[] = {"alpha", "beta", "gamma", "delta", NULL} ; + + static void + call_PrintList() + { + dSP ; + + perl_call_argv("PrintList", G_DISCARD, words) ; + } + +Note that it is not necessary to call C<PUSHMARK> in this instance. +This is because I<perl_call_argv> will do it for you. + +=head2 Using perl_call_method + +Consider the following Perl code + + { + package Mine ; + + sub new + { + my($type) = shift ; + bless [@_] + } + + sub Display + { + my ($self, $index) = @_ ; + print "$index: $$self[$index]\n" ; + } + + sub PrintID + { + my($class) = @_ ; + print "This is Class $class version 1.0\n" ; + } + } + +It implements just a very simple class to manage an array. Apart from +the constructor, C<new>, it declares methods, one static and one +virtual. The static method, C<PrintID>, prints out simply the class +name and a version number. The virtual method, C<Display>, prints out a +single element of the array. Here is an all Perl example of using it. + + $a = new Mine ('red', 'green', 'blue') ; + $a->Display(1) ; + PrintID Mine; + +will print + + 1: green + This is Class Mine version 1.0 + +Calling a Perl method from C is fairly straightforward. The following +things are required + +=over 5 + +=item * + +a reference to the object for a virtual method or the name of the class +for a static method. + +=item * + +the name of the method. + +=item * + +any other parameters specific to the method. + +=back + +Here is a simple XSUB which illustrates the mechanics of calling both +the C<PrintID> and C<Display> methods from C. + + void + call_Method(ref, method, index) + SV * ref + char * method + int index + CODE: + PUSHMARK(SP); + XPUSHs(ref); + XPUSHs(sv_2mortal(newSViv(index))) ; + PUTBACK; + + perl_call_method(method, G_DISCARD) ; + + void + call_PrintID(class, method) + char * class + char * method + CODE: + PUSHMARK(SP); + XPUSHs(sv_2mortal(newSVpv(class, 0))) ; + PUTBACK; + + perl_call_method(method, G_DISCARD) ; + + +So the methods C<PrintID> and C<Display> can be invoked like this + + $a = new Mine ('red', 'green', 'blue') ; + call_Method($a, 'Display', 1) ; + call_PrintID('Mine', 'PrintID') ; + +The only thing to note is that in both the static and virtual methods, +the method name is not passed via the stack - it is used as the first +parameter to I<perl_call_method>. + +=head2 Using GIMME_V + +Here is a trivial XSUB which prints the context in which it is +currently executing. + + void + PrintContext() + CODE: + I32 gimme = GIMME_V; + if (gimme == G_VOID) + printf ("Context is Void\n") ; + else if (gimme == G_SCALAR) + printf ("Context is Scalar\n") ; + else + printf ("Context is Array\n") ; + +and here is some Perl to test it + + PrintContext ; + $a = PrintContext ; + @a = PrintContext ; + +The output from that will be + + Context is Void + Context is Scalar + Context is Array + +=head2 Using Perl to dispose of temporaries + +In the examples given to date, any temporaries created in the callback +(i.e., parameters passed on the stack to the I<perl_call_*> function or +values returned via the stack) have been freed by one of these methods + +=over 5 + +=item * + +specifying the G_DISCARD flag with I<perl_call_*>. + +=item * + +explicitly disposed of using the C<ENTER>/C<SAVETMPS> - +C<FREETMPS>/C<LEAVE> pairing. + +=back + +There is another method which can be used, namely letting Perl do it +for you automatically whenever it regains control after the callback +has terminated. This is done by simply not using the + + ENTER ; + SAVETMPS ; + ... + FREETMPS ; + LEAVE ; + +sequence in the callback (and not, of course, specifying the G_DISCARD +flag). + +If you are going to use this method you have to be aware of a possible +memory leak which can arise under very specific circumstances. To +explain these circumstances you need to know a bit about the flow of +control between Perl and the callback routine. + +The examples given at the start of the document (an error handler and +an event driven program) are typical of the two main sorts of flow +control that you are likely to encounter with callbacks. There is a +very important distinction between them, so pay attention. + +In the first example, an error handler, the flow of control could be as +follows. You have created an interface to an external library. +Control can reach the external library like this + + perl --> XSUB --> external library + +Whilst control is in the library, an error condition occurs. You have +previously set up a Perl callback to handle this situation, so it will +get executed. Once the callback has finished, control will drop back to +Perl again. Here is what the flow of control will be like in that +situation + + perl --> XSUB --> external library + ... + error occurs + ... + external library --> perl_call --> perl + | + perl <-- XSUB <-- external library <-- perl_call <----+ + +After processing of the error using I<perl_call_*> is completed, +control reverts back to Perl more or less immediately. + +In the diagram, the further right you go the more deeply nested the +scope is. It is only when control is back with perl on the extreme +left of the diagram that you will have dropped back to the enclosing +scope and any temporaries you have left hanging around will be freed. + +In the second example, an event driven program, the flow of control +will be more like this + + perl --> XSUB --> event handler + ... + event handler --> perl_call --> perl + | + event handler <-- perl_call <----+ + ... + event handler --> perl_call --> perl + | + event handler <-- perl_call <----+ + ... + event handler --> perl_call --> perl + | + event handler <-- perl_call <----+ + +In this case the flow of control can consist of only the repeated +sequence + + event handler --> perl_call --> perl + +for practically the complete duration of the program. This means that +control may I<never> drop back to the surrounding scope in Perl at the +extreme left. + +So what is the big problem? Well, if you are expecting Perl to tidy up +those temporaries for you, you might be in for a long wait. For Perl +to dispose of your temporaries, control must drop back to the +enclosing scope at some stage. In the event driven scenario that may +never happen. This means that as time goes on, your program will +create more and more temporaries, none of which will ever be freed. As +each of these temporaries consumes some memory your program will +eventually consume all the available memory in your system - kapow! + +So here is the bottom line - if you are sure that control will revert +back to the enclosing Perl scope fairly quickly after the end of your +callback, then it isn't absolutely necessary to dispose explicitly of +any temporaries you may have created. Mind you, if you are at all +uncertain about what to do, it doesn't do any harm to tidy up anyway. + + +=head2 Strategies for storing Callback Context Information + + +Potentially one of the trickiest problems to overcome when designing a +callback interface can be figuring out how to store the mapping between +the C callback function and the Perl equivalent. + +To help understand why this can be a real problem first consider how a +callback is set up in an all C environment. Typically a C API will +provide a function to register a callback. This will expect a pointer +to a function as one of its parameters. Below is a call to a +hypothetical function C<register_fatal> which registers the C function +to get called when a fatal error occurs. + + register_fatal(cb1) ; + +The single parameter C<cb1> is a pointer to a function, so you must +have defined C<cb1> in your code, say something like this + + static void + cb1() + { + printf ("Fatal Error\n") ; + exit(1) ; + } + +Now change that to call a Perl subroutine instead + + static SV * callback = (SV*)NULL; + + static void + cb1() + { + dSP ; + + PUSHMARK(SP) ; + + /* Call the Perl sub to process the callback */ + perl_call_sv(callback, G_DISCARD) ; + } + + + void + register_fatal(fn) + SV * fn + CODE: + /* Remember the Perl sub */ + if (callback == (SV*)NULL) + callback = newSVsv(fn) ; + else + SvSetSV(callback, fn) ; + + /* register the callback with the external library */ + register_fatal(cb1) ; + +where the Perl equivalent of C<register_fatal> and the callback it +registers, C<pcb1>, might look like this + + # Register the sub pcb1 + register_fatal(\&pcb1) ; + + sub pcb1 + { + die "I'm dying...\n" ; + } + +The mapping between the C callback and the Perl equivalent is stored in +the global variable C<callback>. + +This will be adequate if you ever need to have only one callback +registered at any time. An example could be an error handler like the +code sketched out above. Remember though, repeated calls to +C<register_fatal> will replace the previously registered callback +function with the new one. + +Say for example you want to interface to a library which allows asynchronous +file i/o. In this case you may be able to register a callback whenever +a read operation has completed. To be of any use we want to be able to +call separate Perl subroutines for each file that is opened. As it +stands, the error handler example above would not be adequate as it +allows only a single callback to be defined at any time. What we +require is a means of storing the mapping between the opened file and +the Perl subroutine we want to be called for that file. + +Say the i/o library has a function C<asynch_read> which associates a C +function C<ProcessRead> with a file handle C<fh> - this assumes that it +has also provided some routine to open the file and so obtain the file +handle. + + asynch_read(fh, ProcessRead) + +This may expect the C I<ProcessRead> function of this form + + void + ProcessRead(fh, buffer) + int fh ; + char * buffer ; + { + ... + } + +To provide a Perl interface to this library we need to be able to map +between the C<fh> parameter and the Perl subroutine we want called. A +hash is a convenient mechanism for storing this mapping. The code +below shows a possible implementation + + static HV * Mapping = (HV*)NULL ; + + void + asynch_read(fh, callback) + int fh + SV * callback + CODE: + /* If the hash doesn't already exist, create it */ + if (Mapping == (HV*)NULL) + Mapping = newHV() ; + + /* Save the fh -> callback mapping */ + hv_store(Mapping, (char*)&fh, sizeof(fh), newSVsv(callback), 0) ; + + /* Register with the C Library */ + asynch_read(fh, asynch_read_if) ; + +and C<asynch_read_if> could look like this + + static void + asynch_read_if(fh, buffer) + int fh ; + char * buffer ; + { + dSP ; + SV ** sv ; + + /* Get the callback associated with fh */ + sv = hv_fetch(Mapping, (char*)&fh , sizeof(fh), FALSE) ; + if (sv == (SV**)NULL) + croak("Internal error...\n") ; + + PUSHMARK(SP) ; + XPUSHs(sv_2mortal(newSViv(fh))) ; + XPUSHs(sv_2mortal(newSVpv(buffer, 0))) ; + PUTBACK ; + + /* Call the Perl sub */ + perl_call_sv(*sv, G_DISCARD) ; + } + +For completeness, here is C<asynch_close>. This shows how to remove +the entry from the hash C<Mapping>. + + void + asynch_close(fh) + int fh + CODE: + /* Remove the entry from the hash */ + (void) hv_delete(Mapping, (char*)&fh, sizeof(fh), G_DISCARD) ; + + /* Now call the real asynch_close */ + asynch_close(fh) ; + +So the Perl interface would look like this + + sub callback1 + { + my($handle, $buffer) = @_ ; + } + + # Register the Perl callback + asynch_read($fh, \&callback1) ; + + asynch_close($fh) ; + +The mapping between the C callback and Perl is stored in the global +hash C<Mapping> this time. Using a hash has the distinct advantage that +it allows an unlimited number of callbacks to be registered. + +What if the interface provided by the C callback doesn't contain a +parameter which allows the file handle to Perl subroutine mapping? Say +in the asynchronous i/o package, the callback function gets passed only +the C<buffer> parameter like this + + void + ProcessRead(buffer) + char * buffer ; + { + ... + } + +Without the file handle there is no straightforward way to map from the +C callback to the Perl subroutine. + +In this case a possible way around this problem is to predefine a +series of C functions to act as the interface to Perl, thus + + #define MAX_CB 3 + #define NULL_HANDLE -1 + typedef void (*FnMap)() ; + + struct MapStruct { + FnMap Function ; + SV * PerlSub ; + int Handle ; + } ; + + static void fn1() ; + static void fn2() ; + static void fn3() ; + + static struct MapStruct Map [MAX_CB] = + { + { fn1, NULL, NULL_HANDLE }, + { fn2, NULL, NULL_HANDLE }, + { fn3, NULL, NULL_HANDLE } + } ; + + static void + Pcb(index, buffer) + int index ; + char * buffer ; + { + dSP ; + + PUSHMARK(SP) ; + XPUSHs(sv_2mortal(newSVpv(buffer, 0))) ; + PUTBACK ; + + /* Call the Perl sub */ + perl_call_sv(Map[index].PerlSub, G_DISCARD) ; + } + + static void + fn1(buffer) + char * buffer ; + { + Pcb(0, buffer) ; + } + + static void + fn2(buffer) + char * buffer ; + { + Pcb(1, buffer) ; + } + + static void + fn3(buffer) + char * buffer ; + { + Pcb(2, buffer) ; + } + + void + array_asynch_read(fh, callback) + int fh + SV * callback + CODE: + int index ; + int null_index = MAX_CB ; + + /* Find the same handle or an empty entry */ + for (index = 0 ; index < MAX_CB ; ++index) + { + if (Map[index].Handle == fh) + break ; + + if (Map[index].Handle == NULL_HANDLE) + null_index = index ; + } + + if (index == MAX_CB && null_index == MAX_CB) + croak ("Too many callback functions registered\n") ; + + if (index == MAX_CB) + index = null_index ; + + /* Save the file handle */ + Map[index].Handle = fh ; + + /* Remember the Perl sub */ + if (Map[index].PerlSub == (SV*)NULL) + Map[index].PerlSub = newSVsv(callback) ; + else + SvSetSV(Map[index].PerlSub, callback) ; + + asynch_read(fh, Map[index].Function) ; + + void + array_asynch_close(fh) + int fh + CODE: + int index ; + + /* Find the file handle */ + for (index = 0; index < MAX_CB ; ++ index) + if (Map[index].Handle == fh) + break ; + + if (index == MAX_CB) + croak ("could not close fh %d\n", fh) ; + + Map[index].Handle = NULL_HANDLE ; + SvREFCNT_dec(Map[index].PerlSub) ; + Map[index].PerlSub = (SV*)NULL ; + + asynch_close(fh) ; + +In this case the functions C<fn1>, C<fn2>, and C<fn3> are used to +remember the Perl subroutine to be called. Each of the functions holds +a separate hard-wired index which is used in the function C<Pcb> to +access the C<Map> array and actually call the Perl subroutine. + +There are some obvious disadvantages with this technique. + +Firstly, the code is considerably more complex than with the previous +example. + +Secondly, there is a hard-wired limit (in this case 3) to the number of +callbacks that can exist simultaneously. The only way to increase the +limit is by modifying the code to add more functions and then +recompiling. None the less, as long as the number of functions is +chosen with some care, it is still a workable solution and in some +cases is the only one available. + +To summarize, here are a number of possible methods for you to consider +for storing the mapping between C and the Perl callback + +=over 5 + +=item 1. Ignore the problem - Allow only 1 callback + +For a lot of situations, like interfacing to an error handler, this may +be a perfectly adequate solution. + +=item 2. Create a sequence of callbacks - hard wired limit + +If it is impossible to tell from the parameters passed back from the C +callback what the context is, then you may need to create a sequence of C +callback interface functions, and store pointers to each in an array. + +=item 3. Use a parameter to map to the Perl callback + +A hash is an ideal mechanism to store the mapping between C and Perl. + +=back + + +=head2 Alternate Stack Manipulation + + +Although I have made use of only the C<POP*> macros to access values +returned from Perl subroutines, it is also possible to bypass these +macros and read the stack using the C<ST> macro (See L<perlxs> for a +full description of the C<ST> macro). + +Most of the time the C<POP*> macros should be adequate, the main +problem with them is that they force you to process the returned values +in sequence. This may not be the most suitable way to process the +values in some cases. What we want is to be able to access the stack in +a random order. The C<ST> macro as used when coding an XSUB is ideal +for this purpose. + +The code below is the example given in the section I<Returning a list +of values> recoded to use C<ST> instead of C<POP*>. + + static void + call_AddSubtract2(a, b) + int a ; + int b ; + { + dSP ; + I32 ax ; + int count ; + + ENTER ; + SAVETMPS; + + PUSHMARK(SP) ; + XPUSHs(sv_2mortal(newSViv(a))); + XPUSHs(sv_2mortal(newSViv(b))); + PUTBACK ; + + count = perl_call_pv("AddSubtract", G_ARRAY); + + SPAGAIN ; + SP -= count ; + ax = (SP - PL_stack_base) + 1 ; + + if (count != 2) + croak("Big trouble\n") ; + + printf ("%d + %d = %d\n", a, b, SvIV(ST(0))) ; + printf ("%d - %d = %d\n", a, b, SvIV(ST(1))) ; + + PUTBACK ; + FREETMPS ; + LEAVE ; + } + +Notes + +=over 5 + +=item 1. + +Notice that it was necessary to define the variable C<ax>. This is +because the C<ST> macro expects it to exist. If we were in an XSUB it +would not be necessary to define C<ax> as it is already defined for +you. + +=item 2. + +The code + + SPAGAIN ; + SP -= count ; + ax = (SP - PL_stack_base) + 1 ; + +sets the stack up so that we can use the C<ST> macro. + +=item 3. + +Unlike the original coding of this example, the returned +values are not accessed in reverse order. So C<ST(0)> refers to the +first value returned by the Perl subroutine and C<ST(count-1)> +refers to the last. + +=back + +=head2 Creating and calling an anonymous subroutine in C + +As we've already shown, C<perl_call_sv> can be used to invoke an +anonymous subroutine. However, our example showed how Perl script +invoking an XSUB to preform this operation. Let's see how it can be +done inside our C code: + + ... + + SV *cvrv = perl_eval_pv("sub { print 'You will not find me cluttering any namespace!' }", TRUE); + + ... + + perl_call_sv(cvrv, G_VOID|G_NOARGS); + +C<perl_eval_pv> is used to compile the anonymous subroutine, which +will be the return value as well (read more about C<perl_eval_pv> in +L<perlguts/perl_eval_pv>). Once this code reference is in hand, it +can be mixed in with all the previous examples we've shown. + +=head1 SEE ALSO + +L<perlxs>, L<perlguts>, L<perlembed> + +=head1 AUTHOR + +Paul Marquess <F<pmarquess@bfsec.bt.co.uk>> + +Special thanks to the following people who assisted in the creation of +the document. + +Jeff Okamoto, Tim Bunce, Nick Gianniotis, Steve Kelem, Gurusamy Sarathy +and Larry Wall. + +=head1 DATE + +Version 1.3, 14th Apr 1997 |
