Perl also uses two special typedefs, I32 and I16, which will always be at
least 32-bits and 16-bits long, respectively. (Again, there are U32 and U16,
-as well.)
+as well.) They will usually be exactly 32 and 16 bits long, but on Crays
+they will both be 64 bits.
=head2 Working with SVs
-An SV can be created and loaded with one command. There are four types of
-values that can be loaded: an integer value (IV), a double (NV),
-a string (PV), and another scalar (SV).
+An SV can be created and loaded with one command. There are five types of
+values that can be loaded: an integer value (IV), an unsigned integer
+value (UV), a double (NV), a string (PV), and another scalar (SV).
-The six routines are:
+The seven routines are:
SV* newSViv(IV);
+ SV* newSVuv(UV);
SV* newSVnv(double);
SV* newSVpv(const char*, int);
SV* newSVpvn(const char*, int);
SV* newSVpvf(const char*, ...);
SV* newSVsv(SV*);
-To change the value of an *already-existing* SV, there are seven routines:
+If you require more complex initialisation you can create an empty SV with
+newSV(len). If C<len> is 0 an empty SV of type NULL is returned, else an
+SV of type PV is returned with len + 1 (for the NUL) bytes of storage
+allocated, accessible via SvPVX. In both cases the SV has value undef.
+
+ SV* newSV(0); /* no storage allocated */
+ SV* newSV(10); /* 10 (+1) bytes of uninitialised storage allocated */
+
+To change the value of an *already-existing* SV, there are eight routines:
void sv_setiv(SV*, IV);
void sv_setuv(SV*, UV);
void sv_setpv(SV*, const char*);
void sv_setpvn(SV*, const char*, int)
void sv_setpvf(SV*, const char*, ...);
- void sv_setpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool);
+ void sv_vsetpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool *);
void sv_setsv(SV*, SV*);
Notice that you can choose to specify the length of the string to be
The arguments of C<sv_setpvf> are processed like C<sprintf>, and the
formatted output becomes the value.
-C<sv_setpvfn> is an analogue of C<vsprintf>, but it allows you to specify
+C<sv_vsetpvfn> is an analogue of C<vsprintf>, but it allows you to specify
either a pointer to a variable argument list or the address and length of
an array of SVs. The last argument points to a boolean; on return, if that
boolean is true, then locale-specific information has been used to format
void sv_catpv(SV*, const char*);
void sv_catpvn(SV*, const char*, STRLEN);
void sv_catpvf(SV*, const char*, ...);
- void sv_catpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool);
+ void sv_vcatpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool);
void sv_catsv(SV*, SV*);
The first function calculates the length of the string to be appended by
Perl provides the function C<sv_chop> to efficiently remove characters
from the beginning of a string; you give it an SV and a pointer to
-somewhere inside the the PV, and it discards everything before the
+somewhere inside the PV, and it discards everything before the
pointer. The efficiency comes by means of a little hack: instead of
actually removing the characters, C<sv_chop> sets the flag C<OOK>
(offset OK) to signal to other functions that the offset hack is in
shown in parentheses, and the values of C<SvCUR> and C<SvLEN> reflect
the fake beginning, not the real one.
-Something similar to the offset hack is perfomed on AVs to enable
+Something similar to the offset hack is performed on AVs to enable
efficient shifting and splicing off the beginning of the array; while
C<AvARRAY> points to the first element in the array that is visible from
Perl, C<AvALLOC> points to the real start of the C array. These are
/* Get the key from an HE structure and also return
the length of the key string */
SV* hv_iterval(HV*, HE* entry);
- /* Return a SV pointer to the value of the HE
+ /* Return an SV pointer to the value of the HE
structure */
SV* hv_iternextsv(HV*, char** key, I32* retlen);
/* This convenience routine combines hv_iternext,
There are additional macros whose values may be bitwise OR'ed with the
C<TRUE> argument to enable certain extra features. Those bits are:
- GV_ADDMULTI Marks the variable as multiply defined, thus preventing the
- "Name <varname> used only once: possible typo" warning.
- GV_ADDWARN Issues the warning "Had to create <varname> unexpectedly" if
- the variable did not exist before the function was called.
+=over
+
+=item GV_ADDMULTI
+
+Marks the variable as multiply defined, thus preventing the:
+
+ Name <varname> used only once: possible typo
+
+warning.
+
+=item GV_ADDWARN
+
+Issues the warning:
+
+ Had to create <varname> unexpectedly
+
+if the variable did not exist before the function was called.
+
+=back
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. SVs,
+Perl uses a reference count-driven garbage collection mechanism. SVs,
AVs, or HVs (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 it will be destroyed and its memory made available for reuse.
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.
Because C<sv_newmortal> gives the new SV no value,it must normally be given one
-via C<sv_setpv>, C<sv_setiv> etc. :
+via C<sv_setpv>, C<sv_setiv>, etc. :
SV *tmp = sv_newmortal();
sv_setiv(tmp, an_integer);
feature.
If C<sv> is not already magical, Perl uses the C<SvUPGRADE> macro to
-set the C<SVt_PVMG> flag for the C<sv>. Perl then continues by adding
-it to the beginning of the linked list of magical features. Any prior
-entry of the same type of magic is deleted. Note that this can be
-overridden, and multiple instances of the same type of magic can be
-associated with an SV.
+convert C<sv> to type C<SVt_PVMG>. Perl then continues by adding new magic
+to the beginning of the linked list of magical features. Any prior entry
+of the same type of magic is deleted. Note that this can be overridden,
+and multiple instances of the same type of magic can be associated with an
+SV.
The C<name> and C<namlen> arguments are used to associate a string with
the magic, typically the name of a variable. C<namlen> is stored in the
-C<mg_len> field and if C<name> is non-null and C<namlen> >= 0 a malloc'd
+C<mg_len> field and if C<name> is non-null and C<namlen> E<gt>= 0 a malloc'd
copy of the name is stored in C<mg_ptr> field.
The sv_magic function uses C<how> to determine which, if any, predefined
See the "Magic Virtual Table" section below. The C<how> argument is also
stored in the C<mg_type> field. The value of C<how> should be chosen
from the set of macros C<PERL_MAGIC_foo> found perl.h. Note that before
-these macros were added, perl internals used to directly use character
+these macros were added, Perl internals used to directly use character
literals, so you may occasionally come across old code or documentation
-referr
ring to 'U' magic rather than C<PERL_MAGIC_uvar> for example.
+referring to 'U' magic rather than C<PERL_MAGIC_uvar> for example.
The C<obj> argument is stored in the C<mg_obj> field of the C<MAGIC>
structure. If it is not the same as the C<sv> argument, the reference
count of the C<obj> object is incremented. If it is the same, or if
-the C<how> argument is C<PERL_MAGIC_arylen>", or if it is a NULL pointer,
+the C<how> argument is C<PERL_MAGIC_arylen>, or if it is a NULL pointer,
then C<obj> is merely stored, without the reference count being incremented.
There is also a function to add magic to an C<HV>:
=head2 Magic Virtual Tables
-The C<mg_virtual> field in the C<MAGIC> structure is a pointer to a
+The C<mg_virtual> field in the C<MAGIC> structure is a pointer to an
C<MGVTBL>, which is a structure of function pointers and stands for
"Magic Virtual Table" to handle the various operations that might be
applied to that variable.
Function pointer Action taken
---------------- ------------
- svt_get Do something after the value of the SV is retrieved.
+ svt_get Do something before the value of the SV is retrieved.
svt_set Do something after the SV is assigned a value.
svt_len Report on the SV's length.
svt_clear Clear something the SV represents.
L PERL_MAGIC_dbfile (none) Debugger %_<filename
l PERL_MAGIC_dbline vtbl_dbline Debugger %_<filename element
m PERL_MAGIC_mutex vtbl_mutex ???
- o PERL_MAGIC_collxfrm vtbl_collxfrm Locale transformation
+ o PERL_MAGIC_collxfrm vtbl_collxfrm Locale collate transformation
P PERL_MAGIC_tied vtbl_pack Tied array or hash
p PERL_MAGIC_tiedelem vtbl_packelem Tied array or hash element
q PERL_MAGIC_tiedscalar vtbl_packelem Tied scalar or handle
t PERL_MAGIC_taint vtbl_taint Taintedness
U PERL_MAGIC_uvar vtbl_uvar Available for use by extensions
v PERL_MAGIC_vec vtbl_vec vec() lvalue
+ V PERL_MAGIC_vstring (none) v-string scalars
+ w PERL_MAGIC_utf8 vtbl_utf8 UTF-8 length+offset cache
x PERL_MAGIC_substr vtbl_substr substr() lvalue
y PERL_MAGIC_defelem vtbl_defelem Shadow "foreach" iterator
variable / smart parameter
~ PERL_MAGIC_ext (none) Available for use by extensions
When an uppercase and lowercase letter both exist in the table, then the
-uppercase letter is used to represent some kind of composite type (a list
-or a hash), and the lowercase letter is used to represent an element of
-that composite type. Some internals code makes use of this case
-relationship.
+uppercase letter is typically used to represent some kind of composite type
+(a list or a hash), and the lowercase letter is used to represent an element
+of that composite type. Some internals code makes use of this case
+relationship. However, 'v' and 'V' (vec and v-string) are in no way related.
The C<PERL_MAGIC_ext> and C<PERL_MAGIC_uvar> magic types are defined
specifically for use by extensions and will not be used by perl itself.
C<mg_ptr> field points to a C<ufuncs> structure:
struct ufuncs {
- I32 (*uf_val)(IV, SV*);
- I32 (*uf_set)(IV, SV*);
+ I32 (*uf_val)(pTHX_ IV, SV*);
+ I32 (*uf_set)(pTHX_ IV, SV*);
IV uf_index;
};
aware that the behavior may change in the future, umm, without warning.
The perl tie function associates a variable with an object that implements
-the various GET, SET etc methods. To perform the equivalent of the perl
+the various GET, SET, etc methods. To perform the equivalent of the perl
tie function from an XSUB, you must mimic this behaviour. The code below
carries out the necessary steps - firstly it creates a new hash, and then
creates a second hash which it blesses into the class which will implement
The biggest difference is that the first construction would
reinstate the initial value of $var, irrespective of how control exits
-the block: C<goto>, C<return>, C<die>/C<eval> etc. It is a little bit
+the block: C<goto>, C<return>, C<die>/C<eval>, etc. It is a little bit
more efficient as well.
There is a way to achieve a similar task from C via Perl API: create a
=item C<SV* save_svref(SV **sptr)>
-Similar to C<save_scalar>, but will reinstate a C<SV *>.
+Similar to C<save_scalar>, but will reinstate an C<SV *>.
=item C<void save_aptr(AV **aptr)>
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,
+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.
(initially) one element, and this element is the scratchpad AV. Why do
we need an extra level of indirection?
-The answer is B<recursion>, and maybe (sometime soon) B<threads>. Both
+The answer is B<recursion>, and maybe B<threads>. Both
these can create several execution pointers going into the same
subroutine. For the subroutine-child not write over the temporaries
for the subroutine-parent (lifespan of which covers the call to the
done in the subroutine peep(). Optimizations performed at this stage
are subject to the same restrictions as in the pass 2.
+=head2 Pluggable runops
+
+The compile tree is executed in a runops function. There are two runops
+functions in F<run.c>. C<Perl_runops_debug> is used with DEBUGGING and
+C<Perl_runops_standard> is used otherwise. For fine control over the
+execution of the compile tree it is possible to provide your own runops
+function.
+
+It's probably best to copy one of the existing runops functions and
+change it to suit your needs. Then, in the BOOT section of your XS
+file, add the line:
+
+ PL_runops = my_runops;
+
+This function should be as efficient as possible to keep your programs
+running as fast as possible.
+
=head1 Examining internal data structures with the C<dump> functions
To aid debugging, the source file F<dump.c> contains a number of
module should already be familiar with its format.
C<Perl_op_dump> can be used to dump an C<OP> structure or any of its
-derivatives, and produces output simil
iar to C<perl -Dx>; in fact,
+derivatives, and produces output similar to C<perl -Dx>; in fact,
C<Perl_dump_eval> will dump the main root of the code being evaluated,
exactly like C<-Dx>.
for feeding it code or otherwise making it do things, but it also has
functions for its own use. This smells a lot like an object, and
there are ways for you to build Perl so that you can have multiple
-interpreters, with one interpreter represented either as a C++ object,
-a C structure, or inside a thread. The thread, the C structure, or
-the C++ object will contain all the context, the state of that
-interpreter.
-
-Three macros control the major Perl build flavors: MULTIPLICITY,
-USE_THREADS and PERL_OBJECT. The MULTIPLICITY build has a C structure
-that packages all the interpreter state, there is a similar thread-specific
-data structure under USE_THREADS, and the (now deprecated) PERL_OBJECT
-build has a C++ class to maintain interpreter state. In all three cases,
+interpreters, with one interpreter represented either as a C structure,
+or inside a thread-specific structure. These structures contain all
+the context, the state of that interpreter.
+
+Two macros control the major Perl build flavors: MULTIPLICITY and
+USE_5005THREADS. The MULTIPLICITY build has a C structure
+that packages all the interpreter state, and there is a similar thread-specific
+data structure under USE_5005THREADS. In both cases,
PERL_IMPLICIT_CONTEXT is also normally defined, and enables the
support for passing in a "hidden" first argument that represents all three
data structures.
All this obviously requires a way for the Perl internal functions to be
-C++ methods, subroutines taking some kind of structure as the first
+either subroutines taking some kind of structure as the first
argument, or subroutines taking nothing as the first argument. To
-enable these three very different ways of building the interpreter,
+enable these two very different ways of building the interpreter,
the Perl source (as it does in so many other situations) makes heavy
use of macros and subroutine naming conventions.
STATIC void
S_incline(pTHX_ char *s)
-STATIC becomes "static" in C, and is #define'd to nothing in C++.
+STATIC becomes "static" in C, and may be #define'd to nothing in some
+configurations in future.
A public function (i.e. part of the internal API, but not necessarily
sanctioned for use in extensions) begins like this:
void
- Perl_sv_setsv(pTHX_ SV* dsv, SV* ssv)
+ Perl_sv_setiv(pTHX_ SV* dsv, IV num)
C<pTHX_> is one of a number of macros (in perl.h) that hide the
details of the interpreter's context. THX stands for "thread", "this",
explicit arguments.
When a core function calls another, it must pass the context. This
-is normally hidden via macros. Consider C<sv_setsv>. It expands into
+is normally hidden via macros. Consider C<sv_setiv>. It expands into
something like this:
- ifdef PERL_IMPLICIT_CONTEXT
- define sv_setsv(a,b) Perl_sv_setsv(aTHX_ a, b)
+ #ifdef PERL_IMPLICIT_CONTEXT
+ #define sv_setiv(a,b) Perl_sv_setiv(aTHX_ a, b)
/* can't do this for vararg functions, see below */
- else
- define sv_setsv Perl_sv_setsv
- endif
+ #else
+ #define sv_setiv Perl_sv_setiv
+ #endif
This works well, and means that XS authors can gleefully write:
- sv_setsv(foo, bar);
+ sv_setiv(foo, bar);
and still have it work under all the modes Perl could have been
compiled with.
-Under PERL_OBJECT in the core, that will translate to either:
-
- CPerlObj::Perl_sv_setsv(foo,bar); # in CPerlObj functions,
- # C++ takes care of 'this'
- or
-
- pPerl->Perl_sv_setsv(foo,bar); # in truly static functions,
- # see objXSUB.h
-
-Under PERL_OBJECT in extensions (aka PERL_CAPI), or under
-MULTIPLICITY/USE_THREADS with PERL_IMPLICIT_CONTEXT in both core
-and extensions, it will become:
-
- Perl_sv_setsv(aTHX_ foo, bar); # the canonical Perl "API"
- # for all build flavors
-
This doesn't work so cleanly for varargs functions, though, as macros
imply that the number of arguments is known in advance. Instead we
either need to spell them out fully, passing C<aTHX_> as the first
compatibility at the expense of performance. (Passing an arg is
cheaper than grabbing it from thread-local storage.)
-You can ignore [pad]THX[xo] when browsing the Perl headers/sources.
+You can ignore [pad]THXx when browsing the Perl headers/sources.
Those are strictly for use within the core. Extensions and embedders
need only be aware of [pad]THX.
and aTHX_ macros to call a function that will return the context.
Thus, something like:
- sv_setsv(asv, bsv);
+ sv_setiv(sv, num);
in your extension will translate to this when PERL_IMPLICIT_CONTEXT is
in effect:
- Perl_sv_setsv(Perl_get_context(), asv, bsv);
+ Perl_sv_setiv(Perl_get_context(), sv, num);
or to this otherwise:
- Perl_sv_setsv(asv, bsv);
+ Perl_sv_setiv(sv, num);
You have to do nothing new in your extension to get this; since
the Perl library provides Perl_get_context(), it will all just
that the interpreter knows about itself and pass it around, so too are
there plans to allow the interpreter to bundle up everything it knows
about the environment it's running on. This is enabled with the
-PERL_IMPLICIT_SYS macro. Currently it only works with PERL_OBJECT
-and USE_THREADS on Windows (see inside iperlsys.h).
+PERL_IMPLICIT_SYS macro. Currently it only works with USE_ITHREADS
+and USE_5005THREADS on Windows (see inside iperlsys.h).
This allows the ability to provide an extra pointer (called the "host"
environment) for all the system calls. This makes it possible for
over. You're on your own about bounds checking, though, so don't use it
lightly.
-All bytes in a multi-byte UTF8 character will have the high bit set, so
-you can test if you need to do something special with this character
-like this:
+All bytes in a multi-byte UTF8 character will have the high bit set,
+so you can test if you need to do something special with this
+character like this (the UTF8_IS_INVARIANT() is a macro that tests
+whether the byte can be encoded as a single byte even in UTF-8):
- UV uv;
+ U8 *utf;
+ UV uv; /* Note: a UV, not a U8, not a char */
- if (utf & 0x80)
+ if (!UTF8_IS_INVARIANT(*utf))
/* Must treat this as UTF8 */
uv = utf8_to_uv(utf);
else
value of the character; the inverse function C<uv_to_utf8> is available
for putting a UV into UTF8:
- if (uv > 0x80)
+ if (!UTF8_IS_INVARIANT(uv))
/* Must treat this as UTF8 */
utf8 = uv_to_utf8(utf8, uv);
else
not it's dealing with UTF8 data, so that it can handle the string
appropriately.
+Since just passing an SV to an XS function and copying the data of
+the SV is not enough to copy the UTF8 flags, even less right is just
+passing a C<char *> to an XS function.
+
=head2 How do I convert a string to UTF8?
If you're mixing UTF8 and non-UTF8 strings, you might find it necessary
=item *
If a string is UTF8, B<always> use C<utf8_to_uv> to get at the value,
-unless C<!(*s & 0x80)> in which case you can use C<*s>.
+unless C<UTF8_IS_INVARIANT(*s)> in which case you can use C<*s>.
=item *
-When writing to a UTF8 string, B<always> use C<uv_to_utf8>, unless
-C<uv < 0x80> in which case you can use C<*s = uv>.
+When writing a character C<uv> to a UTF8 string, B<always> use
+C<uv_to_utf8>, unless C<UTF8_IS_INVARIANT(uv))> in which case
+you can use C<*s = uv>.
=item *
=back
+=head1 Custom Operators
+
+Custom operator support is a new experimental feature that allows you to
+define your own ops. This is primarily to allow the building of
+interpreters for other languages in the Perl core, but it also allows
+optimizations through the creation of "macro-ops" (ops which perform the
+functions of multiple ops which are usually executed together, such as
+C<gvsv, gvsv, add>.)
+
+This feature is implemented as a new op type, C<OP_CUSTOM>. The Perl
+core does not "know" anything special about this op type, and so it will
+not be involved in any optimizations. This also means that you can
+define your custom ops to be any op structure - unary, binary, list and
+so on - you like.
+
+It's important to know what custom operators won't do for you. They
+won't let you add new syntax to Perl, directly. They won't even let you
+add new keywords, directly. In fact, they won't change the way Perl
+compiles a program at all. You have to do those changes yourself, after
+Perl has compiled the program. You do this either by manipulating the op
+tree using a C<CHECK> block and the C<B::Generate> module, or by adding
+a custom peephole optimizer with the C<optimize> module.
+
+When you do this, you replace ordinary Perl ops with custom ops by
+creating ops with the type C<OP_CUSTOM> and the C<pp_addr> of your own
+PP function. This should be defined in XS code, and should look like
+the PP ops in C<pp_*.c>. You are responsible for ensuring that your op
+takes the appropriate number of values from the stack, and you are
+responsible for adding stack marks if necessary.
+
+You should also "register" your op with the Perl interpreter so that it
+can produce sensible error and warning messages. Since it is possible to
+have multiple custom ops within the one "logical" op type C<OP_CUSTOM>,
+Perl uses the value of C<< o->op_ppaddr >> as a key into the
+C<PL_custom_op_descs> and C<PL_custom_op_names> hashes. This means you
+need to enter a name and description for your op at the appropriate
+place in the C<PL_custom_op_names> and C<PL_custom_op_descs> hashes.
+
+Forthcoming versions of C<B::Generate> (version 1.0 and above) should
+directly support the creation of custom ops by name; C<Opcodes::Custom>
+will provide functions which make it trivial to "register" custom ops to
+the Perl interpreter.
+
=head1 AUTHORS
Until May 1997, this document was maintained by Jeff Okamoto
-<okamoto@corp.hp.com>. It is now maintained as part of Perl itself
-by the Perl 5 Porters <perl5-porters@perl.org>.
+E<lt>okamoto@corp.hp.comE<gt>. It is now maintained as part of Perl
+itself by the Perl 5 Porters E<lt>perl5-porters@perl.orgE<gt>.
With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
Stephen McCamant, and Gurusamy Sarathy.
-API Listing originally by Dean Roehrich <roehrich@cray.com>.
+API Listing originally by Dean Roehrich E<lt>roehrich@cray.comE<gt>.
Modifications to autogenerate the API listing (L<perlapi>) by Benjamin
Stuhl.
https://perl5.git.perl.org / perl5.git / blobdiff