view release on metacpan or  search on metacpan

lib/POD2/RU/perlguts.pod  view on Meta::CPAN

=over 4

=item C<SV* save_scalar(GV *gv)>

Equivalent to Perl code C<local $gv>.

=item C<AV* save_ary(GV *gv)>

=item C<HV* save_hash(GV *gv)>

Similar to C<save_scalar>, but localize C<@gv> and C<%gv>.

=item C<void save_item(SV *item)>

Duplicates the current value of C<SV>, on the exit from the current
C<ENTER>/C<LEAVE> I<pseudo-block> will restore the value of C<SV>
using the stored value. It doesn't handle magic. Use C<save_scalar> if
magic is affected.

=item C<void save_list(SV **sarg, I32 maxsarg)>

A variant of C<save_item> which takes multiple arguments via an array
C<sarg> of C<SV*> of length C<maxsarg>.

=item C<SV* save_svref(SV **sptr)>

Similar to C<save_scalar>, but will reinstate an C<SV *>.

=item C<void save_aptr(AV **aptr)>

=item C<void save_hptr(HV **hptr)>

Similar to C<save_svref>, but localize C<AV *> and C<HV *>.

=back

The C<Alias> module implements localization of the basic types within the
I<caller's scope>.  People who are interested in how to localize things in
the containing scope should take a look there too.

=head1 Subroutines

=head2 XSUBs 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
program, and a way to map from the Perl data structures to a C equivalent.

The stack arguments are accessible through the C<ST(n)> macro, which returns
the C<n>'th stack argument.  Argument 0 is the first argument passed in the
Perl subroutine call.  These arguments are C<SV*>, and can be used anywhere
an C<SV*> is used.

Most of the time, output from the C routine can be handled through use of
the RETVAL and OUTPUT directives.  However, there are some cases where the
argument stack is not already long enough to handle all the return values.
An example is the POSIX tzname() call, which takes no arguments, but returns
two, the local time zone's standard and summer time abbreviations.

To handle this situation, the PPCODE directive is used and the stack is
extended using the macro:

    EXTEND(SP, num);

where C<SP> is the macro that represents the local copy of the stack pointer,
and C<num> is the number of elements the stack should be extended by.

Now that there is room on the stack, values can be pushed on it using C<PUSHs>
macro. The pushed values will often need to be "mortal" (See
L</Reference Counts and Mortality>):

    PUSHs(sv_2mortal(newSViv(an_integer)))
    PUSHs(sv_2mortal(newSVuv(an_unsigned_integer)))
    PUSHs(sv_2mortal(newSVnv(a_double)))
    PUSHs(sv_2mortal(newSVpv("Some String",0)))
    /* Although the last example is better written as the more
     * efficient: */
    PUSHs(newSVpvs_flags("Some String", SVs_TEMP))

And now the Perl program calling C<tzname>, the two values will be assigned
as in:

    ($standard_abbrev, $summer_abbrev) = POSIX::tzname;

An alternate (and possibly simpler) method to pushing values on the stack is
to use the macro:

    XPUSHs(SV*)

This macro automatically adjusts the stack for you, if needed.  Thus, you
do not need to call C<EXTEND> to extend the stack.

Despite their suggestions in earlier versions of this document the macros
C<(X)PUSH[iunp]> are I<not> suited to XSUBs which return multiple results.
For that, either stick to the C<(X)PUSHs> macros shown above, or use the new
C<m(X)PUSH[iunp]> macros instead; see L</Putting a C value on Perl stack>.

For more information, consult L<perlxs> and L<perlxstut>.

=head2 Autoloading with XSUBs

If an AUTOLOAD routine is an XSUB, as with Perl subroutines, Perl puts the
fully-qualified name of the autoloaded subroutine in the $AUTOLOAD variable
of the XSUB's package.

But it also puts the same information in certain fields of the XSUB itself:

    HV *stash           = CvSTASH(cv);
    const char *subname = SvPVX(cv);
    STRLEN name_length  = SvCUR(cv); /* in bytes */
    U32 is_utf8         = SvUTF8(cv);

C<SvPVX(cv)> contains just the sub name itself, not including the package.
For an AUTOLOAD routine in UNIVERSAL or one of its superclasses,
C<CvSTASH(cv)> returns NULL during a method call on a nonexistent package.

B<Note>: Setting $AUTOLOAD stopped working in 5.6.1, which did not support
XS AUTOLOAD subs at all.  Perl 5.8.0 introduced the use of fields in the
XSUB itself.  Perl 5.16.0 restored the setting of $AUTOLOAD.  If you need
to support 5.8-5.14, use the XSUB's fields.