X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlcall.pod;h=2b837808a19ad9c398e4321e919dbfb8afdc72d3;hb=2b5ab1e742ea1b1374dcea7f6f90ef5c5cf29914;hp=f90e09f2384ba682fdc48143ebdffa57f6751559;hpb=137443ea0a858c43f5a720730cac6209a7d41948;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlcall.pod b/pod/perlcall.pod index f90e09f..2b83780 100644 --- a/pod/perlcall.pod +++ b/pod/perlcall.pod @@ -72,7 +72,7 @@ Each of the functions will now be discussed in turn. =over 5 -=item B +=item perl_call_sv I takes two parameters, the first, C, is an SV*. This allows you to specify the Perl subroutine to be called either as a @@ -80,7 +80,7 @@ C string (which has first been converted to an SV) or a reference to a subroutine. The section, I, shows how you can make use of I. -=item B +=item perl_call_pv The function, I, is similar to I except it expects its first parameter to be a C char* which identifies the Perl @@ -88,7 +88,7 @@ subroutine you want to call, e.g., C. 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 +=item perl_call_method The function I is used to call a method from a Perl class. The parameter C corresponds to the name of the method @@ -99,7 +99,7 @@ object (for a virtual method). See L for more information on static and virtual methods and L for an example of using I. -=item B +=item perl_call_argv I calls the Perl subroutine specified by the C string stored in the C parameter. It also takes the usual C @@ -279,8 +279,8 @@ belongs to C. It is possible for the Perl subroutine you are calling to terminate abnormally, e.g., by calling I 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 +existing. By default, when either of these events occurs, the +process will terminate immediately. If you want to trap this type of event, specify the G_EVAL flag. It will put an I around the subroutine call. @@ -404,7 +404,7 @@ via this XSUB void Call_fred() CODE: - PUSHMARK(sp) ; + PUSHMARK(SP) ; perl_call_pv("fred", G_DISCARD|G_NOARGS) ; fprintf(stderr, "back in Call_fred\n") ; @@ -421,7 +421,7 @@ higher, or use the G_EVAL flag with I as shown below void Call_fred() CODE: - PUSHMARK(sp) ; + PUSHMARK(SP) ; perl_call_pv("fred", G_EVAL|G_DISCARD|G_NOARGS) ; fprintf(stderr, "back in Call_fred\n") ; @@ -462,7 +462,7 @@ and here is a C function to call it { dSP ; - PUSHMARK(sp) ; + PUSHMARK(SP) ; perl_call_pv("PrintUID", G_DISCARD|G_NOARGS) ; } @@ -474,7 +474,7 @@ A few points to note about this example. =item 1. -Ignore C and C for now. They will be discussed in +Ignore C and C for now. They will be discussed in the next example. =item 2. @@ -526,12 +526,18 @@ The C function required to call I would look like this. { dSP ; - PUSHMARK(sp) ; + ENTER ; + SAVETMPS ; + + PUSHMARK(SP) ; XPUSHs(sv_2mortal(newSVpv(a, 0))); XPUSHs(sv_2mortal(newSViv(b))); PUTBACK ; perl_call_pv("LeftString", G_DISCARD); + + FREETMPS ; + LEAVE ; } Here are a few notes on the C function I. @@ -542,8 +548,9 @@ Here are a few notes on the C function I. Parameters are passed to the Perl subroutine using the Perl stack. This is the purpose of the code beginning with the line C and -ending with the line C. - +ending with the line C. The C declares a local copy +of the stack pointer. This local copy should B be accessed +as C. =item 2. @@ -597,6 +604,36 @@ on how the XPUSH macros work. =item 6. +Because we created temporary values (by means of sv_2mortal() calls) +we will have to tidy up the Perl stack and dispose of mortal SVs. + +This is the purpose of + + ENTER ; + SAVETMPS ; + +at the start of the function, and + + FREETMPS ; + LEAVE ; + +at the end. The C/C 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/C pair will get rid of any values returned by +the Perl subroutine (see next example), plus it will also dump the +mortal SVs we have created. Having C/C 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 for details of +an alternative to using these macros. + +=item 7. + Finally, I can now be called via the I function. @@ -630,7 +667,7 @@ function required to call it is now a bit more complex. ENTER ; SAVETMPS; - PUSHMARK(sp) ; + PUSHMARK(SP) ; XPUSHs(sv_2mortal(newSViv(a))); XPUSHs(sv_2mortal(newSViv(b))); PUTBACK ; @@ -659,40 +696,8 @@ The only flag specified this time was G_SCALAR. That means the C<@_> array will be created and that the value returned by I will still exist after the call to I. - - =item 2. -Because we are interested in what is returned from I we cannot -specify G_DISCARD. This means that we will have to tidy up the Perl -stack and dispose of any temporary values ourselves. This is the -purpose of - - ENTER ; - SAVETMPS ; - -at the start of the function, and - - FREETMPS ; - LEAVE ; - -at the end. The C/C 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/C pair will get rid of any values returned by -the Perl subroutine, plus it will also dump the mortal SVs we have -created. Having C/C 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 for details of -an alternative to using these macros. - -=item 3. - The purpose of the macro C is to refresh the local copy of the stack pointer. This is necessary because it is possible that the memory allocated to the Perl stack has been reallocated whilst in the @@ -702,7 +707,7 @@ If you are making use of the Perl stack pointer in your code you must always refresh the local copy using SPAGAIN whenever you make use of the I functions or any other Perl internal function. -=item 4. +=item 3. Although only a single value was expected to be returned from I, it is still good practice to check the return code from I @@ -714,7 +719,7 @@ 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 don't want to happen ever. -=item 5. +=item 4. The C macro is used here to pop the return value from the stack. In this case we wanted an integer, so C was used. @@ -729,7 +734,7 @@ they return. POPi integer POPl long -=item 6. +=item 5. The final C is used to leave the Perl stack in a consistent state before exiting the function. This is necessary because when we @@ -766,7 +771,7 @@ and this is the C function ENTER ; SAVETMPS; - PUSHMARK(sp) ; + PUSHMARK(SP) ; XPUSHs(sv_2mortal(newSViv(a))); XPUSHs(sv_2mortal(newSViv(b))); PUTBACK ; @@ -829,7 +834,7 @@ context, like this ENTER ; SAVETMPS; - PUSHMARK(sp) ; + PUSHMARK(SP) ; XPUSHs(sv_2mortal(newSViv(a))); XPUSHs(sv_2mortal(newSViv(b))); PUTBACK ; @@ -897,7 +902,7 @@ and here is a C function to call it. sva = sv_2mortal(newSViv(a)) ; svb = sv_2mortal(newSViv(b)) ; - PUSHMARK(sp) ; + PUSHMARK(SP) ; XPUSHs(sva); XPUSHs(svb); PUTBACK ; @@ -954,7 +959,7 @@ and some C to call it ENTER ; SAVETMPS; - PUSHMARK(sp) ; + PUSHMARK(SP) ; XPUSHs(sv_2mortal(newSViv(a))); XPUSHs(sv_2mortal(newSViv(b))); PUTBACK ; @@ -964,9 +969,10 @@ and some C to call it SPAGAIN ; /* Check the eval first */ - if (SvTRUE(GvSV(errgv))) + if (SvTRUE(ERRSV)) { - printf ("Uh oh - %s\n", SvPV(GvSV(errgv), na)) ; + STRLEN n_a; + printf ("Uh oh - %s\n", SvPV(ERRSV, n_a)) ; POPs ; } else @@ -1006,9 +1012,10 @@ I. The code - if (SvTRUE(GvSV(errgv))) + if (SvTRUE(ERRSV)) { - printf ("Uh oh - %s\n", SvPV(GvSV(errgv), na)) ; + STRLEN n_a; + printf ("Uh oh - %s\n", SvPV(ERRSV, n_a)) ; POPs ; } @@ -1016,14 +1023,14 @@ is the direct equivalent of this bit of Perl print "Uh oh - $@\n" if $@ ; -C is a perl global of type C that points to the -symbol table entry containing the error. C therefore +C is a perl global of type C that points to the +symbol table entry containing the error. C therefore refers to the C equivalent of C<$@>. =item 3. Note that the stack is popped using C in the block where -C is true. This is necessary because whenever a +C is true. This is necessary because whenever a I function invoked with G_EVAL|G_SCALAR returns an error, the top of the stack holds the value I. Because we want the program to continue after detecting this error, it is essential that @@ -1087,7 +1094,7 @@ Here is a snippet of XSUB which defines I. CallSubPV(name) char * name CODE: - PUSHMARK(sp) ; + PUSHMARK(SP) ; perl_call_pv(name, G_DISCARD|G_NOARGS) ; That is fine as far as it goes. The thing is, the Perl subroutine @@ -1103,7 +1110,7 @@ I instead of I. CallSubSV(name) SV * name CODE: - PUSHMARK(sp) ; + PUSHMARK(SP) ; perl_call_sv(name, G_DISCARD|G_NOARGS) ; Because we are using an SV to call I the following can all be used @@ -1133,7 +1140,7 @@ pointer to the SV. Say the code above had been like this void CallSavedSub1() CODE: - PUSHMARK(sp) ; + PUSHMARK(SP) ; perl_call_sv(rememberSub, G_DISCARD|G_NOARGS) ; The reason this is wrong is that by the time you come to use the @@ -1209,7 +1216,7 @@ SV. The code below shows C modified to do that void CallSavedSub2() CODE: - PUSHMARK(sp) ; + PUSHMARK(SP) ; perl_call_sv(keepSub, G_DISCARD|G_NOARGS) ; To avoid creating a new SV every time C is called, @@ -1318,7 +1325,7 @@ the C and C methods from C. char * method int index CODE: - PUSHMARK(sp); + PUSHMARK(SP); XPUSHs(ref); XPUSHs(sv_2mortal(newSViv(index))) ; PUTBACK; @@ -1330,7 +1337,7 @@ the C and C methods from C. char * class char * method CODE: - PUSHMARK(sp); + PUSHMARK(SP); XPUSHs(sv_2mortal(newSVpv(class, 0))) ; PUTBACK; @@ -1522,7 +1529,7 @@ Now change that to call a Perl subroutine instead { dSP ; - PUSHMARK(sp) ; + PUSHMARK(SP) ; /* Call the Perl sub to process the callback */ perl_call_sv(callback, G_DISCARD) ; @@ -1625,7 +1632,7 @@ and C could look like this if (sv == (SV**)NULL) croak("Internal error...\n") ; - PUSHMARK(sp) ; + PUSHMARK(SP) ; XPUSHs(sv_2mortal(newSViv(fh))) ; XPUSHs(sv_2mortal(newSVpv(buffer, 0))) ; PUTBACK ; @@ -1709,7 +1716,7 @@ series of C functions to act as the interface to Perl, thus { dSP ; - PUSHMARK(sp) ; + PUSHMARK(SP) ; XPUSHs(sv_2mortal(newSVpv(buffer, 0))) ; PUTBACK ; @@ -1863,7 +1870,7 @@ of values> recoded to use C instead of C. ENTER ; SAVETMPS; - PUSHMARK(sp) ; + PUSHMARK(SP) ; XPUSHs(sv_2mortal(newSViv(a))); XPUSHs(sv_2mortal(newSViv(b))); PUTBACK ; @@ -1871,8 +1878,8 @@ of values> recoded to use C instead of C. count = perl_call_pv("AddSubtract", G_ARRAY); SPAGAIN ; - sp -= count ; - ax = (sp - stack_base) + 1 ; + SP -= count ; + ax = (SP - PL_stack_base) + 1 ; if (count != 2) croak("Big trouble\n") ; @@ -1901,8 +1908,8 @@ you. The code SPAGAIN ; - sp -= count ; - ax = (sp - stack_base) + 1 ; + SP -= count ; + ax = (SP - PL_stack_base) + 1 ; sets the stack up so that we can use the C macro. @@ -1917,9 +1924,9 @@ refers to the last. =head2 Creating and calling an anonymous subroutine in C -As we've already shown, L can be used to invoke an -anonymous subroutine. However, our example showed how Perl script -invoking an XSUB to preform this operation. Let's see how it can be +As we've already shown, C can be used to invoke an +anonymous subroutine. However, our example showed a Perl script +invoking an XSUB to perform this operation. Let's see how it can be done inside our C code: ... @@ -1930,8 +1937,9 @@ done inside our C code: perl_call_sv(cvrv, G_VOID|G_NOARGS); -L is used to compile the anonymous subroutine, which -will be the return value as well. Once this code reference is in hand, it +C is used to compile the anonymous subroutine, which +will be the return value as well (read more about C in +L). Once this code reference is in hand, it can be mixed in with all the previous examples we've shown. =head1 SEE ALSO