X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlcall.pod;h=7c94d377c7df97986d0afac93d35d0a08a00e9e1;hb=9cde0e7fb9816f759feaabc0f640403a7cdbc5c6;hp=37916ae6d87a0851e216b5045c2d75ac365a066c;hpb=7b8d334a971230040a212bc5038097b3f600a094;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlcall.pod b/pod/perlcall.pod index 37916ae..7c94d37 100644 --- a/pod/perlcall.pod +++ b/pod/perlcall.pod @@ -526,12 +526,18 @@ The C function required to call I would look like this. { dSP ; + 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. @@ -598,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. @@ -660,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 @@ -703,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 @@ -715,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. @@ -730,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 @@ -965,9 +969,9 @@ 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)) ; + printf ("Uh oh - %s\n", SvPV(ERRSV, PL_na)) ; POPs ; } else @@ -1007,9 +1011,9 @@ I. The code - if (SvTRUE(GvSV(errgv))) + if (SvTRUE(ERRSV)) { - printf ("Uh oh - %s\n", SvPV(GvSV(errgv), na)) ; + printf ("Uh oh - %s\n", SvPV(ERRSV, PL_na)) ; POPs ; } @@ -1017,14 +1021,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 @@ -1873,7 +1877,7 @@ of values> recoded to use C instead of C. SPAGAIN ; SP -= count ; - ax = (SP - stack_base) + 1 ; + ax = (SP - PL_stack_base) + 1 ; if (count != 2) croak("Big trouble\n") ; @@ -1903,7 +1907,7 @@ The code SPAGAIN ; SP -= count ; - ax = (SP - stack_base) + 1 ; + ax = (SP - PL_stack_base) + 1 ; sets the stack up so that we can use the C macro.