perl 5.000perl-5.000

[editor's note: this commit combines approximate 4 months of furious
releases of Andy Dougherty and Larry Wall - see pod/perlhist.pod for
details.  Andy notes that;
 
Alas neither my "Irwin AccuTrack" nor my DC 600A quarter-inch cartridge 
backup tapes from that era seem to be readable anymore.  I guess 13 years 
exceeds the shelf life for that backup technology :-(.
]

1 files changed, 838 insertions, 0 deletions

diff --git a/pod/perlcall.pod b/pod/perlcall.pod
new file mode 100644
index 0000000000..d81ee4a9ec
--- /dev/null
+++ b/pod/perlcall.pod
@@ -0,0 +1,838 @@
+=head1 NAME
+
+perlcall - Perl calling conventions from C
+
+=head1 DESCRIPTION
+
+B<WARNING : This document is still under construction. 
+There are bound to be a number of inaccuracies, so tread very carefully for now.>
+
+The purpose of this document is to show you how to write I<callbacks>, 
+i.e. how to call Perl from C. The main
+focus is on how to interface back to Perl from a bit of C code that has itself
+been run by Perl, i.e. the 'main' program is a Perl script; you are using it
+to execute
+a section of code written in C; that bit of C code wants you to do something
+with a particular event, so you want a Perl sub to be executed whenever it
+happens.
+
+Examples where this is necessary include
+
+=over 5
+
+=item * 
+
+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 get called whenever something nasty occurs.
+What we would like is for a Perl sub to be called instead.
+
+=item *
+
+The classic example of where callbacks are used is in an event driven program 
+like for X-windows.
+In this case your register functions to be called whenever a specific events
+occur, e.g. a mouse button is pressed.
+
+=back
+
+Although the techniques described are applicable to embedding Perl
+in a C program, this is not the primary goal of this document. For details
+on embedding Perl in C refer to L<perlembed> (currently unwritten).
+
+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<perlapi> and L<perlguts>.
+
+This stuff is easier to explain using examples. But first here are a few
+definitions anyway.
+
+=head2 Definitions
+
+Perl has a number of C functions which allow you to call Perl subs. They are
+
+    I32 perl_call_sv(SV* sv, I32 flags) ;
+    I32 perl_call_pv(char *subname, I32 flags) ;
+    I32 perl_call_method(char *methname, I32 flags) ;
+    I32 perl_call_argv(char *subname, I32 flags, register char **argv) ;
+
+The key function is I<perl_call_sv>. All the other functions make use of
+I<perl_call_sv> to do what they do.
+
+I<perl_call_sv> takes two parameters, the first is an SV*. This allows you to 
+specify the Perl sub to be called either as a C string (which has first been 
+converted to an SV) or a reference to a 
+sub. Example 7, shows you how you can make use of I<perl_call_sv>.
+The second parameter, C<flags>, is a general purpose option command. 
+This parameter is common to all the I<perl_call_*> functions. 
+It is discussed in the next section.
+
+The function, I<perl_call_pv>, is similar as I<perl_call_sv> except it 
+expects it's first parameter has to be a C char* which identifies the Perl 
+sub you want to call, e.g. C<perl_call_pv("fred", 0)>.
+
+The function I<perl_call_method> expects its first argument to contain a 
+blessed reference to a class. Using that reference it looks up and calls C<methname> 
+from that class. See example 9.
+
+I<perl_call_argv> calls the Perl sub specified by the C<subname> parameter. 
+It also takes the usual C<flags> parameter. 
+The final parameter, C<argv>, consists of a 
+list of C strings to be sent to the Perl sub. See example 8.
+
+All the functions return a number. This is a count of the number of items
+returned by the Perl sub on the stack.
+
+As a general rule you should I<always> check the return value from these 
+functions.
+Even if you are only expecting a particular number of values to be returned 
+from the Perl sub, there is nothing to stop someone from doing something
+unexpected - don't say you havn't been warned.
+
+=head2 Flag Values
+
+The C<flags> parameter in all the I<perl_call_*> functions consists of any 
+combination of the symbols defined below, OR'ed together.
+
+=over 5
+
+=item  G_SCALAR	
+
+Calls the Perl sub in a scalar context.
+
+Whatever the Perl sub actually returns, we only want a scalar. If the perl sub 
+does return a scalar, the return value from the I<perl_call_*> function 
+will be 1 or 0. If 1, then the value actually returned by the Perl sub will 
+be contained
+on the top of the stack. 
+If 0, then the sub has probably called I<die> or you have 
+used the G_DISCARD flag.
+
+If the Perl sub returns a list, the I<perl_call_*> function will still
+only return 1 or 0. If 1, then the number of elements in the list 
+will be stored on top of the stack.
+The actual values of the list will not be accessable. 
+
+
+G_SCALAR is the default flag setting for all the functions.
+
+=item G_ARRAY	
+
+Calls the Perl sub in a list context.
+
+The return code from the I<perl_call_*> functions will indicate how
+many elements of the stack are used to store the array.
+
+=item G_DISCARD	
+
+If you are not interested in the values returned by the Perl sub then setting
+this flag will make Perl get rid of them automatically for you. This will take
+precedence to either G_SCALAR or G_ARRAY.
+
+If you do 
+not set this flag then you may need to explicitly get rid of temporary values.
+See example 3 for details.
+
+=item G_NOARGS	
+
+If you are not passing any parameters to the Perl sub, you can save a bit of 
+time by setting this flag. It has the effect of of not creating the C<@_> array 
+for the Perl sub.
+
+A point worth noting is that if this flag is specified the Perl sub called can 
+still access an C<@_> array from a previous Perl sub. 
+This functionality can be illustrated with the perl code below
+
+	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>.
+
+=item G_EVAL	
+
+If the Perl sub you are calling has the ability to terminate 
+abnormally, e.g. by calling I<die> or by not actually existing, and 
+you want to catch this type of event, specify this flag setting. It will put 
+an I<eval { }> around the sub call.
+
+Whenever control returns from the I<perl_call_*> function you need to
+check the C<$@> variable as you would in a normal Perl script. 
+See example 6 for details of how to do this.
+
+
+=back
+
+
+=head1 EXAMPLES
+
+Enough of the definition talk, let's have a few examples.
+
+Perl provides many macros to assist in accessing the Perl stack. 
+These macros should always be used when interfacing to Perl internals.
+Hopefully this should make the code less vulnerable to changes made to
+Perl in the future.
+
+Another point worth noting is that in the first series of examples I have 
+only made use of the I<perl_call_pv> function. 
+This has only been done to ease you into the 
+topic. Wherever possible, if the choice is between using I<perl_call_pv> 
+and I<perl_call_sv>, I would always try to use I<perl_call_sv>.
+
+The code for these examples is stored in the file F<perlcall.tar>. 
+(Once this document settles down, all the example code will be available in the file).
+
+=head2 Example1: No Parameters, Nothing returned
+
+This first trivial example will call a Perl sub, I<PrintUID>, to print 
+out the UID of the process. 
+
+    sub PrintUID
+    {
+        print "UID is $<\n" ;
+    }
+
+and here is the C to call it
+
+    void
+    call_PrintUID()
+    {
+	dSP ;
+
+	PUSHMARK(sp) ;
+        perl_call_pv("PrintUID", G_DISCARD|G_NOARGS) ;
+    }
+
+Simple, eh. 
+
+A few points to note about this example. 
+
+=over 5
+
+=item 1. 
+
+We aren't passing any parameters to I<PrintUID> so G_NOARGS
+can be specified.
+
+=item 2.
+
+Ignore C<dSP> and C<PUSHMARK(sp)> for now. They will be discussed in the next
+example.
+
+=item 3. 
+
+We aren't interested in anything returned from I<PrintUID>, so
+G_DISCARD is specified. Even if I<PrintUID> was changed to actually
+return some value(s), having specified G_DISCARD will mean that they
+will be wiped by the time control returns from I<perl_call_pv>.
+
+=item 4. 
+
+Because we specified G_DISCARD, it is not necessary to check 
+the value returned from I<perl_call_sv>. It will always be 0.
+
+=item 5.
+
+As I<perl_call_pv> is being used, the Perl sub is specified as a C string.
+
+=back
+
+=head2 Example 2: Passing Parameters
+
+Now let's make a slightly more complex example. This time we want 
+to call a Perl sub
+which will take 2 parameters - a string (C<$s>) and an integer (C<$n>). 
+The sub will simply print the first C<$n> characters of the string.
+
+So the Perl sub 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 ;
+
+        PUSHMARK(sp) ;
+        XPUSHs(sv_2mortal(newSVpv(a, 0)));
+        XPUSHs(sv_2mortal(newSViv(b)));
+        PUTBACK ;
+
+        perl_call_pv("LeftString", G_DISCARD);
+    }
+
+
+Here are a few notes on the C function I<call_LeftString>.
+
+=over 5
+
+=item 1. 
+
+The only flag specified this time is G_DISCARD. As we are passing 2 
+parameters to the Perl sub this time, we have not specified G_NOARGS.
+
+=item 2. 
+
+Parameters are passed to the Perl sub using the Perl stack.
+This is the purpose of the code beginning with the line C<dSP> and ending
+with the line C<PUTBACK>.
+
+
+=item 3.
+
+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 initialises a 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. 
+
+If you are calling a Perl sub directly from an XSUB function, it is 
+not necessary to explicitly use the C<dSP> macro - it will be declared for you.
+
+=item 4.
+
+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 automatically count
+the number of parameters you are pushing. Then whenever Perl is creating
+the C<@_> array for the sub, 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 in Example 1) you must 
+still call the C<PUSHMARK> macro before you can call any of 
+the I<perl_call_*> functions - Perl still needs to know that there are 
+no parameters.
+
+The C<PUTBACK> macro sets the global copy of the stack pointer to be the
+same as our local copy. If we didn't do this I<perl_call_pv> wouldn't
+know where the two parameters we pushed were - remember that up to now
+all the stack pointer manipulation we have done is with our local copy,
+I<not> the global copy.
+
+=item 5.
+
+Next, we come to XPUSHs. This is where the parameters actually get
+pushed onto the stack. In this case we are pushing a string and an integer.
+
+See the section I<XSUB's AND  THE ARGUMENT STACK> in L<perlguts> for
+details on how the XPUSH macros work.
+
+=item 6.
+
+Finally, I<LeftString> can now be called via the I<perl_call_pv> function.
+
+=back
+
+=head2 Example 3: Returning a Scalar
+
+Now for an example of dealing with the values returned from a Perl sub.
+
+Here is a Perl sub, I<Adder>,  which takes 2 integer parameters and simply 
+returns their sum.
+
+    sub Adder
+    {
+        my($a, $b) = @_ ;
+        $a + $b ;
+    }
+
+As we are now concerned with the return value from I<Adder>, the C function
+is now a bit more complex.
+
+    static void
+    call_Adder(a, b)
+    int a ;
+    int b ;
+    {
+        dSP ;
+        int count ;
+
+        ENTER ;
+        SAVETMPS;
+
+        PUSHMARK(sp) ;
+        XPUSHs(sv_2mortal(newSViv(a)));
+        XPUSHs(sv_2mortal(newSViv(b)));
+        PUTBACK ;
+
+        count = perl_call_pv("Adder", G_SCALAR);
+
+        SPAGAIN ;
+
+	if (count != 1)
+	    croak("Big trouble\n") ;
+
+	printf ("The sum of %d and %d is %d\n", a, b, POPi) ;
+
+        PUTBACK ;
+        FREETMPS ;
+        LEAVE ;
+    }
+
+
+Points to note this time are
+
+=over 5
+
+=item 1. 
+
+The only flag specified this time was G_SCALAR. That means the @_ array
+will be created and that the value returned by I<Adder> will still
+exist after the call to I<perl_call_pv>.
+
+
+
+=item 2.
+
+Because we are interested in what is returned from I<Adder> we cannot specify
+G_DISCARD. This means that we will have to tidy up the Perl stack and dispose
+of any temporary values ourselves. 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 
+sub, plus it will also dump the mortal SV's we created. 
+Having C<ENTER>/C<SAVETMPS> at the beginning
+of the code makes sure that no other mortals are destroyed.
+
+=item 3.
+
+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 re-allocated whilst in the I<perl_call_pv>
+call.
+
+If you are making use of the Perl stack pointer in your code you must always
+refresh the your local copy using SPAGAIN whenever you make use of
+of the I<perl_call_*> functions or any other Perl internal function.
+
+=item 4. 
+
+Although only a single value was expected to be returned from I<Adder>, it is
+still good practice to check the return code from I<perl_call_pv> anyway.
+
+Expecting a single value is not quite the same as knowing that there will
+be one. If someone modified I<Adder> to return a list and we didn't check
+for that possibility and take appropriate action the Perl stack would end 
+up in an inconsistant state. That is something you I<really> don't want
+to ever happen.
+
+=item 5.
+
+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 6.
+
+The final C<PUTBACK> is used to leave the Perl stack in a consistant state 
+before exiting the function. This is
+necessary because when we popped the return value from the stack with C<POPi> it
+only updated 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 Example 4: 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 sub
+
+    sub AddSubtract
+    {
+       my($a, $b) = @_ ;
+       ($a+$b, $a-$b) ;
+    }
+
+
+and this is the C function
+
+    static void
+    call_AddSubtract(a, b)
+    int a ;
+    int b ;
+    {
+        dSP ;
+        int count ;
+
+        ENTER ;
+        SAVETMPS;
+
+        PUSHMARK(sp) ;
+        XPUSHs(sv_2mortal(newSViv(a)));
+        XPUSHs(sv_2mortal(newSViv(b)));
+        PUTBACK ;
+
+        count = perl_call_pv("AddSubtract", G_ARRAY);
+
+        SPAGAIN ;
+
+	if (count != 2)
+	    croak("Big trouble\n") ;
+
+	printf ("%d - %d = %d\n", a, b, POPi) ;
+	printf ("%d + %d = %d\n", a, b, POPi) ;
+
+        PUTBACK ;
+        FREETMPS ;
+        LEAVE ;
+    }
+
+
+Notes
+
+=over 5
+
+=item 1.
+
+We wanted array context, so we used G_ARRAY.
+
+=item 2.
+
+Not surprisingly there are 2 POPi's this time  because we were retrieving 2
+values from the stack. The main point to note is that they came off the stack in
+reverse order.
+
+=back
+
+=head2 Example 5: 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 sub, I<Inc>, below takes 2 parameters and increments each.
+
+    sub Inc
+    {
+        ++ $_[0] ;
+        ++ $_[1] ;
+    }
+
+and here is a C function to call it.
+
+    static void
+    call_Inc(a, b)
+    int a ;
+    int b ;
+    {
+        dSP ;
+        int count ;
+        SV * sva ;
+        SV * svb ;
+
+        ENTER ;
+        SAVETMPS;
+
+        sva = sv_2mortal(newSViv(a)) ;
+        svb = sv_2mortal(newSViv(b)) ;
+
+        PUSHMARK(sp) ;
+        XPUSHs(sva);
+        XPUSHs(svb);
+        PUTBACK ;
+
+        count = perl_call_pv("Inc", G_DISCARD);
+
+        if (count != 0)
+            croak ("call_Inc : expected 0 return value from 'Inc', got %d\n", count) ;
+
+        printf ("%d + 1 = %d\n", a, SvIV(sva)) ;
+        printf ("%d + 1 = %d\n", b, SvIV(svb)) ;
+
+    	FREETMPS ;
+	LEAVE ; 
+    }
+
+
+
+To be able to access the two parameters that were pushed onto the stack 
+after they return from I<perl_call_pv> it is necessary to make a note of
+their addresses - thus the two variables C<sva> and C<svb>. 
+
+The reason this is necessary is that
+the area of the Perl stack which held them
+will very likely have been overwritten by something else by the time control
+returns from I<perl_call_pv>.
+
+
+
+
+=head2 Example 6: Using G_EVAL
+
+Now an example using G_EVAL. Below is a Perl sub which computes the 
+difference of its 2 parameters. If this would result in a negative result,
+the sub 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 ;
+	SV * sv ;
+
+        ENTER ;
+        SAVETMPS;
+
+        PUSHMARK(sp) ;
+        XPUSHs(sv_2mortal(newSViv(a)));
+        XPUSHs(sv_2mortal(newSViv(b)));
+        PUTBACK ;
+
+        count = perl_call_pv("Subtract", G_EVAL|G_SCALAR);
+
+	/* Check the eval first */
+        sv = GvSV(gv_fetchpv("@", TRUE, SVt_PV));
+        if (SvTRUE(sv))
+            printf ("Uh oh - %s\n", SvPV(sv, na)) ;
+
+        SPAGAIN ;
+
+        if (count != 1)
+            croak ("call_Subtract : expected 1 return 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.
+
+=item 2.
+
+The code 
+
+        sv = GvSV(gv_fetchpv("@", TRUE, SVt_PV));
+        if (SvTRUE(sv))
+            printf ("Uh oh - %s\n", SvPVx(sv, na)) ;
+
+is the equivalent of this bit of Perl
+
+	print "Uh oh - $@\n" if $@ ;
+
+
+
+=back
+
+
+=head2 Example 7: Using perl_call_sv
+
+In all the previous examples I have 'hard-wried' the name of the Perl sub to
+be called from C. 
+Sometimes though, it is necessary to be able to specify the name
+of the Perl sub from within the Perl script.
+
+Consider the Perl code below
+
+	sub fred
+	{
+	    print "Hello there\n" ;
+	}
+
+	CallSub("fred") ;
+
+
+here is a snippet of XSUB which defines I<CallSub>.
+
+	void
+	CallSub(name)
+		char *	name
+		CODE:
+		PUSHMARK(sp) ;
+		perl_call_pv(name, G_DISCARD|G_NOARGS) ;
+
+That is fine as far as it goes. The thing is, it only allows the Perl sub to be
+specified as a string. 
+For perl 4 this was adequate, but Perl 5 allows references to 
+subs and anonymous subs. This is where I<perl_call_sv> is useful.
+
+The code below for I<CallSub> is identical to the previous time except that the
+C<name> parameter is now defined as an SV* and we use I<perl_call_sv> instead of
+I<perl_call_pv>.
+
+	void
+	CallSub(name)
+		SV*	name
+		CODE:
+		PUSHMARK(sp) ;
+		perl_call_sv(name, G_DISCARD|G_NOARGS) ;
+
+As we are using an SV to call I<fred> the following can all be used
+
+	CallSub("fred") ;
+	Callsub(\&fred) ;
+	$ref = \&fred ;
+	CallSub($ref) ;
+	CallSub( sub { print "Hello there\n" } ) ;
+
+As you can see, I<perl_call_sv> gives you greater flexibility in how you 
+can specify the Perl sub.
+
+=head2 Example 8: Using perl_call_argv
+
+Here is a Perl sub which prints whatever parameters are passed to it.
+
+	sub PrintList
+	{
+	    my(@list) = @_ ;
+
+	    foreach (@list) { print "$_\n" }
+	}
+
+and here is an example of I<perl_call_argv> which will call I<PrintList>.
+
+	call_PrintList
+	{
+	    dSP ;
+	    char * words[] = {"alpha", "beta", "gamma", "delta", NULL } ;
+
+	    perl_call_argv("PrintList", words, G_DISCARD) ;
+	}
+
+Note that it is not necessary to call C<PUSHMARK> in this instance. This is
+because I<perl_call_argv> will do it for you.
+
+=head2 Example 9: Using perl_call_method
+
+[This section is under construction]
+
+Consider the following Perl code
+
+	{
+	  package Mine ;
+
+	  sub new     { bless [@_] }
+	  sub Display { print $_[0][1], "\n" }
+	}
+
+	$a = new Mine ('red', 'green', 'blue') ;
+	call_Display($a, 'Display') ;
+
+The method C<Display> just prints out the first element of the list.
+Here is a XSUB implementation of I<call_Display>.
+
+	void
+	call_Display(ref, method)
+            SV *    ref
+            char *  method
+            CODE:
+            PUSHMARK(sp);
+            XPUSHs(ref);
+            PUTBACK;
+
+            perl_call_method(method, G_DISCARD) ;
+
+
+
+
+=head2 Strategies for storing Context Information
+
+[This section is under construction]
+
+One of the trickiest problems to overcome when designing a callback interface 
+is figuring 
+out how to store the mapping between the C callback functions and the 
+Perl equivalent.
+
+Consider the following example.
+
+=head2 Alternate Stack Manipulation
+
+[This section is under construction]
+
+Although I have only made use of the POP* macros to access values returned 
+from Perl subs, it is also possible to bypass these macros and read the 
+stack directly.
+
+The code below is example 4 recoded to 
+
+=head1 SEE ALSO
+
+L<perlapi>, L<perlguts>, L<perlembed>
+
+=head1 AUTHOR
+
+Paul Marquess <pmarquess@bfsec.bt.co.uk>
+
+Special thanks to the following people who assisted in the creation of the 
+document.
+
+Jeff Okamoto, Tim Bunce.
+
+=head1 DATE
+
+Version 0.4, 17th October 1994
+
+