diff options
| -rw-r--r-- | pod/perlapi.pod | 34 | ||||
| -rw-r--r-- | pod/perlbot.pod | 78 | ||||
| -rw-r--r-- | pod/perlcall.pod | 1748 | ||||
| -rw-r--r-- | pod/perlguts.pod | 378 |
4 files changed, 1789 insertions, 449 deletions
diff --git a/pod/perlapi.pod b/pod/perlapi.pod index 7519e875e0..22df2e2011 100644 --- a/pod/perlapi.pod +++ b/pod/perlapi.pod @@ -100,6 +100,11 @@ function is called with the correct parameters. This abstraction will allow the programmer to create a more Perl-like interface to the C function. +It is recommended that the B<h2xs> tool be used when creating new +extensions. This tool will generate template source files and Makefiles. +This is discussed in more detail in the section titled "Creating A New +Extension" and in the B<h2xs> manpage. + =head2 The Anatomy of an XSUB The following XSUB allows a Perl program to access a C library function called sin(). The XSUB will imitate the C @@ -277,7 +282,8 @@ its parameters. The Perl usage is given first. The XSUB follows. - bool_t rpcb_gettime(host,timep) + bool_t + rpcb_gettime(host,timep) char * host time_t timep CODE: @@ -294,7 +300,7 @@ typemaps and ensures the resulting C code is legal. =head2 The NO_INIT Keyword The NO_INIT keyword is used to indicate that a function -parameter is being used only as an output value. The B<xsubpp> +parameter is being used as only an output value. The B<xsubpp> compiler will normally generate code to read the values of all function parameters from the argument stack and assign them to C variables upon entry to the function. NO_INIT @@ -303,7 +309,7 @@ output rather than for input and that they will be handled before the function terminates. The following example shows a variation of the rpcb_gettime() function. -This function uses the timep variable only as an output variable and does +This function uses the timep variable as only an output variable and does not care about its initial contents. bool_t @@ -382,7 +388,7 @@ create an XSUB which accepts a list of parameters of unknown length. The I<host> parameter for the rpcb_gettime() XSUB can be optional so the ellipsis can be used to indicate that the XSUB will take a variable number of parameters. Perl should -be able to call this XSUB with either of the following statments. +be able to call this XSUB with either of the following statements. $status = rpcb_gettime( $timep, $host ); @@ -409,7 +415,7 @@ The XS code, with ellipsis, follows. The PPCODE: keyword is an alternate form of the CODE: keyword and is used to tell the B<xsubpp> compiler that the programmer is supplying the code to -control the argument stack for the XSUBs return values. Occassionally one +control the argument stack for the XSUBs return values. Occasionally one will want an XSUB to return a list of values rather than a single value. In these cases one must use PPCODE: and then explicitly push the list of values on the stack. The PPCODE: and CODE: keywords are not used @@ -419,7 +425,8 @@ The following XSUB will call the C rpcb_gettime() function and will return its two output values, timep and status, to Perl as a single list. - void rpcb_gettime(host) + void + rpcb_gettime(host) char * host PPCODE: { @@ -454,7 +461,7 @@ the following statement. =head2 Returning Undef And Empty Lists -Occassionally the programmer will want to simply return +Occasionally the programmer will want to simply return C<undef> or an empty list if a function fails rather than a separate status value. The rpcb_gettime() function offers just this situation. If the function succeeds we would like @@ -611,7 +618,8 @@ reference. The result will be another SV which points to the actual Perl variable. This can then be dereferenced with SvPVX(), SvNVX(), or SvIVX(). The following XSUB will use SvRV(). - void rpcb_gettime() + void + rpcb_gettime() PPCODE: { char *host; @@ -645,7 +653,7 @@ a possibly empty SV. XSUBs may use B<perl_get_av()>, B<perl_get_hv()>, and B<perl_get_cv()> to access Perl arrays, hashes, and code values. -=head2 Interface Stategy +=head2 Interface Strategy When designing an interface between Perl and a C library a straight translation from C to XS is often sufficient. The interface will often be @@ -658,7 +666,7 @@ Identify the C functions which modify their parameters. The XSUBs for these functions may be able to return lists to Perl, or may be candidates to return undef or an empty list in case of failure. -Identify which values are used only by the C and XSUB functions +Identify which values are used by only the C and XSUB functions themselves. If Perl does not need to access the contents of the value then it may not be necessary to provide a translation for that value from C to Perl. @@ -716,7 +724,7 @@ designed to handle pointers to complex objects. The T_PTRREF type will allow the Perl object to be unblessed while the T_PTROBJ type requires that the object be blessed. By using T_PTROBJ one can achieve a form of type-checking -since the XSUB will attempt to verify that the Perl object +because the XSUB will attempt to verify that the Perl object is of the expected type. The following XS code shows the getnetconfigent() function which is used @@ -947,5 +955,5 @@ File C<rpctest.pl>: Perl test program for the RPC extension. =head1 AUTHOR -Dean Roehrich C<roehrich@cray.com> -September 27, 1994 +Dean Roehrich F<E<lt>roehrich@cray.comE<gt>> +May 3, 1995 diff --git a/pod/perlbot.pod b/pod/perlbot.pod index 3df273be7d..fb94560948 100644 --- a/pod/perlbot.pod +++ b/pod/perlbot.pod @@ -248,7 +248,7 @@ that it is impossible to override the BAZ() method. $a->bar; Now we try to override the BAZ() method. We would like FOO::bar() to call -GOOP::BAZ(), but this cannot happen since FOO::bar() explicitly calls +GOOP::BAZ(), but this cannot happen because FOO::bar() explicitly calls FOO::private::BAZ(). package FOO; @@ -365,3 +365,79 @@ method where that data is located. $a->enter; $b->enter; +=head1 INHERITING A CONSTRUCTOR + +An inheritable constructor should use the second form of bless() which allows +blessing directly into a specified class. Notice in this example that the +object will be a BAR not a FOO, even though the constructor is in class FOO. + + package FOO; + + sub new { + my $type = shift; + my $self = {}; + bless $self, $type; + } + + sub baz { + print "in FOO::baz()\n"; + } + + package BAR; + @ISA = qw(FOO); + + sub baz { + print "in BAR::baz()\n"; + } + + package main; + + $a = BAR->new; + $a->baz; + +=head1 DELEGATION + +Some classes, such as SDBM_File, cannot be effectively subclassed because +they create foreign objects. Such a class can be extended with some sort of +aggregation technique such as the "using" relationship mentioned earlier or +by delegation. + +The following example demonstrates delegation using an AUTOLOAD() function to +perform message-forwarding. This will allow the Mydbm object to behave +exactly like an SDBM_File object. The Mydbm class could now extend the +behavior by adding custom FETCH() and STORE() methods, if this is desired. + + package Mydbm; + + require SDBM_File; + require TieHash; + @ISA = qw(TieHash); + + sub TIEHASH { + my $type = shift; + my $ref = SDBM_File->new(@_); + bless {'delegate' => $ref}; + } + + sub AUTOLOAD { + my $self = shift; + + # The Perl interpreter places the name of the + # message in a variable called $AUTOLOAD. + + # DESTROY messages should never be propagated. + return if $AUTOLOAD =~ /::DESTROY$/; + + # Remove the package name. + $AUTOLOAD =~ s/^Mydbm:://; + + # Pass the message to the delegate. + $self->{'delegate'}->$AUTOLOAD(@_); + } + + package main; + use Fcntl qw( O_RDWR O_CREAT ); + + tie %foo, Mydbm, "adbm", O_RDWR|O_CREAT, 0640; + $foo{'bar'} = 123; + print "foo-bar = $foo{'bar'}\n"; diff --git a/pod/perlcall.pod b/pod/perlcall.pod index d81ee4a9ec..bde86796ac 100644 --- a/pod/perlcall.pod +++ b/pod/perlcall.pod @@ -4,255 +4,454 @@ 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 call Perl subroutines +directly from C, i.e. how to write I<callbacks>. -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. +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 this is necessary include +Examples where callbacks are necessary include =over 5 -=item * +=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 get called whenever something nasty occurs. -What we would like is for a Perl sub to be called instead. +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 * +=item * An Event Driven Program -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. +The classic example of where callbacks are used is when writing an +event driven program like for an X windows application. In this case +your 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 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). +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<perlapi> and L<perlguts>. +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. +=head1 THE PERL_CALL FUNCTIONS -=head2 Definitions +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 which allow you to call Perl subs. They are +Perl has a number of C functions that allow you to call Perl +subroutines. They are I32 perl_call_sv(SV* sv, I32 flags) ; I32 perl_call_pv(char *subname, I32 flags) ; I32 perl_call_method(char *methname, I32 flags) ; I32 perl_call_argv(char *subname, I32 flags, register char **argv) ; -The key function is I<perl_call_sv>. All the other functions make use of -I<perl_call_sv> to do what they do. +The key function is I<perl_call_sv>. All the other functions are +fairly simple wrappers which make it easier to call Perl subroutines in +special cases. At the end of the day they will all call I<perl_call_sv> +to actually invoke the Perl subroutine. + +All the I<perl_call_*> functions have a C<flags> parameter which is +used to pass a bit mask of options to Perl. This bit mask operates +identically for each of the functions. The settings available in the +bit mask are discussed in L<FLAG VALUES>. + +Each of the functions will now be discussed in turn. + +=over 5 + +=item B<perl_call_sv> + +I<perl_call_sv> takes two parameters, the first, C<sv>, is an SV*. +This allows you to specify the Perl subroutine to be called either as a +C string (which has first been converted to an SV) or a reference to a +subroutine. The section, I<Using perl_call_sv>, shows how you can make +use of I<perl_call_sv>. + +=item B<perl_call_pv> + +The function, I<perl_call_pv>, is similar to I<perl_call_sv> except it +expects its first parameter to be a C char* which identifies the Perl +subroutine you want to call, e.g. C<perl_call_pv("fred", 0)>. If the +subroutine you want to call is in another package, just include the +package name in the string, e.g. C<"pkg::fred">. + +=item B<perl_call_method> + +The function I<perl_call_method> is used to call a method from a Perl +class. The parameter C<methname> corresponds to the name of the method +to be called. Note that the class that the method belongs to is passed +on the Perl stack rather than in the parameter list. This class can be +either the name of the class (for a static method) or a reference to an +object (for a virtual method). See L<perlobj> for more information on +static and virtual methods and L<Using perl_call_method> for an example +of using I<perl_call_method>. + +=item B<perl_call_argv> + +I<perl_call_argv> calls the Perl subroutine specified by the C string +stored in the C<subname> parameter. It also takes the usual C<flags> +parameter. The final parameter, C<argv>, consists of a NULL terminated +list of C strings to be passed as parameters to the Perl subroutine. +See I<Using perl_call_argv>. + +=back + +All the functions return an integer. This is a count of the number of +items returned by the Perl subroutine. The actual items returned by the +subroutine are stored on the Perl stack. + +As a general rule you should I<always> check the return value from +these functions. Even if you are expecting only a particular number of +values to be returned from the Perl subroutine, there is nothing to +stop someone from doing something unexpected - don't say you haven't +been warned. + +=head1 FLAG VALUES + +The C<flags> parameter in all the I<perl_call_*> functions is a bit mask +which can consist of any combination of the symbols defined below, +OR'ed together. + + +=head2 G_SCALAR + +Calls the Perl subroutine in a scalar context. This is the default +context flag setting for all the I<perl_call_*> functions. + +This flag has 2 effects + +=over 5 + +=item 1. + +it indicates to the subroutine being called that it is executing in a +scalar context (if it executes I<wantarray> the result will be false). -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)>. +=item 2. + +it ensures that only a scalar is actually returned from the subroutine. +The subroutine can, of course, ignore the I<wantarray> and return a +list anyway. If so, then only the last element of the list will be +returned. + +=back + +The value returned by the I<perl_call_*> function indicates how may +items have been returned by the Perl subroutine - in this case it will +be either 0 or 1. -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. +If 0, then you have specified the G_DISCARD flag. -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. +If 1, then the item actually returned by the Perl subroutine will be +stored on the Perl stack - the section I<Returning a Scalar> shows how +to access this value on the stack. Remember that regardless of how +many items the Perl subroutine returns, only the last one will be +accessible from the stack - think of the case where only one value is +returned as being a list with only one element. Any other items that +were returned will not exist by the time control returns from the +I<perl_call_*> function. The section I<Returning a list in a scalar +context> shows an example of this behaviour. -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 G_ARRAY -=head2 Flag Values +Calls the Perl subroutine in a list context. -The C<flags> parameter in all the I<perl_call_*> functions consists of any -combination of the symbols defined below, OR'ed together. +As with G_SCALAR, this flag has 2 effects =over 5 -=item G_SCALAR +=item 1. + +it indicates to the subroutine being called that it is executing in an +array context (if it executes I<wantarray> the result will be true). -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. +=item 2. -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. +it ensures that all items returned from the subroutine will be +accessible when control returns from the I<perl_call_*> function. +=back -G_SCALAR is the default flag setting for all the functions. +The value returned by the I<perl_call_*> function indicates how may +items have been returned by the Perl subroutine. -=item G_ARRAY +If 0, the you have specified the G_DISCARD flag. -Calls the Perl sub in a list context. +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. -The return code from the I<perl_call_*> functions will indicate how -many elements of the stack are used to store the array. +=head2 G_DISCARD -=item G_DISCARD +By default, the I<perl_call_*> functions place the items returned from +by the Perl subroutine on the stack. If you are not interested in +these items, then setting this flag will make Perl get rid of them +automatically for you. Note that it is still possible to indicate a +context to the Perl subroutine by using either G_SCALAR or G_ARRAY. -If you 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 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 +explicitly dispose of these temporaries 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. -If you do -not set this flag then you may need to explicitly get rid of temporary values. -See example 3 for details. +=head2 G_NOARGS -=item G_NOARGS +Whenever a Perl subroutine is called using one of the I<perl_call_*> +functions, it is assumed by default that parameters are to be passed to +the subroutine. If you are not passing any parameters to the Perl +subroutine, you can save a bit of time by setting this flag. It has +the effect of not creating the C<@_> array for the Perl subroutine. -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. +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. -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 +In fact, what can happen is that the Perl subroutine you have called +can access the C<@_> array from a previous Perl subroutine. This will +occur when the code that is executing the I<perl_call_*> function has +itself been called from another Perl subroutine. The code below +illustrates this - sub fred - { print "@_\n" } + sub fred + { print "@_\n" } - sub joe - { &fred } + sub joe + { &fred } - &joe(1,2,3) ; + &joe(1,2,3) ; This will print - 1 2 3 + 1 2 3 + +What has happened is that C<fred> accesses the C<@_> array which +belongs to C<joe>. -What has happened is that C<fred> accesses the C<@_> array which belongs to C<joe>. -=item G_EVAL +=head2 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. +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 of events occurs, the +process will terminate immediately. If though, you want to trap this +type of event, specify the G_EVAL flag. It will put an I<eval { }> +around the subroutine call. Whenever control returns from the I<perl_call_*> function you need to -check the C<$@> variable as you would in a normal Perl script. -See example 6 for details of how to do this. +check the C<$@> variable as you would in a normal Perl script. + +The value returned from the I<perl_call_*> function is dependent on +what other flags have been specified and whether an error has +occurred. Here are all the different cases that can occur + +=over 5 + +=item * + +If the I<perl_call_*> function returns normally, then the value +returned is as specified in the previous sections. + +=item * + +If G_DISCARD is specified, the return value will always be 0. + +=item * + +If G_ARRAY is specified I<and> an error has occurred, the return value +will always be 0. + +=item * +If G_SCALAR is specified I<and> an error has occurred, the return value +will be 1 and the value on the top of the stack will be I<undef>. This +means that if you have already detected the error by checking C<$@> and +you want the program to continue, you must remember to pop the I<undef> +from the stack. =back +See I<Using G_EVAL> for details of using G_EVAL. + +=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> macro. This will return C<G_SCALAR> +if you have been called in a scalar context and C<G_ARRAY> if in an +array context. An example of using the C<GIMME> macro is shown in +section I<Using GIMME>. + +=head1 KNOWN PROBLEMS + +This section outlines all known problems that exist in the +I<perl_call_*> functions. + +=over 5 + +=item 1. + +If you are intending to make use of both the G_EVAL and G_SCALAR flags +in your code, use a version of Perl greater than 5.000. There is a bug +in version 5.000 of Perl which means that the combination of these two +flags will not work as described in the section I<FLAG VALUES>. + +Specifically, if the two flags are used when calling a subroutine and +that subroutine does not call I<die>, the value returned by +I<perl_call_*> will be wrong. + + +=item 2. + +In Perl 5.000 and 5.001 there is a problem with using I<perl_call_*> if +the Perl sub you are calling attempts to trap a I<die>. + +The symptom of this problem is that the called Perl sub will continue +to completion, but whenever it attempts to pass control back to the +XSUB, the program will immediately terminate. + +For example, say you want to call this Perl sub + + sub fred + { + eval { die "Fatal Error" ; } + print "Trapped error: $@\n" + if $@ ; + } + +via this XSUB + + void + Call_fred() + CODE: + PUSHMARK(sp) ; + perl_call_pv("fred", G_DISCARD|G_NOARGS) ; + fprintf(stderr, "back in Call_fred\n") ; + +When C<Call_fred> is executed it will print + + Trapped error: Fatal Error + +As control never returns to C<Call_fred>, the C<"back in Call_fred"> +string will not get printed. + +To work around this problem, you can either upgrade to Perl 5.002 (or +later), or use the G_EVAL flag with I<perl_call_*> as shown below + + void + Call_fred() + CODE: + PUSHMARK(sp) ; + perl_call_pv("fred", G_EVAL|G_DISCARD|G_NOARGS) ; + fprintf(stderr, "back in Call_fred\n") ; + +=back + + =head1 EXAMPLES Enough of the definition talk, let's have a few examples. -Perl provides many macros to assist in accessing the Perl stack. -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>. +Perl provides many macros to assist in accessing the Perl stack. +Wherever possible, these macros should always be used when interfacing +to Perl internals. Hopefully this should make the code less vulnerable +to any changes made to Perl in the future. -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). +Another point worth noting is that in the first series of examples I +have made use of only the I<perl_call_pv> function. This has been done +to keep the code simpler and ease you into the topic. Wherever +possible, if the choice is between using I<perl_call_pv> and +I<perl_call_sv>, you should always try to use I<perl_call_sv>. See +I<Using perl_call_sv> for details. -=head2 Example1: No Parameters, Nothing returned +=head2 No Parameters, Nothing returned -This first trivial example will call a Perl sub, I<PrintUID>, to print -out the UID of the process. +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 the C to call it +and here is a C function to call it - void + static void call_PrintUID() { - dSP ; + dSP ; - PUSHMARK(sp) ; + PUSHMARK(sp) ; perl_call_pv("PrintUID", G_DISCARD|G_NOARGS) ; } -Simple, eh. +Simple, eh. -A few points to note about this example. +A few points to note about this example. =over 5 -=item 1. +=item 1. -We aren't passing any parameters to I<PrintUID> so G_NOARGS -can be specified. +Ignore C<dSP> and C<PUSHMARK(sp)> for now. They will be discussed in +the next example. =item 2. -Ignore C<dSP> and C<PUSHMARK(sp)> for now. They will be discussed in the next -example. +We aren't passing any parameters to I<PrintUID> so G_NOARGS can be +specified. -=item 3. +=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. +=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. +As I<perl_call_pv> is being used, the Perl subroutine is specified as a +C string. In this case the subroutine name has been 'hard-wired' into the +code. =item 5. -As I<perl_call_pv> is being used, the Perl sub is specified as a C string. +Because we specified G_DISCARD, it is not necessary to check the value +returned from I<perl_call_pv>. It will always be 0. =back -=head2 Example 2: Passing Parameters +=head2 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. +Now let's make a slightly more complex example. This time we want to +call a Perl subroutine, C<LeftString>, which will take 2 parameters - a +string (C<$s>) and an integer (C<$n>). The subroutine will simply +print the first C<$n> characters of the string. -So the Perl sub would look like this +So the Perl subroutine would look like this sub LeftString { @@ -277,75 +476,81 @@ The C function required to call I<LeftString> would look like this. 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. +=item 1. -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>. +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>. -=item 3. +=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 initialises a local copy of the Perl stack pointer. +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. +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. +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 +explicitly use the C<dSP> macro - it will be declared for you +automatically. -=item 4. +=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 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. +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 +subroutine, it knows how big to make it. + +The C<PUSHMARK> macro tells Perl to make a mental note of the current +stack pointer. Even if you aren't passing any parameters (like the +example shown in the section I<No Parameters, Nothing returned>) you +must still call the C<PUSHMARK> macro before you can call any of the +I<perl_call_*> functions - Perl still needs to know that there are no +parameters. + +The C<PUTBACK> macro sets the global copy of the stack pointer to be +the same as our local copy. If we didn't do this I<perl_call_pv> +wouldn't know where the two parameters we pushed were - remember that +up to now all the stack pointer manipulation we have done is with our +local copy, I<not> the global copy. + +=item 4. + +The only flag specified this time is G_DISCARD. Since we are passing 2 +parameters to the Perl subroutine this time, we have not specified +G_NOARGS. =item 5. Next, we come to XPUSHs. This is where the parameters actually get -pushed onto the stack. In this case we are pushing a string and an integer. +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. +See the section L<perlguts/"XSUB'S and the Argument Stack"> for details +on how the XPUSH macros work. =item 6. -Finally, I<LeftString> can now be called via the I<perl_call_pv> function. +Finally, I<LeftString> can now be called via the I<perl_call_pv> +function. =back -=head2 Example 3: Returning a Scalar +=head2 Returning a Scalar -Now for an example of dealing with the values returned from a Perl sub. +Now for an example of dealing with the items returned from a Perl +subroutine. -Here is a Perl sub, I<Adder>, which takes 2 integer parameters and simply -returns their sum. +Here is a Perl subroutine, I<Adder>, which takes 2 integer parameters +and simply returns their sum. sub Adder { @@ -353,8 +558,8 @@ returns their sum. $a + $b ; } -As we are now concerned with the return value from I<Adder>, the C function -is now a bit more complex. +Since 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) @@ -376,107 +581,113 @@ is now a bit more complex. SPAGAIN ; - if (count != 1) - croak("Big trouble\n") ; + if (count != 1) + croak("Big trouble\n") ; - printf ("The sum of %d and %d is %d\n", a, b, POPi) ; + 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>. +The only flag specified this time was G_SCALAR. That means the C<@_> +array will be created and that the value returned by I<Adder> will +still exist after the call to I<perl_call_pv>. =item 2. -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 +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 ; + ENTER ; + SAVETMPS ; at the start of the function, and - FREETMPS ; - LEAVE ; + 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. -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, plus it will also dump the mortal SV's we have +created. Having C<ENTER>/C<SAVETMPS> at the beginning of the code +makes sure that no other mortals are destroyed. -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. +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 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. +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 +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 the I<perl_call_*> functions or any other Perl internal function. -=item 4. +=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. +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. +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 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. +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. +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 + 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. +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 Example 4: Returning a list of values +=head2 Returning a list of values -Now, let's extend the previous example to return both the sum of the parameters -and the difference. +Now, let's extend the previous example to return both the sum of the +parameters and the difference. -Here is the Perl sub +Here is the Perl subroutine sub AddSubtract { @@ -484,7 +695,6 @@ Here is the Perl sub ($a+$b, $a-$b) ; } - and this is the C function static void @@ -507,17 +717,25 @@ and this is the C function SPAGAIN ; - if (count != 2) - croak("Big trouble\n") ; + if (count != 2) + croak("Big trouble\n") ; - printf ("%d - %d = %d\n", a, b, POPi) ; - printf ("%d + %d = %d\n", a, b, POPi) ; + 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 @@ -525,22 +743,77 @@ Notes =item 1. -We wanted array context, so we used G_ARRAY. +We wanted array context, so G_ARRAY was used. =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. +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 Example 5: Returning Data from Perl via the parameter list +=head2 Returning a list in a scalar context + +Say the Perl subroutine in the previous section was called in a scalar +context, like this + + static void + call_AddSubScalar(a, b) + int a ; + int b ; + { + dSP ; + int count ; + int i ; + + ENTER ; + SAVETMPS; + + PUSHMARK(sp) ; + XPUSHs(sv_2mortal(newSViv(a))); + XPUSHs(sv_2mortal(newSViv(b))); + PUTBACK ; + + count = perl_call_pv("AddSubtract", G_SCALAR); + + SPAGAIN ; + + printf ("Items Returned = %d\n", count) ; + + for (i = 1 ; i <= count ; ++i) + printf ("Value %d = %d\n", i, POPi) ; + + PUTBACK ; + FREETMPS ; + LEAVE ; + } + +The other modification made is that I<call_AddSubScalar> will print the +number of items returned from the Perl subroutine and their value (for +simplicity it assumes that they are integer). So if +I<call_AddSubScalar> is called + + call_AddSubScalar(7, 4) ; + +then the output will be + + Items Returned = 1 + Value 1 = 3 + +In this case the main point to note is that only the last item in the +list returned from the subroutine, I<Adder> 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 sub, I<Inc>, below takes 2 parameters and increments each. +The Perl subroutine, I<Inc>, below takes 2 parameters and increments +each directly. sub Inc { @@ -574,43 +847,40 @@ and here is a C function to call it. count = perl_call_pv("Inc", G_DISCARD); if (count != 0) - croak ("call_Inc : expected 0 return value from 'Inc', got %d\n", count) ; + 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 ; + 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>. - -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>. +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>. +=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) = @_ ; + my ($a, $b) = @_ ; die "death can be fatal\n" if $a < $b ; - $a - $b ; + $a - $b ; } and some C to call it @@ -622,7 +892,7 @@ and some C to call it { dSP ; int count ; - SV * sv ; + SV * sv ; ENTER ; SAVETMPS; @@ -634,32 +904,36 @@ and some C to call it count = perl_call_pv("Subtract", G_EVAL|G_SCALAR); - /* Check the eval first */ + SPAGAIN ; + + /* Check the eval first */ sv = GvSV(gv_fetchpv("@", TRUE, SVt_PV)); if (SvTRUE(sv)) + { printf ("Uh oh - %s\n", SvPV(sv, na)) ; + POPs ; + } + else + { + if (count != 1) + croak("call_Subtract: wanted 1 value from 'Subtract', got %d\n", + count) ; - 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) ; + printf ("%d - %d = %d\n", a, b, POPi) ; + } PUTBACK ; FREETMPS ; LEAVE ; - } If I<call_Subtract> is called thus - call_Subtract(4, 5) + call_Subtract(4, 5) the following will be printed - Uh oh - death can be fatal + Uh oh - death can be fatal Notes @@ -667,156 +941,882 @@ Notes =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. +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 - sv = GvSV(gv_fetchpv("@", TRUE, SVt_PV)); - if (SvTRUE(sv)) - printf ("Uh oh - %s\n", SvPVx(sv, na)) ; + sv = GvSV(gv_fetchpv("@", TRUE, SVt_PV)); + if (SvTRUE(sv)) + { + printf ("Uh oh - %s\n", SvPVx(sv, na)) ; + POPs ; + } -is the equivalent of this bit of Perl +is the direct equivalent of this bit of Perl - print "Uh oh - $@\n" if $@ ; + print "Uh oh - $@\n" if $@ ; +=item 3. +Note that the stack is popped using C<POPs> in the block where +C<SvTRUE(sv)> is true. This is necessary because whenever a +I<perl_call_*> function invoked with G_EVAL|G_SCALAR returns an error, +the top of the stack holds the value I<undef>. Since 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 Example 7: Using perl_call_sv +=head2 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. +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" ; - } + sub fred + { + print "Hello there\n" ; + } + + CallSubPV("fred") ; + +Here is a snippet of XSUB which defines I<CallSubPV>. + + void + CallSubPV(name) + char * name + CODE: + PUSHMARK(sp) ; + perl_call_pv(name, G_DISCARD|G_NOARGS) ; - CallSub("fred") ; +That is fine as far as it goes. The thing is, the Perl subroutine +can be specified only as a string. For Perl 4 this was adequate, +but Perl 5 allows references to subroutines and anonymous subroutines. +This is where I<perl_call_sv> is useful. + +The code below for I<CallSubSV> is identical to I<CallSubPV> except +that the C<name> parameter is now defined as an SV* and we use +I<perl_call_sv> instead of I<perl_call_pv>. + + void + CallSubSV(name) + SV * name + CODE: + PUSHMARK(sp) ; + perl_call_sv(name, G_DISCARD|G_NOARGS) ; +Since we are using an SV to call I<fred> the following can all be used -here is a snippet of XSUB which defines I<CallSub>. + CallSubSV("fred") ; + CallSubSV(\&fred) ; + $ref = \&fred ; + CallSubSV($ref) ; + CallSubSV( sub { print "Hello there\n" } ) ; - void - CallSub(name) - char * name - CODE: - PUSHMARK(sp) ; - perl_call_pv(name, G_DISCARD|G_NOARGS) ; +As you can see, I<perl_call_sv> gives you much greater flexibility in +how you can specify the Perl subroutine. + +You should note that if it is necessary to store the SV (C<name> in the +example above) which corresponds to the Perl subroutine so that it can +be used later in the program, it not enough to just store a copy of the +pointer to the SV. Say the code above had been like this + + static SV * rememberSub ; + + void + SaveSub1(name) + SV * name + CODE: + rememberSub = name ; + + void + CallSavedSub1() + CODE: + PUSHMARK(sp) ; + perl_call_sv(rememberSub, G_DISCARD|G_NOARGS) ; -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 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 -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>. + SaveSub1(\&fred) ; + CallSavedSub1() ; - void - CallSub(name) - SV* name - CODE: - PUSHMARK(sp) ; - perl_call_sv(name, G_DISCARD|G_NOARGS) ; + SaveSub1( sub { print "Hello there\n" } ) ; + CallSavedSub1() ; -As we are using an SV to call I<fred> the following can all be used +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 - CallSub("fred") ; - Callsub(\&fred) ; - $ref = \&fred ; - CallSub($ref) ; - CallSub( sub { print "Hello there\n" } ) ; + Can't use an undefined value as a subroutine reference at ... -As you can see, I<perl_call_sv> gives you greater flexibility in how you -can specify the Perl sub. +for each of the C<CallSavedSub1> lines. -=head2 Example 8: Using perl_call_argv +Similarly, with this code -Here is a Perl sub which prints whatever parameters are passed to it. + $ref = \&fred ; + SaveSub1($ref) ; + $ref = 47 ; + CallSavedSub1() ; - sub PrintList - { - my(@list) = @_ ; +you can expect one of these messages (which you actually get is dependant on +the version of Perl you are using) - foreach (@list) { print "$_\n" } - } + Not a CODE reference at ... + Undefined subroutine &main::47 called ... -and here is an example of I<perl_call_argv> which will call I<PrintList>. +The variable C<$ref> may have referred to the subroutine C<fred> +whenever the call to C<SaveSub1> was made but by the time +C<CallSavedSub1> gets called it now holds the number C<47>. Since we +saved only a pointer to the original SV in C<SaveSub1>, any changes to +C<$ref> will be tracked by the pointer C<rememberSub>. This means that +whenever C<CallSavedSub1> gets called, it will attempt to execute the +code which is referenced by the SV* C<rememberSub>. In this case +though, it now refers to the integer C<47>, so expect Perl to complain +loudly. - call_PrintList - { - dSP ; - char * words[] = {"alpha", "beta", "gamma", "delta", NULL } ; +A similar but more subtle problem is illustrated with this code - perl_call_argv("PrintList", words, G_DISCARD) ; - } + $ref = \&fred ; + SaveSub1($ref) ; + $ref = \&joe ; + CallSavedSub1() ; -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. +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>. -=head2 Example 9: Using perl_call_method +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 -[This section is under construction] + static SV * keepSub = (SV*)NULL ; + + void + SaveSub2(name) + SV * name + CODE: + /* Take a copy of the callback */ + if (keepSub == (SV*)NULL) + /* First time, so create a new SV */ + keepSub = newSVsv(name) ; + else + /* Been here before, so overwrite */ + SvSetSV(keepSub, name) ; + + void + CallSavedSub2() + CODE: + PUSHMARK(sp) ; + perl_call_sv(keepSub, G_DISCARD|G_NOARGS) ; + +In order to avoid creating a new SV every time C<SaveSub2> is called, +the function first checks to see if it has been called before. If not, +then space for a new SV is allocated and the reference to the Perl +subroutine, C<name> is copied to the variable C<keepSub> in one +operation using C<newSVsv>. Thereafter, whenever C<SaveSub2> is called +the existing SV, C<keepSub>, is overwritten with the new value using +C<SvSetSV>. + +=head2 Using perl_call_argv + +Here is a Perl subroutine which prints whatever parameters are passed +to it. + + sub PrintList + { + my(@list) = @_ ; + + foreach (@list) { print "$_\n" } + } + +and here is an example of I<perl_call_argv> which will call +I<PrintList>. + + static char * words[] = {"alpha", "beta", "gamma", "delta", NULL} ; + + static void + call_PrintList() + { + dSP ; + + perl_call_argv("PrintList", G_DISCARD, words) ; + } + +Note that it is not necessary to call C<PUSHMARK> in this instance. +This is because I<perl_call_argv> will do it for you. + +=head2 Using perl_call_method Consider the following Perl code - { - package Mine ; + { + 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 just implements 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>, simply prints out the class +name and a version number. The virtual method, C<Display>, prints out a +single element of the array. Here is an all Perl example of using it. + + $a = new Mine ('red', 'green', 'blue') ; + $a->Display(1) ; + PrintID Mine; - sub new { bless [@_] } - sub Display { print $_[0][1], "\n" } - } +will print - $a = new Mine ('red', 'green', 'blue') ; - call_Display($a, 'Display') ; + 1: green + This is Class Mine version 1.0 -The method C<Display> just prints out the first element of the list. -Here is a XSUB implementation of I<call_Display>. +Calling a Perl method from C is fairly straightforward. The following +things are required - void - call_Display(ref, method) - SV * ref - char * method - CODE: - PUSHMARK(sp); - XPUSHs(ref); - PUTBACK; +=over 5 + +=item * + +a reference to the object for a virtual method or the name of the class +for a static method. + +=item * + +the name of the method. + +=item * + +any other parameters specific to the method. + +=back + +Here is a simple XSUB which illustrates the mechanics of calling both +the C<PrintID> and C<Display> methods from C. + + void + call_Method(ref, method, index) + SV * ref + char * method + int index + CODE: + PUSHMARK(sp); + XPUSHs(ref); + XPUSHs(sv_2mortal(newSViv(index))) ; + PUTBACK; + + perl_call_method(method, G_DISCARD) ; + + void + call_PrintID(class, method) + char * class + char * method + CODE: + PUSHMARK(sp); + XPUSHs(sv_2mortal(newSVpv(class, 0))) ; + PUTBACK; + + perl_call_method(method, G_DISCARD) ; + + +So the methods C<PrintID> and C<Display> can be invoked like this + + $a = new Mine ('red', 'green', 'blue') ; + call_Method($a, 'Display', 1) ; + call_PrintID('Mine', 'PrintID') ; + +The only thing to note is that in both the static and virtual methods, +the method name is not passed via the stack - it is used as the first +parameter to I<perl_call_method>. + +=head2 Using GIMME + +Here is a trivial XSUB which prints the context in which it is +currently executing. + + void + PrintContext() + CODE: + if (GIMME == G_SCALAR) + printf ("Context is Scalar\n") ; + else + printf ("Context is Array\n") ; + +and here is some Perl to test it + + $a = PrintContext ; + @a = PrintContext ; + +The output from that will be + + Context is Scalar + Context is Array + +=head2 Using Perl to dispose of temporaries + +In the examples given to date, any temporaries created in the callback +(i.e. parameters passed on the stack to the I<perl_call_*> function or +values returned via the stack) have been freed by one of these methods + +=over 5 + +=item * + +specifying the G_DISCARD flag with I<perl_call_*>. + +=item * + +explicitly disposed of using the C<ENTER>/C<SAVETMPS> - +C<FREETMPS>/C<LEAVE> pairing. + +=back + +There is another method which can be used, namely letting Perl do it +for you automatically whenever it regains control after the callback +has terminated. This is done by simply not using the + + ENTER ; + SAVETMPS ; + ... + FREETMPS ; + LEAVE ; + +sequence in the callback (and not, of course, specifying the G_DISCARD +flag). + +If you are going to use this method you have to be aware of a possible +memory leak which can arise under very specific circumstances. To +explain these circumstances you need to know a bit about the flow of +control between Perl and the callback routine. + +The examples given at the start of the document (an error handler and +an event driven program) are typical of the two main sorts of flow +control that you are likely to encounter with callbacks. There is a +very important distinction between them, so pay attention. + +In the first example, an error handler, the flow of control could be as +follows. You have created an interface to an external library. +Control can reach the external library like this + + perl --> XSUB --> external library + +Whilst control is in the library, an error condition occurs. You have +previously set up a Perl callback to handle this situation, so it will +get executed. Once the callback has finished, control will drop back to +Perl again. Here is what the flow of control will be like in that +situation + + perl --> XSUB --> external library + ... + error occurs + ... + external library --> perl_call --> perl + | + perl <-- XSUB <-- external library <-- perl_call <----+ + +After processing of the error using I<perl_call_*> is completed, +control reverts back to Perl more or less immediately. + +In the diagram, the further right you go the more deeply nested the +scope is. It is only when control is back with perl on the extreme +left of the diagram that you will have dropped back to the enclosing +scope and any temporaries you have left hanging around will be freed. + +In the second example, an event driven program, the flow of control +will be more like this + + perl --> XSUB --> event handler + ... + event handler --> perl_call --> perl + | + event handler <-- perl_call --<--+ + ... + event handler --> perl_call --> perl + | + event handler <-- perl_call --<--+ + ... + event handler --> perl_call --> perl + | + event handler <-- perl_call --<--+ + +In this case the flow of control can consist of only the repeated +sequence + + event handler --> perl_call --> perl + +for the 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 actually 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 explicitly dispose of +any temporaries you may have created. Mind you, if you are at all +uncertain about what to do, it doesn't do any harm to tidy up anyway. + + +=head2 Strategies for storing Callback Context Information + + +Potentially one of the trickiest problems to overcome when designing a +callback interface can be figuring out how to store the mapping between +the C callback function and the Perl equivalent. + +To help understand why this can be a real problem first consider how a +callback is set up in an all C environment. Typically a C API will +provide a function to register a callback. This will expect a pointer +to a function as one of its parameters. Below is a call to a +hypothetical function C<register_fatal> which registers the C function +to get called when a fatal error occurs. + + register_fatal(cb1) ; + +The single parameter C<cb1> is a pointer to a function, so you must +have defined C<cb1> in your code, say something like this + + static void + cb1() + { + printf ("Fatal Error\n") ; + exit(1) ; + } + +Now change that to call a Perl subroutine instead + + static SV * callback = (SV*)NULL; + + static void + cb1() + { + dSP ; + + PUSHMARK(sp) ; + + /* Call the Perl sub to process the callback */ + perl_call_sv(callback, G_DISCARD) ; + } + + + void + register_fatal(fn) + SV * fn + CODE: + /* Remember the Perl sub */ + if (callback == (SV*)NULL) + callback = newSVsv(fn) ; + else + SvSetSV(callback, fn) ; + + /* register the callback with the external library */ + register_fatal(cb1) ; + +where the Perl equivalent of C<register_fatal> and the callback it +registers, C<pcb1>, might look like this + + # Register the sub pcb1 + register_fatal(\&pcb1) ; + + sub pcb1 + { + die "I'm dying...\n" ; + } + +The mapping between the C callback and the Perl equivalent is stored in +the global variable C<callback>. + +This will be adequate if you ever need to have only 1 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 ; - perl_call_method(method, G_DISCARD) ; + void + asynch_read(fh, callback) + int fh + SV * callback + CODE: + /* If the hash doesn't already exist, create it */ + if (Mapping == (HV*)NULL) + Mapping = newHV() ; + + /* Save the fh -> callback mapping */ + hv_store(Mapping, (char*)&fh, sizeof(fh), newSVsv(callback), 0) ; + + /* Register with the C Library */ + asynch_read(fh, asynch_read_if) ; + +and C<asynch_read_if> could look like this + + static void + asynch_read_if(fh, buffer) + int fh ; + char * buffer ; + { + dSP ; + SV ** sv ; + + /* Get the callback associated with fh */ + sv = hv_fetch(Mapping, (char*)&fh , sizeof(fh), FALSE) ; + if (sv == (SV**)NULL) + croak("Internal error...\n") ; + + PUSHMARK(sp) ; + XPUSHs(sv_2mortal(newSViv(fh))) ; + XPUSHs(sv_2mortal(newSVpv(buffer, 0))) ; + PUTBACK ; + + /* Call the Perl sub */ + perl_call_sv(*sv, G_DISCARD) ; + } + +For completeness, here is C<asynch_close>. This shows how to remove +the entry from the hash C<Mapping>. + + void + asynch_close(fh) + int fh + CODE: + /* Remove the entry from the hash */ + (void) hv_delete(Mapping, (char*)&fh, sizeof(fh), G_DISCARD) ; + /* Now call the real asynch_close */ + asynch_close(fh) ; +So the Perl interface would look like this + + sub callback1 + { + my($handle, $buffer) = @_ ; + } + # Register the Perl callback + asynch_read($fh, \&callback1) ; -=head2 Strategies for storing Context Information + 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 ; + { + ... + } -[This section is under construction] +Without the file handle there is no straightforward way to map from the +C callback to the Perl subroutine. -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. +In this case a possible way around this problem is to pre-define a +series of C functions to act as the interface to Perl, thus + + #define MAX_CB 3 + #define NULL_HANDLE -1 + typedef void (*FnMap)() ; + + struct MapStruct { + FnMap Function ; + SV * PerlSub ; + int Handle ; + } ; + + static void fn1() ; + static void fn2() ; + static void fn3() ; + + static struct MapStruct Map [MAX_CB] = + { + { fn1, NULL, NULL_HANDLE }, + { fn2, NULL, NULL_HANDLE }, + { fn3, NULL, NULL_HANDLE } + } ; + + static void + Pcb(index, buffer) + int index ; + char * buffer ; + { + dSP ; + + PUSHMARK(sp) ; + XPUSHs(sv_2mortal(newSVpv(buffer, 0))) ; + PUTBACK ; + + /* Call the Perl sub */ + perl_call_sv(Map[index].PerlSub, G_DISCARD) ; + } + + static void + fn1(buffer) + char * buffer ; + { + Pcb(0, buffer) ; + } + + static void + fn2(buffer) + char * buffer ; + { + Pcb(1, buffer) ; + } + + static void + fn3(buffer) + char * buffer ; + { + Pcb(2, buffer) ; + } + + void + array_asynch_read(fh, callback) + int fh + SV * callback + CODE: + int index ; + int null_index = MAX_CB ; + + /* Find the same handle or an empty entry */ + for (index = 0 ; index < MAX_CB ; ++index) + { + if (Map[index].Handle == fh) + break ; + + if (Map[index].Handle == NULL_HANDLE) + null_index = index ; + } + + if (index == MAX_CB && null_index == MAX_CB) + croak ("Too many callback functions registered\n") ; + + if (index == MAX_CB) + index = null_index ; + + /* Save the file handle */ + Map[index].Handle = fh ; + + /* Remember the Perl sub */ + if (Map[index].PerlSub == (SV*)NULL) + Map[index].PerlSub = newSVsv(callback) ; + else + SvSetSV(Map[index].PerlSub, callback) ; + + asynch_read(fh, Map[index].Function) ; + + void + array_asynch_close(fh) + int fh + CODE: + int index ; + + /* Find the file handle */ + for (index = 0; index < MAX_CB ; ++ index) + if (Map[index].Handle == fh) + break ; + + if (index == MAX_CB) + croak ("could not close fh %d\n", fh) ; + + Map[index].Handle = NULL_HANDLE ; + SvREFCNT_dec(Map[index].PerlSub) ; + Map[index].PerlSub = (SV*)NULL ; + + asynch_close(fh) ; + +In this case the functions C<fn1>, C<fn2> and C<fn3> are used to +remember the Perl subroutine to be called. Each of the functions holds +a separate hard-wired index which is used in the function C<Pcb> to +access the C<Map> array and actually call the Perl subroutine. + +There are some obvious disadvantages with this technique. + +Firstly, the code is considerably more complex than with the previous +example. + +Secondly, there is a hard-wired limit (in this case 3) to the number of +callbacks that can exist simultaneously. The only way to increase the +limit is by modifying the code to add more functions and then +re-compiling. 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 -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. +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<perlapi> for a +full description of the C<ST> macro). + +Most of the time the C<POP*> macros should be adequate, the main +problem with them is that they force you to process the returned values +in sequence. This may not be the most suitable way to process the +values in some cases. What we want is to be able to access the stack in +a random order. The C<ST> macro as used when coding an XSUB is ideal +for this purpose. + +The code below is the example given in the section I<Returning a list +of values> recoded to use C<ST> instead of C<POP*>. + + static void + call_AddSubtract2(a, b) + int a ; + int b ; + { + dSP ; + I32 ax ; + int count ; + + ENTER ; + SAVETMPS; + + PUSHMARK(sp) ; + XPUSHs(sv_2mortal(newSViv(a))); + XPUSHs(sv_2mortal(newSViv(b))); + PUTBACK ; + + count = perl_call_pv("AddSubtract", G_ARRAY); + + SPAGAIN ; + sp -= count ; + ax = (sp - stack_base) + 1 ; + + if (count != 2) + croak("Big trouble\n") ; -The code below is example 4 recoded to + 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 - 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 =head1 SEE ALSO @@ -826,13 +1826,11 @@ L<perlapi>, L<perlguts>, L<perlembed> Paul Marquess <pmarquess@bfsec.bt.co.uk> -Special thanks to the following people who assisted in the creation of the -document. +Special thanks to the following people who assisted in the creation of +the document. -Jeff Okamoto, Tim Bunce. +Jeff Okamoto, Tim Bunce, Nick Gianniotis, Steve Kelem and Larry Wall. =head1 DATE -Version 0.4, 17th October 1994 - - +Version 1.1, 17th May 1995 diff --git a/pod/perlguts.pod b/pod/perlguts.pod index a08ac95340..886a096671 100644 --- a/pod/perlguts.pod +++ b/pod/perlguts.pod @@ -16,14 +16,15 @@ Perl has three typedefs that handle Perl's three main data types: AV Array Value HV Hash Value -Each typedef has specific routines that manipulate the various data type. +Each typedef has specific routines that manipulate the various data types. =head2 What is an "IV"? Perl uses a special typedef IV which is large enough to hold either an integer or a pointer. -Perl also uses a special typedef I32 which will always be a 32-bit integer. +Perl also uses two special typedefs, I32 and I16, which will always be at +least 32-bits and 16-bits long, respectively. =head2 Working with SV's @@ -47,8 +48,9 @@ To change the value of an *already-existing* scalar, there are five routines: void sv_setsv(SV*, SV*); Notice that you can choose to specify the length of the string to be -assigned by using C<sv_setpvn>, or allow Perl to calculate the length by -using C<sv_setpv>. Be warned, though, that C<sv_setpv> determines the +assigned by using C<sv_setpvn> or C<newSVpv>, or you may allow Perl to +calculate the length by using C<sv_setpv> or specifying 0 as the second +argument to C<newSVpv>. Be warned, though, that Perl will determine the string's length by using C<strlen>, which depends on the string terminating with a NUL character. @@ -95,6 +97,19 @@ the following macros: But note that these are valid only if C<SvPOK()> is true. +If you want to append something to the end of string stored in an C<SV*>, +you can use the following functions: + + void sv_catpv(SV*, char*); + void sv_catpvn(SV*, char*, int); + void sv_catsv(SV*, SV*); + +The first function calculates the length of the string to be appended by +using C<strlen>. In the second, you specify the length of the string +yourself. The third function extends the string stored in the first SV +with the string stored in the second SV. It also forces the second SV to +be interpreted as a string. + If you know the name of a scalar variable, you can get a pointer to its SV by using the following: @@ -102,7 +117,7 @@ by using the following: This returns NULL if the variable does not exist. -If you want to know if this variable (or any other SV) is actually defined, +If you want to know if this variable (or any other SV) is actually C<defined>, you can call: SvOK(SV*) @@ -132,11 +147,11 @@ all will be well. To free an SV that you've created, call C<SvREFCNT_dec(SV*)>. Normally this call is not necessary. See the section on B<MORTALITY>. -=head2 Private and Public Values +=head2 What's Really Stored in an SV? Recall that the usual method of determining the type of scalar you have is -to use C<Sv[INP]OK> macros. Since a scalar can be both a number and a string, -usually these macros will always return TRUE and calling the C<Sv[INP]V> +to use C<Sv*OK> macros. Since a scalar can be both a number and a string, +usually these macros will always return TRUE and calling the C<Sv*V> macros will do the appropriate conversion of string to integer/double or integer/double to string. @@ -148,9 +163,9 @@ pointer in an SV, you can use the following three macros instead: SvPOKp(SV*) These will tell you if you truly have an integer, double, or string pointer -stored in your SV. +stored in your SV. The "p" stands for private. -In general, though, it's best to just use the C<Sv[INP]V> macros. +In general, though, it's best to just use the C<Sv*V> macros. =head2 Working with AV's @@ -163,7 +178,8 @@ The second method both creates the AV and initially populates it with SV's: AV* av_make(I32 num, SV **ptr); -The second argument points to an array containing C<num> C<SV*>'s. +The second argument points to an array containing C<num> C<SV*>'s. Once the +AV has been created, the SV's can be destroyed, if so desired. Once the AV has been created, the following operations are possible on AV's: @@ -179,14 +195,16 @@ to these new elements. Here are some other functions: - I32 av_len(AV*); /* Returns length of array */ + I32 av_len(AV*); /* Returns highest index value in array */ SV** av_fetch(AV*, I32 key, I32 lval); - /* Fetches value at key offset, but it seems to - set the value to lval if lval is non-zero */ + /* Fetches value at key offset, but it stores an undef value + at the offset if lval is non-zero */ SV** av_store(AV*, I32 key, SV* val); /* Stores val at offset key */ +Take note that these two functions return C<SV**>'s, not C<SV*>'s. + void av_clear(AV*); /* Clear out all elements, but leave the array */ void av_undef(AV*); @@ -224,7 +242,7 @@ value is not NULL before dereferencing it. These two functions check if a hash table entry exists, and deletes it. bool hv_exists(HV*, char* key, U32 klen); - SV* hv_delete(HV*, char* key, U32 klen); + SV* hv_delete(HV*, char* key, U32 klen, I32 flags); And more miscellaneous functions: @@ -233,6 +251,12 @@ And more miscellaneous functions: void hv_undef(HV*); /* Undefines the hash table */ +Perl keeps the actual data in linked list of structures with a typedef of HE. +These contain the actual key and value pointers (plus extra administrative +overhead). The key is a string pointer; the value is an C<SV*>. However, +once you have an C<HE*>, to get the actual key and value, use the routines +specified below. + I32 hv_iterinit(HV*); /* Prepares starting point to traverse hash table */ HE* hv_iternext(HV*); @@ -244,6 +268,11 @@ And more miscellaneous functions: SV* hv_iterval(HV*, HE* entry); /* Return a SV pointer to the value of the HE structure */ + SV* hv_iternextsv(HV*, char** key, I32* retlen); + /* This convenience routine combines hv_iternext, + hv_iterkey, and hv_iterval. The key and retlen + arguments are return values for the key and its + length. The value is returned in the SV* argument */ If you know the name of a hash variable, you can get a pointer to its HV by using the following: @@ -260,30 +289,69 @@ The hash algorithm, for those who are interested, is: while (i--) hash = hash * 33 + *s++; +=head1 Creating New Variables + +To create a new Perl variable, which can be accessed from your Perl script, +use the following routines, depending on the variable type. + + SV* perl_get_sv("varname", TRUE); + AV* perl_get_av("varname", TRUE); + HV* perl_get_hv("varname", TRUE); + +Notice the use of TRUE as the second parameter. The new variable can now +be set, using the routines appropriate to the data type. + +There are additional bits that may be OR'ed with the TRUE argument to enable +certain extra features. Those bits are: + + 0x02 Marks the variable as multiply defined, thus preventing the + "Indentifier <varname> used only once: possible typo" warning. + 0x04 Issues a "Had to create <varname> unexpectedly" warning if + the variable didn't actually exist. This is useful if + you expected the variable to already exist and want to propagate + this warning back to the user. + +If the C<varname> argument does not contain a package specifier, it is +created in the current package. + =head2 References -References are a special type of scalar that point to other scalar types -(including references). To treat an AV or HV as a scalar, it is simply -a matter of casting an AV or HV to an SV. +References are a special type of scalar that point to other data types +(including references). To create a reference, use the following command: - SV* newRV((SV*) pointer); + SV* newRV((SV*) thing); -Once you have a reference, you can use the following macro with a cast to -the appropriate typedef (SV, AV, HV): +The C<thing> argument can be any of an C<SV*>, C<AV*>, or C<HV*>. Once +you have a reference, you can use the following macro to dereference the +reference: SvRV(SV*) then call the appropriate routines, casting the returned C<SV*> to either an -C<AV*> or C<HV*>. +C<AV*> or C<HV*>, if required. -To determine, after dereferencing a reference, if you still have a reference, -you can use the following macro: +To determine if an SV is a reference, you can use the following macro: SvROK(SV*) -=head1 XSUB'S and the Argument Stack +To actually discover what the reference refers to, you must use the following +macro and then check the value returned. + + SvTYPE(SvRV(SV*)) + +The most useful types that will be returned are: + + SVt_IV Scalar + SVt_NV Scalar + SVt_PV Scalar + SVt_PVAV Array + SVt_PVHV Hash + SVt_PVCV Code + SVt_PVMG Blessed Scalar + +=head1 XSUB's and the Argument Stack The XSUB mechanism is a simple way for Perl programs to access C subroutines. An XSUB routine will have a stack that contains the arguments from the Perl @@ -331,12 +399,16 @@ to use the macros: These macros automatically adjust the stack for you, if needed. +For more information, consult L<perlapi>. + =head1 Mortality In Perl, values are normally "immortal" -- that is, they are not freed unless explicitly done so (via the Perl C<undef> call or other routines in Perl itself). +Add cruft about reference counts. + In the above example with C<tzname>, we needed to create two new SV's to push onto the argument stack, that being the two strings. However, we don't want these new SV's to stick around forever because they will eventually be @@ -361,27 +433,27 @@ The mortal routines are not just for SV's -- AV's and HV's can be made mortal by passing their address (and casting them to C<SV*>) to the C<sv_2mortal> or C<sv_mortalcopy> routines. -=head1 Creating New Variables +From Ilya: +Beware that the sv_2mortal() call is eventually equivalent to +svREFCNT_dec(). A value can happily be mortal in two different contexts, +and it will be svREFCNT_dec()ed twice, once on exit from these +contexts. It can also be mortal twice in the same context. This means +that you should be very careful to make a value mortal exactly as many +times as it is needed. The value that go to the Perl stack I<should> +be mortal. -To create a new Perl variable, which can be accessed from your Perl script, -use the following routines, depending on the variable type. - - SV* perl_get_sv("varname", TRUE); - AV* perl_get_av("varname", TRUE); - HV* perl_get_hv("varname", TRUE); - -Notice the use of TRUE as the second parameter. The new variable can now -be set, using the routines appropriate to the data type. +You should be careful about creating mortal variables. It is possible for +strange things to happen should you make the same value mortal within +multiple contexts. =head1 Stashes and Objects A stash is a hash table (associative array) that contains all of the different objects that are contained within a package. Each key of the -hash table is a symbol name (shared by all the different types of -objects that have the same name), and each value in the hash table is -called a GV (for Glob Value). The GV in turn contains references to -the various objects of that name, including (but not limited to) the -following: +stash is a symbol name (shared by all the different types of objects +that have the same name), and each value in the hash table is called a +GV (for Glob Value). This GV in turn contains references to the various +objects of that name, including (but not limited to) the following: Scalar Value Array Value @@ -391,21 +463,25 @@ following: Format Subroutine -Perl stores various stashes in a GV structure (for global variable) but -represents them with an HV structure. +Perl stores various stashes in a separate GV structure (for global +variable) but represents them with an HV structure. The keys in this +larger GV are the various package names; the values are the C<GV*>'s +which are stashes. It may help to think of a stash purely as an HV, +and that the term "GV" means the global variable hash. -To get the HV pointer for a particular package, use the function: +To get the stash pointer for a particular package, use the function: HV* gv_stashpv(char* name, I32 create) HV* gv_stashsv(SV*, I32 create) The first function takes a literal string, the second uses the string stored -in the SV. +in the SV. Remember that a stash is just a hash table, so you get back an +C<HV*>. The name that C<gv_stash*v> wants is the name of the package whose symbol table you want. The default package is called C<main>. If you have multiply nested -packages, it is legal to pass their names to C<gv_stash*v>, separated by -C<::> as in the Perl language itself. +packages, pass their names to C<gv_stash*v>, separated by C<::> as in the Perl +language itself. Alternately, if you have an SV that is a blessed reference, you can find out the stash pointer by using: @@ -425,9 +501,148 @@ where the first argument, an C<SV*>, must be a reference, and the second argument is a stash. The returned C<SV*> can now be used in the same way as any other SV. +For more information on references and blessings, consult L<perlref>. + =head1 Magic -[This section under construction] +[This section still under construction. Ignore everything here. Post no +bills. Everything not permitted is forbidden.] + +# Version 6, 1995/1/27 + +Any SV may be magical, that is, it has special features that a normal +SV does not have. These features are stored in the SV structure in a +linked list of C<struct magic>'s, typedef'ed to C<MAGIC>. + + struct magic { + MAGIC* mg_moremagic; + MGVTBL* mg_virtual; + U16 mg_private; + char mg_type; + U8 mg_flags; + SV* mg_obj; + char* mg_ptr; + I32 mg_len; + }; + +Note this is current as of patchlevel 0, and could change at any time. + +=head2 Assigning Magic + +Perl adds magic to an SV using the sv_magic function: + + void sv_magic(SV* sv, SV* obj, int how, char* name, I32 namlen); + +The C<sv> argument is a pointer to the SV that is to acquire a new magical +feature. + +If C<sv> is not already magical, Perl uses the C<SvUPGRADE> macro to +set the C<SVt_PVMG> flag for the C<sv>. Perl then continues by adding +it to the beginning of the linked list of magical features. Any prior +entry of the same type of magic is deleted. Note that this can be +overriden, and multiple instances of the same type of magic can be +associated with an SV. + +The C<name> and C<namlem> arguments are used to associate a string with +the magic, typically the name of a variable. C<namlem> is stored in the +C<mg_len> field and if C<name> is non-null and C<namlem> >= 0 a malloc'd +copy of the name is stored in C<mg_ptr> field. + +The sv_magic function uses C<how> to determine which, if any, predefined +"Magic Virtual Table" should be assigned to the C<mg_virtual> field. +See the "Magic Virtual Table" section below. + +The C<obj> argument is stored in the C<mg_obj> field of the C<MAGIC> +structure. If it is not the same as the C<sv> argument, the reference +count of the C<obj> object is incremented. If it is the same, or if +the C<how> argument is "#", or if it is a null pointer, then C<obj> is +merely stored, without the reference count being incremented. + +=head2 Magic Virtual Tables + +The C<mg_virtual> field in the C<MAGIC> structure is a pointer to a +C<MGVTBL>, which is a structure of function pointers and stands for +"Magic Virtual Table" to handle the various operations that might be +applied to that variable. + +The C<MGVTBL> has five pointers to the following routine types: + + int (*svt_get)(SV* sv, MAGIC* mg); + int (*svt_set)(SV* sv, MAGIC* mg); + U32 (*svt_len)(SV* sv, MAGIC* mg); + int (*svt_clear)(SV* sv, MAGIC* mg); + int (*svt_free)(SV* sv, MAGIC* mg); + +This MGVTBL structure is set at compile-time in C<perl.h> and there are +currently 19 types (or 21 with overloading turned on). These different +structures contain pointers to various routines that perform additional +actions depending on which function is being called. + + Function pointer Action taken + ---------------- ------------ + svt_get Do something after the value of the SV is retrieved. + svt_set Do something after the SV is assigned a value. + svt_len Report on the SV's length. + svt_clear Clear something the SV represents. + svt_free Free any extra storage associated with the SV. + +For instance, the MGVTBL structure called C<vtbl_sv> (which corresponds +to an C<mg_type> of '\0') contains: + + { magic_get, magic_set, magic_len, 0, 0 } + +Thus, when an SV is determined to be magical and of type '\0', if a get +operation is being performed, the routine C<magic_get> is called. All +the various routines for the various magical types begin with C<magic_>. + +The current kinds of Magic Virtual Tables are: + + mg_type MGVTBL Type of magicalness + ------- ------ ------------------- + \0 vtbl_sv Regexp??? + A vtbl_amagic Operator Overloading + a vtbl_amagicelem Operator Overloading + c 0 Used in Operator Overloading + B vtbl_bm Boyer-Moore??? + E vtbl_env %ENV hash + e vtbl_envelem %ENV hash element + g vtbl_mglob Regexp /g flag??? + I vtbl_isa @ISA array + i vtbl_isaelem @ISA array element + L 0 (but sets RMAGICAL) Perl Module/Debugger??? + l vtbl_dbline Debugger? + P vtbl_pack Tied Array or Hash + p vtbl_packelem Tied Array or Hash element + q vtbl_packelem Tied Scalar or Handle + S vtbl_sig Signal Hash + s vtbl_sigelem Signal Hash element + t vtbl_taint Taintedness + U vtbl_uvar ??? + v vtbl_vec Vector + x vtbl_substr Substring??? + * vtbl_glob GV??? + # vtbl_arylen Array Length + . vtbl_pos $. scalar variable + ~ Reserved for extensions, but multiple extensions may clash + +When an upper-case and lower-case letter both exist in the table, then the +upper-case letter is used to represent some kind of composite type (a list +or a hash), and the lower-case letter is used to represent an element of +that composite type. + +=head2 Finding Magic + + MAGIC* mg_find(SV*, int type); /* Finds the magic pointer of that type */ + +This routine returns a pointer to the C<MAGIC> structure stored in the SV. +If the SV does not have that magical feature, C<NULL> is returned. Also, +if the SV is not of type SVt_PVMG, Perl may core-dump. + + int mg_copy(SV* sv, SV* nsv, char* key, STRLEN klen); + +This routine checks to see what types of magic C<sv> has. If the mg_type +field is an upper-case letter, then the mg_obj is copied to C<nsv>, but +the mg_type field is changed to be the lower-case letter. =head1 Double-Typed SV's @@ -437,7 +652,7 @@ actual scalar data from the stored type into the requested type. Some scalar variables contain more than one type of scalar data. For example, the variable C<$!> contains either the numeric value of C<errno> -or its string equivalent from C<sys_errlist[]>. +or its string equivalent from either C<strerror> or C<sys_errlist[]>. To force multiple data values into an SV, you must do two things: use the C<sv_set*v> routines to add the additional scalar type, then set a flag @@ -479,16 +694,19 @@ within a C program. These four are: I32 perl_call_method(char*, I32); I32 perl_call_argv(char*, I32, register char**); -The routine most often used should be C<perl_call_sv>. The C<SV*> argument -contains either the name of the Perl subroutine to be called, or a reference -to the subroutine. The second argument tells the appropriate routine what, -if any, variables are being returned by the Perl subroutine. +The routine most often used is C<perl_call_sv>. The C<SV*> argument +contains either the name of the Perl subroutine to be called, or a +reference to the subroutine. The second argument consists of flags +that control the context in which the subroutine is called, whether +or not the subroutine is being passed arguments, how errors should be +trapped, and how to treat return values. All four routines return the number of arguments that the subroutine returned on the Perl stack. -When using these four routines, the programmer must manipulate the Perl stack. -These include the following macros and functions: +When using any of these routines (except C<perl_call_argv>), the programmer +must manipulate the Perl stack. These include the following macros and +functions: dSP PUSHMARK() @@ -504,18 +722,58 @@ For more information, consult L<perlcall>. =head1 Memory Allocation -[This section under construction] +It is strongly suggested that you use the version of malloc that is distributed +with Perl. It keeps pools of various sizes of unallocated memory in order to +more quickly satisfy allocation requests. +However, on some platforms, it may cause spurious malloc or free errors. + + New(x, pointer, number, type); + Newc(x, pointer, number, type, cast); + Newz(x, pointer, number, type); + +These three macros are used to initially allocate memory. The first argument +C<x> was a "magic cookie" that was used to keep track of who called the macro, +to help when debugging memory problems. However, the current code makes no +use of this feature (Larry has switched to using a run-time memory checker), +so this argument can be any number. + +The second argument C<pointer> will point to the newly allocated memory. +The third and fourth arguments C<number> and C<type> specify how many of +the specified type of data structure should be allocated. The argument +C<type> is passed to C<sizeof>. The final argument to C<Newc>, C<cast>, +should be used if the C<pointer> argument is different from the C<type> +argument. + +Unlike the C<New> and C<Newc> macros, the C<Newz> macro calls C<memzero> +to zero out all the newly allocated memory. + + Renew(pointer, number, type); + Renewc(pointer, number, type, cast); + Safefree(pointer) + +These three macros are used to change a memory buffer size or to free a +piece of memory no longer needed. The arguments to C<Renew> and C<Renewc> +match those of C<New> and C<Newc> with the exception of not needing the +"magic cookie" argument. + + Move(source, dest, number, type); + Copy(source, dest, number, type); + Zero(dest, number, type); + +These three macros are used to move, copy, or zero out previously allocated +memory. The C<source> and C<dest> arguments point to the source and +destination starting points. Perl will move, copy, or zero out C<number> +instances of the size of the C<type> data structure (using the C<sizeof> +function). =head1 AUTHOR Jeff Okamoto <okamoto@corp.hp.com> With lots of help and suggestions from Dean Roehrich, Malcolm Beattie, -Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, and Neil -Bowers. +Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil +Bowers, Matthew Green, Tim Bunce, and Spider Boardman. =head1 DATE -Version 12: 1994/10/16 - - +Version 19: 1995/4/26 |