summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl.straw/lib/pods/perlcall.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl.straw/lib/pods/perlcall.pod')
-rwxr-xr-xMaster/tlpkg/tlperl.straw/lib/pods/perlcall.pod1935
1 files changed, 0 insertions, 1935 deletions
diff --git a/Master/tlpkg/tlperl.straw/lib/pods/perlcall.pod b/Master/tlpkg/tlperl.straw/lib/pods/perlcall.pod
deleted file mode 100755
index 06f3aa33c74..00000000000
--- a/Master/tlpkg/tlperl.straw/lib/pods/perlcall.pod
+++ /dev/null
@@ -1,1935 +0,0 @@
-=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 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 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<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
-
-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<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<$@>. an error will not be appended if that same error string is
-already at the end of C<$@>.
-
-In addition, a warning is generated using the appended string. This can be
-disabled using C<no warnings 'misc'>.
-
-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 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 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 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 whilst in 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 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<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 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 $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> 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);
- 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 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 --> 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
-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<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_LIST, 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
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-26 14:49:43 +0000