view release on metacpan or  search on metacpan

pod/perlguts.pod  view on Meta::CPAN

    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.

=head2 Calling Perl Routines from within C Programs

There are four routines that can be used to call a Perl subroutine from
within a C program.  These four are:

    I32  call_sv(SV*, I32);
    I32  call_pv(const char*, I32);
    I32  call_method(const char*, I32);
    I32  call_argv(const char*, I32, char**);

The routine most often used is C<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.

These routines used to be called C<perl_call_sv>, etc., before Perl v5.6.0,
but those names are now deprecated; macros of the same name are provided for
compatibility.

When using any of these routines (except C<call_argv>), the programmer
must manipulate the Perl stack.  These include the following macros and
functions:

    dSP
    SP
    PUSHMARK()
    PUTBACK
    SPAGAIN
    ENTER
    SAVETMPS
    FREETMPS
    LEAVE
    XPUSH*()
    POP*()

For a detailed description of calling conventions from C to Perl,
consult L<perlcall>.

=head2 Putting a C value on Perl stack

A lot of opcodes (this is an elementary operation in the internal perl
stack machine) put an SV* on the stack.  However, as an optimization
the corresponding SV is (usually) not recreated each time.  The opcodes
reuse specially assigned SVs (I<target>s) which are (as a corollary)
not constantly freed/created.

Each of the targets is created only once (but see
L</Scratchpads and recursion> below), and when an opcode needs to put
an integer, a double, or a string on the stack, it just sets the
corresponding parts of its I<target> and puts the I<target> on stack.

The macro to put this target on stack is C<PUSHTARG>, and it is
directly used in some opcodes, as well as indirectly in zillions of
others, which use it via C<(X)PUSH[iunp]>.

Because the target is reused, you must be careful when pushing multiple
values on the stack.  The following code will not do what you think:

    XPUSHi(10);
    XPUSHi(20);

This translates as "set C<TARG> to 10, push a pointer to C<TARG> onto
the stack; set C<TARG> to 20, push a pointer to C<TARG> onto the stack".
At the end of the operation, the stack does not contain the values 10
and 20, but actually contains two pointers to C<TARG>, which we have set
to 20.

If you need to push multiple different values then you should either use
the C<(X)PUSHs> macros, or else use the new C<m(X)PUSH[iunp]> macros,
none of which make use of C<TARG>.  The C<(X)PUSHs> macros simply push an
SV* on the stack, which, as noted under L</XSUBs and the Argument Stack>,
will often need to be "mortal".  The new C<m(X)PUSH[iunp]> macros make
this a little easier to achieve by creating a new mortal for you (via
C<(X)PUSHmortal>), pushing that onto the stack (extending it if necessary
in the case of the C<mXPUSH[iunp]> macros), and then setting its value.
Thus, instead of writing this to "fix" the example above:

    XPUSHs(sv_2mortal(newSViv(10)))
    XPUSHs(sv_2mortal(newSViv(20)))

you can simply write:

    mXPUSHi(10)
    mXPUSHi(20)

On a related note, if you do use C<(X)PUSH[iunp]>, then you're going to
need a C<dTARG> in your variable declarations so that the C<*PUSH*>
macros can make use of the local variable C<TARG>.  See also
C<dTARGET> and C<dXSTARG>.

Be careful with TARG: each non-recursive call to your OP, or XSUB for
dXSTARG, will use the same SV for TARG for each call, so you can't
assume the SV is pristine since the results from the previous call to
your OP or XSUB may still be in TARG.

Other state such as a cached numeric version of a PV or the cached
UTF-8 length may also be set.  You can avoid problems with this by
using the normal sv_set*() APIs instead of trying to optimize by
directly manipulating the SV.

For OPs that implement the C<OA_TARGLEX> optimization, TARG may be
special in other ways, there may be references to it, it might be
blessed, it might be tied, or magical in other ways.

pod/perlguts.pod  view on Meta::CPAN

    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.

=head2 Moving

    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 PerlIO

The most recent development releases of Perl have been experimenting with
removing Perl's dependency on the "normal" standard I/O suite and allowing
other stdio implementations to be used.  This involves creating a new
abstraction layer that then calls whichever implementation of stdio Perl
was compiled with.  All XSUBs should now use the functions in the PerlIO
abstraction layer and not make any assumptions about what kind of stdio
is being used.

For a complete description of the PerlIO abstraction, consult L<perlapio>.

=head1 Compiled code

=head2 Code tree

Here we describe the internal form your code is converted to by
Perl.  Start with a simple example:

  $a = $b + $c;

This is converted to a tree similar to this one:

             assign-to
           /           \
          +             $a
        /   \
      $b     $c

(but slightly more complicated).  This tree reflects the way Perl
parsed your code, but has nothing to do with the execution order.
There is an additional "thread" going through the nodes of the tree
which shows the order of execution of the nodes.  In our simplified
example above it looks like:

     $b ---> $c ---> + ---> $a ---> assign-to

But with the actual compile tree for C<$a = $b + $c> it is different:
some nodes I<optimized away>.  As a corollary, though the actual tree
contains more nodes than our simplified example, the execution order
is the same as in our example.

=head2 Examining the tree

If you have your perl compiled for debugging (usually done with
C<-DDEBUGGING> on the C<Configure> command line), you may examine the
compiled tree by specifying C<-Dx> on the Perl command line.  The
output takes several lines per node, and for C<$b+$c> it looks like
this:

    5           TYPE = add  ===> 6
                TARG = 1
                FLAGS = (SCALAR,KIDS)
                {
                    TYPE = null  ===> (4)
                      (was rv2sv)
                    FLAGS = (SCALAR,KIDS)
                    {
    3                   TYPE = gvsv  ===> 4
                        FLAGS = (SCALAR)
                        GV = main::b
                    }
                }
                {
                    TYPE = null  ===> (5)
                      (was rv2sv)
                    FLAGS = (SCALAR,KIDS)
                    {
    4                   TYPE = gvsv  ===> 5
                        FLAGS = (SCALAR)
                        GV = main::c
                    }
                }

This tree has 5 nodes (one per C<TYPE> specifier), only 3 of them are
not optimized away (one per number in the left column).  The immediate
children of the given node correspond to C<{}> pairs on the same level
of indentation, thus this listing corresponds to the tree:

                   add
                 /     \
               null    null
                |       |
               gvsv    gvsv

The execution order is indicated by C<===E<gt>> marks, thus it is C<3
4 5 6> (node C<6> is not included into above listing), i.e.,
C<gvsv gvsv add whatever>.

Each of these nodes represents an op, a fundamental operation inside the
Perl core.  The code which implements each operation can be found in the
F<pp*.c> files; the function which implements the op with type C<gvsv>
is C<pp_gvsv>, and so on.  As the tree above shows, different ops have
different numbers of children: C<add> is a binary operator, as one would
expect, and so has two children.  To accommodate the various different
numbers of children, there are various types of op data structure, and
they link together in different ways.

The simplest type of op structure is C<OP>: this has no children.  Unary