=over 5
-=item B<perl_call_sv>
+=item 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
subroutine. The section, I<Using perl_call_sv>, shows how you can make
use of I<perl_call_sv>.
-=item B<perl_call_pv>
+=item 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 is in another package, just include the
package name in the string, e.g., C<"pkg::fred">.
-=item B<perl_call_method>
+=item 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
static and virtual methods and L<Using perl_call_method> for an example
of using I<perl_call_method>.
-=item B<perl_call_argv>
+=item 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>
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
+existing. By default, when either of these events occurs, the
+process will terminate immediately. If you want to trap this
type of event, specify the G_EVAL flag. It will put an I<eval { }>
around the subroutine call.
void
Call_fred()
CODE:
- PUSHMARK(sp) ;
+ PUSHMARK(SP) ;
perl_call_pv("fred", G_DISCARD|G_NOARGS) ;
fprintf(stderr, "back in Call_fred\n") ;
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") ;
{
dSP ;
- PUSHMARK(sp) ;
+ PUSHMARK(SP) ;
perl_call_pv("PrintUID", G_DISCARD|G_NOARGS) ;
}
=item 1.
-Ignore C<dSP> and C<PUSHMARK(sp)> for now. They will be discussed in
+Ignore C<dSP> and C<PUSHMARK(SP)> for now. They will be discussed in
the next example.
=item 2.
{
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<call_LeftString>.
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>.
-
+ending with the line C<PUTBACK>. The C<dSP> declares a local copy
+of the stack pointer. This local copy should B<always> be accessed
+as C<SP>.
=item 2.
=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<ENTER>/C<SAVETMPS> pair creates a boundary for any
+temporaries we create. This means that the temporaries we get rid of
+will be limited to those which were created after these calls.
+
+The C<FREETMPS>/C<LEAVE> pair will get rid of any values returned by
+the Perl subroutine (see next example), plus it will also dump the
+mortal SVs we have created. Having C<ENTER>/C<SAVETMPS> at the
+beginning of the code makes sure that no other mortals are destroyed.
+
+Think of these macros as working a bit like using C<{> and C<}> in Perl
+to limit the scope of local variables.
+
+See the section I<Using Perl to dispose of temporaries> for details of
+an alternative to using these macros.
+
+=item 7.
+
Finally, I<LeftString> can now be called via the I<perl_call_pv>
function.
ENTER ;
SAVETMPS;
- PUSHMARK(sp) ;
+ PUSHMARK(SP) ;
XPUSHs(sv_2mortal(newSViv(a)));
XPUSHs(sv_2mortal(newSViv(b)));
PUTBACK ;
array will be created and that the value returned by I<Adder> will
still exist after the call to I<perl_call_pv>.
-
-
=item 2.
-Because we are interested in what is returned from I<Adder> we cannot
-specify G_DISCARD. This means that we will have to tidy up the Perl
-stack and dispose of any temporary values ourselves. This is the
-purpose of
-
- ENTER ;
- SAVETMPS ;
-
-at the start of the function, and
-
- FREETMPS ;
- LEAVE ;
-
-at the end. The C<ENTER>/C<SAVETMPS> pair creates a boundary for any
-temporaries we create. This means that the temporaries we get rid of
-will be limited to those which were created after these calls.
-
-The C<FREETMPS>/C<LEAVE> pair will get rid of any values returned by
-the Perl subroutine, plus it will also dump the mortal SVs we have
-created. Having C<ENTER>/C<SAVETMPS> at the beginning of the code
-makes sure that no other mortals are destroyed.
-
-Think of these macros as working a bit like using C<{> and C<}> in Perl
-to limit the scope of local variables.
-
-See the section I<Using Perl to dispose of temporaries> for details of
-an alternative to using these macros.
-
-=item 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 reallocated whilst in the
always refresh the local copy using SPAGAIN whenever you make use
of the I<perl_call_*> functions or any other Perl internal function.
-=item 4.
+=item 3.
Although only a single value was expected to be returned from I<Adder>,
it is still good practice to check the return code from I<perl_call_pv>
stack would end up in an inconsistent state. That is something you
I<really> don't want to happen ever.
-=item 5.
+=item 4.
The C<POPi> macro is used here to pop the return value from the stack.
In this case we wanted an integer, so C<POPi> was used.
POPi integer
POPl long
-=item 6.
+=item 5.
The final C<PUTBACK> is used to leave the Perl stack in a consistent
state before exiting the function. This is necessary because when we
ENTER ;
SAVETMPS;
- PUSHMARK(sp) ;
+ PUSHMARK(SP) ;
XPUSHs(sv_2mortal(newSViv(a)));
XPUSHs(sv_2mortal(newSViv(b)));
PUTBACK ;
ENTER ;
SAVETMPS;
- PUSHMARK(sp) ;
+ PUSHMARK(SP) ;
XPUSHs(sv_2mortal(newSViv(a)));
XPUSHs(sv_2mortal(newSViv(b)));
PUTBACK ;
sva = sv_2mortal(newSViv(a)) ;
svb = sv_2mortal(newSViv(b)) ;
- PUSHMARK(sp) ;
+ PUSHMARK(SP) ;
XPUSHs(sva);
XPUSHs(svb);
PUTBACK ;
ENTER ;
SAVETMPS;
- PUSHMARK(sp) ;
+ PUSHMARK(SP) ;
XPUSHs(sv_2mortal(newSViv(a)));
XPUSHs(sv_2mortal(newSViv(b)));
PUTBACK ;
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
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 ;
}
print "Uh oh - $@\n" if $@ ;
-C<errgv> is a perl global of type C<GV *> that points to the
-symbol table entry containing the error. C<GvSV(errgv)> therefore
+C<PL_errgv> is a perl global of type C<GV *> that points to the
+symbol table entry containing the error. C<ERRSV> therefore
refers to the C equivalent of C<$@>.
=item 3.
Note that the stack is popped using C<POPs> in the block where
-C<SvTRUE(GvSV(errgv))> is true. This is necessary because whenever a
+C<SvTRUE(ERRSV)> 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>. Because we want the
program to continue after detecting this error, it is essential that
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
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<fred> the following can all be used
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
void
CallSavedSub2()
CODE:
- PUSHMARK(sp) ;
+ PUSHMARK(SP) ;
perl_call_sv(keepSub, G_DISCARD|G_NOARGS) ;
To avoid creating a new SV every time C<SaveSub2> is called,
char * method
int index
CODE:
- PUSHMARK(sp);
+ PUSHMARK(SP);
XPUSHs(ref);
XPUSHs(sv_2mortal(newSViv(index))) ;
PUTBACK;
char * class
char * method
CODE:
- PUSHMARK(sp);
+ PUSHMARK(SP);
XPUSHs(sv_2mortal(newSVpv(class, 0))) ;
PUTBACK;
{
dSP ;
- PUSHMARK(sp) ;
+ PUSHMARK(SP) ;
/* Call the Perl sub to process the callback */
perl_call_sv(callback, G_DISCARD) ;
if (sv == (SV**)NULL)
croak("Internal error...\n") ;
- PUSHMARK(sp) ;
+ PUSHMARK(SP) ;
XPUSHs(sv_2mortal(newSViv(fh))) ;
XPUSHs(sv_2mortal(newSVpv(buffer, 0))) ;
PUTBACK ;
{
dSP ;
- PUSHMARK(sp) ;
+ PUSHMARK(SP) ;
XPUSHs(sv_2mortal(newSVpv(buffer, 0))) ;
PUTBACK ;
ENTER ;
SAVETMPS;
- PUSHMARK(sp) ;
+ 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 ;
+ SP -= count ;
+ ax = (SP - PL_stack_base) + 1 ;
if (count != 2)
croak("Big trouble\n") ;
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<ST> macro.
=head2 Creating and calling an anonymous subroutine in C
-As we've already shown, L<perl_call_sv> 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<perl_call_sv> can be used to invoke an
+anonymous subroutine. However, our example showed a Perl script
+invoking an XSUB to perform this operation. Let's see how it can be
done inside our C code:
...
perl_call_sv(cvrv, G_VOID|G_NOARGS);
-L<perlguts/perl_eval_pv> is used to compile the anonymous subroutine, which
-will be the return value as well. Once this code reference is in hand, it
+C<perl_eval_pv> is used to compile the anonymous subroutine, which
+will be the return value as well (read more about C<perl_eval_pv> in
+L<perlguts/perl_eval_pv>). Once this code reference is in hand, it
can be mixed in with all the previous examples we've shown.
=head1 SEE ALSO
projects / p5sagit/p5-mst-13.2.git / blobdiff