| =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, such as for an X11 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 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 call_sv(SV* sv, I32 flags); |
| I32 call_pv(char *subname, I32 flags); |
| I32 call_method(char *methname, I32 flags); |
| I32 call_argv(char *subname, I32 flags, register char **argv); |
| |
| The key function is I<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<call_sv> |
| to invoke the Perl subroutine. |
| |
| All the I<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 call_sv |
| |
| I<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 call_sv>, shows how you can make |
| use of I<call_sv>. |
| |
| =item call_pv |
| |
| The function, I<call_pv>, is similar to I<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<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 call_method |
| |
| The function I<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 call_method> for an example |
| of using I<call_method>. |
| |
| =item call_argv |
| |
| I<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 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<call_*> functions is one of G_VOID, |
| G_SCALAR, or G_ARRAY, which indicate the call context, OR'ed together |
| with a bit mask of any combination of the other G_* symbols defined below. |
| |
| =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<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<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<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<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 a |
| list 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<call_*> function. |
| |
| =back |
| |
| The value returned by the I<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<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<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<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<call_*> function you need to |
| check the C<$@> variable as you would in a normal Perl script. |
| |
| The value returned from the I<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<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 |
| |
| Using the G_EVAL flag described above will always set C<$@>: clearing |
| it if there was no error, and setting it to describe the error if there |
| was an error in the called code. This is what you want if your intention |
| is to handle possible errors, but sometimes you just want to trap errors |
| and stop them interfering with the rest of the program. |
| |
| This scenario will mostly be applicable to code that is meant to be called |
| from within destructors, asynchronous callbacks, and signal handlers. |
| In such situations, where the code being called has little relation to the |
| surrounding dynamic context, the main program needs to be insulated from |
| errors in the called code, even if they can't be handled intelligently. |
| It may also be useful to do this with code for C<__DIE__> or C<__WARN__> |
| hooks, and C<tie> functions. |
| |
| The G_KEEPERR flag is meant to be used in conjunction with G_EVAL in |
| I<call_*> functions that are used to implement such code, or with |
| C<eval_sv>. This flag has no effect on the C<call_*> functions when |
| G_EVAL is not used. |
| |
| When G_KEEPERR is used, any error in the called code will terminate the |
| call as usual, and the error will not propagate beyond the call (as usual |
| for G_EVAL), but it will not go into C<$@>. Instead the error will be |
| converted into a warning, prefixed with the string "\t(in cleanup)". |
| This can be disabled using C<no warnings 'misc'>. If there is no error, |
| C<$@> will not be cleared. |
| |
| Note that the G_KEEPERR flag does not propagate into inner evals; these |
| may still set 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 a list 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 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<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<call_pv> and |
| I<call_sv>, you should always try to use I<call_sv>. See |
| I<Using 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); |
| 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<call_pv>. |
| |
| =item 4. |
| |
| As I<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<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 ($s) and an integer ($n). The subroutine will simply |
| print the first $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; |
| |
| 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<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<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. |
| |
| 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 5. |
| |
| 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 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 6. |
| |
| Finally, I<LeftString> can now be called via the I<call_pv> function. |
| 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. |
| |
| =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 = 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 that the C<@_> |
| array will be created and that the value returned by I<Adder> will |
| still exist after the call to I<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 during the |
| I<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<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<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 = 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 list 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 = 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 = 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<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<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 = call_pv("Subtract", G_EVAL|G_SCALAR); |
| |
| SPAGAIN; |
| |
| /* Check the eval first */ |
| if (SvTRUE(ERRSV)) |
| { |
| printf ("Uh oh - %s\n", SvPV_nolen(ERRSV)); |
| 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_nolen(ERRSV)); |
| 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<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 be 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; |
| { |
| my $foo = Foo->new; |
| eval { $foo->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 outer braced block, and because |
| call_Subtract is implemented with I<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<call_pv> call in |
| call_Subtract reads: |
| |
| count = call_pv("Subtract", G_EVAL|G_SCALAR|G_KEEPERR); |
| |
| will preserve the error and restore reliable error handling. |
| |
| =head2 Using 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); |
| 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<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<call_sv> instead of I<call_pv>. |
| |
| void |
| CallSubSV(name) |
| SV * name |
| CODE: |
| PUSHMARK(SP); |
| 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<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); |
| 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 has 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 $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 |
| $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> gets 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); |
| 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 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<call_argv> which will call |
| I<PrintList>. |
| |
| static char * words[] = {"alpha", "beta", "gamma", "delta", NULL}; |
| |
| static void |
| call_PrintList() |
| { |
| dSP; |
| |
| call_argv("PrintList", G_DISCARD, words); |
| } |
| |
| Note that it is not necessary to call C<PUSHMARK> in this instance. |
| This is because I<call_argv> will do it for you. |
| |
| =head2 Using 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 = Mine->new('red', 'green', 'blue'); |
| $a->Display(1); |
| Mine->PrintID; |
| |
| 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; |
| |
| call_method(method, G_DISCARD); |
| |
| void |
| call_PrintID(class, method) |
| char * class |
| char * method |
| CODE: |
| PUSHMARK(SP); |
| XPUSHs(sv_2mortal(newSVpv(class, 0))); |
| PUTBACK; |
| |
| call_method(method, G_DISCARD); |
| |
| |
| So the methods C<PrintID> and C<Display> can be invoked like this: |
| |
| $a = Mine->new('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<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<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<call_*> |
| |
| =item * |
| |
| Explicitly 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 --> call_* --> perl |
| | |
| perl <-- XSUB <-- external library <-- call_* <----+ |
| |
| After processing of the error using I<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 --> call_* --> perl |
| | |
| event handler <-- call_* <----+ |
| ... |
| event handler --> call_* --> perl |
| | |
| event handler <-- call_* <----+ |
| ... |
| event handler --> call_* --> perl |
| | |
| event handler <-- call_* <----+ |
| |
| In this case the flow of control can consist of only the repeated |
| sequence |
| |
| event handler --> 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 */ |
| 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 */ |
| 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 */ |
| 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 = 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 |
| us. |
| |
| =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<call_sv> can be used to invoke an |
| anonymous subroutine. However, our example showed a Perl script |
| invoking an XSUB to perform this operation. Let's see how it can be |
| done inside our C code: |
| |
| ... |
| |
| SV *cvrv = eval_pv("sub { print 'You will not find me cluttering any namespace!' }", TRUE); |
| |
| ... |
| |
| call_sv(cvrv, G_VOID|G_NOARGS); |
| |
| C<eval_pv> is used to compile the anonymous subroutine, which |
| will be the return value as well (read more about C<eval_pv> in |
| L<perlapi/eval_pv>). Once this code reference is in hand, it |
| can be mixed in with all the previous examples we've shown. |
| |
| =head1 LIGHTWEIGHT CALLBACKS |
| |
| Sometimes you need to invoke the same subroutine repeatedly. |
| This usually happens with a function that acts on a list of |
| values, such as Perl's built-in sort(). You can pass a |
| comparison function to sort(), which will then be invoked |
| for every pair of values that needs to be compared. The first() |
| and reduce() functions from L<List::Util> follow a similar |
| pattern. |
| |
| In this case it is possible to speed up the routine (often |
| quite substantially) by using the lightweight callback API. |
| The idea is that the calling context only needs to be |
| created and destroyed once, and the sub can be called |
| arbitrarily many times in between. |
| |
| It is usual to pass parameters using global variables (typically |
| $_ for one parameter, or $a and $b for two parameters) rather |
| than via @_. (It is possible to use the @_ mechanism if you know |
| what you're doing, though there is as yet no supported API for |
| it. It's also inherently slower.) |
| |
| The pattern of macro calls is like this: |
| |
| dMULTICALL; /* Declare local variables */ |
| I32 gimme = G_SCALAR; /* context of the call: G_SCALAR, |
| * G_ARRAY, or G_VOID */ |
| |
| PUSH_MULTICALL(cv); /* Set up the context for calling cv, |
| and set local vars appropriately */ |
| |
| /* loop */ { |
| /* set the value(s) af your parameter variables */ |
| MULTICALL; /* Make the actual call */ |
| } /* end of loop */ |
| |
| POP_MULTICALL; /* Tear down the calling context */ |
| |
| For some concrete examples, see the implementation of the |
| first() and reduce() functions of List::Util 1.18. There you |
| will also find a header file that emulates the multicall API |
| on older versions of perl. |
| |
| =head1 SEE ALSO |
| |
| L<perlxs>, L<perlguts>, L<perlembed> |
| |
| =head1 AUTHOR |
| |
| Paul Marquess |
| |
| 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 |