Perl executable. It is far from complete and probably contains many errors.
Please refer any questions or comments to the author below.
+=head1 Variables
+
=head2 Datatypes
Perl has three typedefs that handle Perl's three main data types:
however, that Perl allows arbitrary strings of data that may both contain
NUL's and might not be terminated by a NUL.
-If you want to know simply if the scalar value is TRUE, you can use:
+If you want to know if the scalar value is TRUE, you can use:
SvTRUE(SV*)
call the function C<sv_grow>. Note that C<SvGROW> can only increase, not
decrease, the allocated memory of an SV and that it does not automatically
add a byte for the a trailing NUL (perl's own string functions typically do
-SvGROW(sv, len + 1)).
+C<SvGROW(sv, len + 1)>).
If you have an SV and want to know what kind of data Perl thinks is stored
in it, you can use the following macros to check the type of SV you have.
These will tell you if you truly have an integer, double, or string pointer
stored in your SV. The "p" stands for private.
-In general, though, it's best just to use the C<Sv*V> macros.
+In general, though, it's best to use the C<Sv*V> macros.
=head2 Working with AV's
-There are two ways to create and load an AV. The first method creates just
-an empty AV:
+There are two ways to create and load an AV. The first method creates an
+empty AV:
AV* newAV();
This returns NULL if the variable does not exist.
-The hash algorithm is defined in the PERL_HASH(hash, key, klen) macro:
+The hash algorithm is defined in the C<PERL_HASH(hash, key, klen)> macro:
i = klen;
hash = 0;
References are a special type of scalar that point to other data types
(including references).
-To create a reference, use the following functions:
+To create a reference, use either of the following functions:
SV* newRV_inc((SV*) thing);
SV* newRV_noinc((SV*) thing);
The C<thing> argument can be any of an C<SV*>, C<AV*>, or C<HV*>. The
-functions are identical except that C<newRV_inc> increments the
-reference count of C<thing>, while C<newRV_noinc> does not. (For
-historical reasons, "newRV" is a synonym for "newRV_inc".) Once you
-have a reference, you can use the following macro to dereference the
-reference:
+functions are identical except that C<newRV_inc> increments the reference
+count of the C<thing>, while C<newRV_noinc> does not. For historical
+reasons, C<newRV> is a synonym for C<newRV_inc>.
+
+Once you have a reference, you can use the following macro to dereference
+the reference:
SvRV(SV*)
SvROK(SV*)
-To discover what type of value the reference refers to, you must use the
-following macro and then check the value returned.
+To discover what type of value the reference refers to, use the following
+macro and then check the return value.
SvTYPE(SvRV(SV*))
/* Still under construction */
Upgrades rv to reference if not already one. Creates new SV for rv to
-point to.
-If classname is non-null, the SV is blessed into the specified class.
-SV is returned.
+point to. If C<classname> is non-null, the SV is blessed into the specified
+class. SV is returned.
SV* newSVrv(SV* rv, char* classname);
-Copies integer or double into an SV whose reference is rv. SV is blessed
-if classname is non-null.
+Copies integer or double into an SV whose reference is C<rv>. SV is blessed
+if C<classname> is non-null.
SV* sv_setref_iv(SV* rv, char* classname, IV iv);
SV* sv_setref_nv(SV* rv, char* classname, NV iv);
Copies the pointer value (I<the address, not the string!>) into an SV whose
-reference is rv. SV is blessed if classname is non-null.
+reference is rv. SV is blessed if C<classname> is non-null.
SV* sv_setref_pv(SV* rv, char* classname, PV iv);
-Copies string into an SV whose reference is rv.
-Set length to 0 to let Perl calculate the string length.
-SV is blessed if classname is non-null.
+Copies string into an SV whose reference is C<rv>. Set length to 0 to let
+Perl calculate the string length. SV is blessed if C<classname> is non-null.
SV* sv_setref_pvn(SV* rv, char* classname, PV iv, int length);
GV_ADDMULTI Marks the variable as multiply defined, thus preventing the
"Indentifier <varname> used only once: possible typo" warning.
- GV_ADDWARN Issues a "Had to create <varname> unexpectedly" warning if
- the variable didn't actually exist. This is useful if
- you expected the variable to exist already and want to
- propagate this warning back to the user.
+ GV_ADDWARN Issues the warning "Had to create <varname> unexpectedly" if
+ the variable did not exist before the function was called.
-If the C<varname> argument does not contain a package specifier, it is
-created in the current package.
+If you do not specify a package name, the variable is created in the current
+package.
=head2 Reference Counts and Mortality
Perl uses an reference count-driven garbage collection mechanism. SV's,
AV's, or HV's (xV for short in the following) start their life with a
reference count of 1. If the reference count of an xV ever drops to 0,
-then they will be destroyed and their memory made available for reuse.
+then it will be destroyed and its memory made available for reuse.
This normally doesn't happen at the Perl level unless a variable is
undef'ed or the last variable holding a reference to it is changed or
void SvREFCNT_dec(SV* sv);
However, there is one other function which manipulates the reference
-count of its argument. The C<newRV_inc> function, as you should
-recall, creates a reference to the specified argument. As a side
-effect, it increments the argument's reference count. If this is not
-what you want, use C<newRV_noinc> instead.
-
-For example, imagine you want to return a reference from an XSUB
-function. You create a new SV which initially has a reference count
-of one. Then you call C<newRV_inc>, passing the just-created SV.
+count of its argument. The C<newRV_inc> function, you will recall,
+creates a reference to the specified argument. As a side effect,
+it increments the argument's reference count. If this is not what
+you want, use C<newRV_noinc> instead.
+
+For example, imagine you want to return a reference from an XSUB function.
+Inside the XSUB routine, you create an SV which initially has a reference
+count of one. Then you call C<newRV_inc>, passing it the just-created SV.
This returns the reference as a new SV, but the reference count of the
SV you passed to C<newRV_inc> has been incremented to two. Now you
-return the reference and forget about the SV. But Perl hasn't!
-Whenever the returned reference is destroyed, the reference count of
-the original SV is decreased to one and nothing happens. The SV will
-hang around without any way to access it until Perl itself terminates.
-This is a memory leak.
+return the reference from the XSUB routine and forget about the SV.
+But Perl hasn't! Whenever the returned reference is destroyed, the
+reference count of the original SV is decreased to one and nothing happens.
+The SV will hang around without any way to access it until Perl itself
+terminates. This is a memory leak.
The correct procedure, then, is to use C<newRV_noinc> instead of
-C<newRV_inc>. Then, if and when the last reference is destroyed, the
-reference count of the SV will go to 0 and also be destroyed, stopping
-any memory leak.
+C<newRV_inc>. Then, if and when the last reference is destroyed,
+the reference count of the SV will go to zero and it will be destroyed,
+stopping any memory leak.
There are some convenience functions available that can help with the
-destruction of old xV objects. These functions introduce the concept
-of "mortality". An xV that is mortal has had its reference count
-marked to be decremented, but not actually decremented, until "a short
-time later". Generally the term "short time later" means a single
-Perl statement, such as a call to an XSUB function. The actual
-determinant for when mortal xV's have their reference count
-decremented depends on two macros, SAVETMPS and FREETMPS. Take a look
-at L<perlcall> and L<perlxs> for more details on these macros.
+destruction of xV's. These functions introduce the concept of "mortality".
+An xV that is mortal has had its reference count marked to be decremented,
+but not actually decremented, until "a short time later". Generally the
+term "short time later" means a single Perl statement, such as a call to
+an XSUB function. The actual determinant for when mortal xV's have their
+reference count decremented depends on two macros, SAVETMPS and FREETMPS.
+See L<perlcall> and L<perlxs> for more details on these macros.
"Mortalization" then is at its simplest a deferred C<SvREFCNT_dec>.
However, if you mortalize a variable twice, the reference count will
SV to a mortal SV (and thus defers a call to C<SvREFCNT_dec>), and the
third creates a mortal copy of an existing SV.
-The mortal routines are not for just SV's -- AV's and HV's can be made
-mortal by passing their address (casted to C<SV*>) to the C<sv_2mortal> or
-C<sv_mortalcopy> routines.
+The mortal routines are not just for SV's -- AV's and HV's can be
+made mortal by passing their address (type-casted to C<SV*>) to the
+C<sv_2mortal> or C<sv_mortalcopy> routines.
=head2 Stashes and Globs
-A stash is a hash table (associative array) that contains all of the
-different objects that are contained within a package. Each key of the
-stash is a symbol name (shared by all the different types of objects
-that have the same name), and each value in the hash table is called a
-GV (for Glob Value). This GV in turn contains references to the various
-objects of that name, including (but not limited to) the following:
+A "stash" is a hash that contains all of the different objects that
+are contained within a package. Each key of the stash is a symbol
+name (shared by all the different types of objects that have the same
+name), and each value in the hash table is a GV (Glob Value). This GV
+in turn contains references to the various objects of that name,
+including (but not limited to) the following:
Scalar Value
Array Value
For more information on references and blessings, consult L<perlref>.
-=head2 Magic
+=head2 Double-Typed SV's
+
+Scalar variables normally contain only one type of value, an integer,
+double, pointer, or reference. Perl will automatically convert the
+actual scalar data from the stored type into the requested type.
+
+Some scalar variables contain more than one type of scalar data. For
+example, the variable C<$!> contains either the numeric value of C<errno>
+or its string equivalent from either C<strerror> or C<sys_errlist[]>.
+
+To force multiple data values into an SV, you must do two things: use the
+C<sv_set*v> routines to add the additional scalar type, then set a flag
+so that Perl will believe it contains more than one type of data. The
+four macros to set the flags are:
+
+ SvIOK_on
+ SvNOK_on
+ SvPOK_on
+ SvROK_on
+
+The particular macro you must use depends on which C<sv_set*v> routine
+you called first. This is because every C<sv_set*v> routine turns on
+only the bit for the particular type of data being set, and turns off
+all the rest.
+
+For example, to create a new Perl variable called "dberror" that contains
+both the numeric and descriptive string error values, you could use the
+following code:
+
+ extern int dberror;
+ extern char *dberror_list;
+
+ SV* sv = perl_get_sv("dberror", TRUE);
+ sv_setiv(sv, (IV) dberror);
+ sv_setpv(sv, dberror_list[dberror]);
+ SvIOK_on(sv);
+
+If the order of C<sv_setiv> and C<sv_setpv> had been reversed, then the
+macro C<SvPOK_on> would need to be called instead of C<SvIOK_on>.
+
+=head2 Magic Variables
[This section still under construction. Ignore everything here. Post no
bills. Everything not permitted is forbidden.]
The current kinds of Magic Virtual Tables are:
- mg_type MGVTBL Type of magic
+ mg_type MGVTBL Type of magical
------- ------ ----------------------------
\0 vtbl_sv Regexp???
A vtbl_amagic Operator Overloading
i vtbl_isaelem @ISA array element
L 0 (but sets RMAGICAL) Perl Module/Debugger???
l vtbl_dbline Debugger?
+ o vtbl_collxfrm Locale transformation
P vtbl_pack Tied Array or Hash
p vtbl_packelem Tied Array or Hash element
q vtbl_packelem Tied Scalar or Handle
U vtbl_uvar ???
v vtbl_vec Vector
x vtbl_substr Substring???
+ y vtbl_itervar Shadow "foreach" iterator variable
* vtbl_glob GV???
# vtbl_arylen Array Length
. vtbl_pos $. scalar variable
field is an upper-case letter, then the mg_obj is copied to C<nsv>, but
the mg_type field is changed to be the lower-case letter.
-=head2 Double-Typed SV's
-
-Scalar variables normally contain only one type of value, an integer,
-double, pointer, or reference. Perl will automatically convert the
-actual scalar data from the stored type into the requested type.
-
-Some scalar variables contain more than one type of scalar data. For
-example, the variable C<$!> contains either the numeric value of C<errno>
-or its string equivalent from either C<strerror> or C<sys_errlist[]>.
-
-To force multiple data values into an SV, you must do two things: use the
-C<sv_set*v> routines to add the additional scalar type, then set a flag
-so that Perl will believe it contains more than one type of data. The
-four macros to set the flags are:
-
- SvIOK_on
- SvNOK_on
- SvPOK_on
- SvROK_on
-
-The particular macro you must use depends on which C<sv_set*v> routine
-you called first. This is because every C<sv_set*v> routine turns on
-only the bit for the particular type of data being set, and turns off
-all the rest.
-
-For example, to create a new Perl variable called "dberror" that contains
-both the numeric and descriptive string error values, you could use the
-following code:
-
- extern int dberror;
- extern char *dberror_list;
-
- SV* sv = perl_get_sv("dberror", TRUE);
- sv_setiv(sv, (IV) dberror);
- sv_setpv(sv, dberror_list[dberror]);
- SvIOK_on(sv);
-
-If the order of C<sv_setiv> and C<sv_setpv> had been reversed, then the
-macro C<SvPOK_on> would need to be called instead of C<SvIOK_on>.
+=head1 Subroutines
=head2 XSUB's and the Argument Stack
It is suggested that you use the version of malloc that is distributed
with Perl. It keeps pools of various sizes of unallocated memory in
-satisfy allocation requests more quickly. However, on some platforms, it
-may cause spurious malloc or free errors.
+order to satisfy allocation requests more quickly. However, on some
+platforms, it may cause spurious malloc or free errors.
New(x, pointer, number, type);
Newc(x, pointer, number, type, cast);
Newz(x, pointer, number, type);
-These three macros are used to allocate memory.
+These three macros are used to initially allocate memory.
The first argument C<x> was a "magic cookie" that was used to keep track
of who called the macro, to help when debugging memory problems. However,
-the current code makes no use of this feature (Larry has switched to using
-a run-time memory checker), so this argument can be any number.
+the current code makes no use of this feature (most Perl developers now
+use run-time memory checkers), so this argument can be any number.
The second argument C<pointer> should be the name of a variable that will
point to the newly allocated memory.
For a complete description of the PerlIO abstraction, consult L<perlapio>.
-=head2 Scratchpads
-
-=head3 Putting a C value on Perl stack
+=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
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
+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 stack, it just sets the
corresponding parts of its I<target> and puts the I<target> on stack.
directly used in some opcodes, as well as indirectly in zillions of
others, which use it via C<(X)PUSH[pni]>.
-=head3 Scratchpads
+=head2 Scratchpads
The question remains on when the SV's which are I<target>s for opcodes
are created. The answer is that they are created when the current unit --
OP's in the compile tree of the unit can use the same target, if this
would not conflict with the expected life of the temporary.
-=head3 Scratchpads and recursions
+=head2 Scratchpads and recursions
In fact it is not 100% true that a compiled unit contains a pointer to
the scratchpad AV. In fact it contains a pointer to an AV of
The I<target>s on this scratchpad are C<undef>s, but they are already
marked with correct flags.
-=head2 API LISTING
+=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 reflect 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<-D
+optimize=-g> on 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>.
+
+=head2 Compile pass 1: check routines
+
+The tree is created by the I<pseudo-compiler> while yacc code feeds it
+the constructions it recognizes. Since yacc works bottom-up, so does
+the first pass of perl compilation.
+
+What makes this pass interesting for perl developers is that some
+optimization may be performed on this pass. This is optimization by
+so-called I<check routines>. The correspondence between node names
+and corresponding check routines is described in F<opcode.pl> (do not
+forget to run C<make regen_headers> if you modify this file).
+
+A check routine is called when the node is fully constructed except
+for the execution-order thread. Since at this time there is no
+back-links to the currently constructed node, one can do most any
+operation to the top-level node, including freeing it and/or creating
+new nodes above/below it.
+
+The check routine returns the node which should be inserted into the
+tree (if the top-level node was not modified, check routine returns
+its argument).
+
+By convention, check routines have names C<ck_*>. They are usually
+called from C<new*OP> subroutines (or C<convert>) (which in turn are
+called from F<perly.y>).
+
+=head2 Compile pass 1a: constant folding
+
+Immediately after the check routine is called the returned node is
+checked for being compile-time executable. If it is (the value is
+judged to be constant) it is immediately executed, and a I<constant>
+node with the "return value" of the corresponding subtree is
+substituted instead. The subtree is deleted.
+
+If constant folding was not performed, the execution-order thread is
+created.
+
+=head2 Compile pass 2: context propagation
+
+When a context for a part of compile tree is known, it is propagated
+down through the tree. Aat this time the context can have 5 values
+(instead of 2 for runtime context): void, boolean, scalar, list, and
+lvalue. In contrast with the pass 1 this pass is processed from top
+to bottom: a node's context determines the context for its children.
+
+Additional context-dependent optimizations are performed at this time.
+Since at this moment the compile tree contains back-references (via
+"thread" pointers), nodes cannot be free()d now. To allow
+optimized-away nodes at this stage, such nodes are null()ified instead
+of free()ing (i.e. their type is changed to OP_NULL).
+
+=head2 Compile pass 3: peephole optimization
+
+After the compile tree for a subroutine (or for an C<eval> or a file)
+is created, an additional pass over the code is performed. This pass
+is neither top-down or bottom-up, but in the execution order (with
+additional compilications for conditionals). These optimizations are
+done in the subroutine peep(). Optimizations performed at this stage
+are subject to the same restrictions as in the pass 2.
+
+=head1 API LISTING
This is a listing of functions, macros, flags, and variables that may be
useful to extension writers or that may be found while reading other
Used to indicate scalar context. See C<GIMME> and L<perlcall>.
+=item gv_fetchmeth
+
+Returns the glob with the given C<name> and a defined subroutine or
+C<NULL>. The glob lives in the given C<stash>, or in the stashes accessable
+via @ISA and @<UNIVERSAL>.
+
+The argument C<level> should be either 0 or -1. If C<level==0>, as a
+side-effect creates a glob with the given C<name> in the given
+C<stash> which in the case of success contains an alias for the
+subroutine, and sets up caching info for this glob. Similarly for all
+the searched stashes.
+
+The GV returned from C<gv_fetchmeth> may be a method cache entry,
+which is not visible to Perl code. So when calling C<perl_call_sv>,
+you should not use the GV directly; instead, you should use the
+method's CV, which can be obtained from the GV with the C<GvCV> macro.
+
+ GV* gv_fetchmeth _((HV* stash, char* name, STRLEN len, I32 level));
+
+=item gv_fetchmethod
+
+Returns the glob which contains the subroutine to call to invoke the
+method on the C<stash>. In fact in the presense of autoloading this may
+be the glob for "AUTOLOAD". In this case the corresponing variable
+$AUTOLOAD is already setup.
+
+Note that if you want to keep this glob for a long time, you need to
+check for it being "AUTOLOAD", since at the later time the the call
+may load a different subroutine due to $AUTOLOAD changing its value.
+Use the glob created via a side effect to do this.
+
+This function grants C<"SUPER"> token as prefix of name or postfix of
+the stash name.
+
+Has the same side-effects and as C<gv_fetchmeth> with C<level==0>.
+C<name> should be writable if contains C<':'> or C<'\''>.
+The warning against passing the GV returned by C<gv_fetchmeth> to
+C<perl_call_sv> apply equally to C<gv_fetchmethod>.
+
+ GV* gv_fetchmethod _((HV* stash, char* name));
+
=item gv_stashpv
Returns a pointer to the stash for a specified package. If C<create> is set
Return the SV from the GV.
+=item he_delayfree
+
+Releases a hash entry, such as while iterating though the hash, but
+delays actual freeing of key and value until the end of the current
+statement (or thereabouts) with C<sv_2mortal>. See C<hv_iternext>.
+
+ void he_delayfree _((HV* hv, HE* hent));
+
=item he_free
-Releases a hash entry from an iterator. See C<hv_iternext>.
+Releases a hash entry, such as while iterating though the hash. See
+C<hv_iternext>.
+
+ void he_free _((HV* hv, HE* hent));
=item hv_clear
Creates an RV wrapper for an SV. The reference count for the original
SV is B<not> incremented.
- SV* newRV_noinc _((SV* ref));
+ SV* newRV_noinc _((SV* ref));
=item newSV
Creates a new SV. The C<len> parameter indicates the number of bytes of
-pre-allocated string space the SV should have. The reference count for the new SV
-is set to 1.
+pre-allocated string space the SV should have. The reference count for the
+new SV is set to 1.
SV* newSV _((STRLEN len));
=item newSViv
-Creates a new SV and copies an integer into it. The reference count for the SV is
-set to 1.
+Creates a new SV and copies an integer into it. The reference count for the
+SV is set to 1.
SV* newSViv _((IV i));
=item newSVnv
-Creates a new SV and copies a double into it. The reference count for the SV is
-set to 1.
+Creates a new SV and copies a double into it. The reference count for the
+SV is set to 1.
SV* newSVnv _((NV i));
=item newSVpv
-Creates a new SV and copies a string into it. The reference count for the SV is
-set to 1. If C<len> is zero then Perl will compute the length.
+Creates a new SV and copies a string into it. The reference count for the
+SV is set to 1. If C<len> is zero then Perl will compute the length.
SV* newSVpv _((char* s, STRLEN len));
=item sv_bless
Blesses an SV into a specified package. The SV must be an RV. The package
-must be designated by its stash (see C<gv_stashpv()>). The reference count of the
-SV is unaffected.
+must be designated by its stash (see C<gv_stashpv()>). The reference count
+of the SV is unaffected.
SV* sv_bless _((SV* sv, HV* stash));
=item sv_inc
-Auto increment of the value in the SV.
+Auto-increment of the value in the SV.
void sv_inc _((SV* sv));
=item sv_unref
-Unsets the RV status of the SV, and decrements the reference count of whatever was
-being referenced by the RV. This can almost be thought of as a reversal of
-C<newSVrv>. See C<SvROK_off>.
+Unsets the RV status of the SV, and decrements the reference count of
+whatever was being referenced by the RV. This can almost be thought of
+as a reversal of C<newSVrv>. See C<SvROK_off>.
void sv_unref _((SV* sv));
=head1 DATE
-Version 25.2: 1996/12/16
+Version 31: 1997/1/27
projects / p5sagit/p5-mst-13.2.git / blobdiff