These will tell you if you truly have an integer, double, or string pointer
stored in your SV. The "p" stands for private.
+The are various ways in which the private and public flags may differ.
+For example, a tied SV may have a valid underlying value in the IV slot
+(so SvIOKp is true), but the data should be accessed via the FETCH
+routine rather than directly, so SvIOK is false. Another is when
+numeric conversion has occured and precision has been lost: only the
+private flag is set on 'lossy' values. So when an NV is converted to an
+IV with loss, SvIOKp, SvNOKp and SvNOK will be set, while SvIOK wont be.
+
In general, though, it's best to use the C<Sv*V> macros.
=head2 Working with AVs
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
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
referrring 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>:
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
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;
};
tie = newRV_noinc((SV*)newHV());
stash = gv_stashpv("MyTie", TRUE);
sv_bless(tie, stash);
- hv_magic(hash, tie, PERL_MAGIC_tied);
+ hv_magic(hash, (GV*)tie, PERL_MAGIC_tied);
RETVAL = newRV_noinc(hash);
OUTPUT:
RETVAL
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 values pushed will often need to be "mortal" (See L</Reference Counts and Mortality).
+macro. The values pushed will often need to be "mortal" (See L</Reference Counts and Mortality>).
PUSHs(sv_2mortal(newSViv(an_integer)))
PUSHs(sv_2mortal(newSVpv("Some String",0)))
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
interpreter.
Three macros control the major Perl build flavors: MULTIPLICITY,
-USE_THREADS and PERL_OBJECT. The MULTIPLICITY build has a C structure
+USE_5005THREADS 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
+data structure under USE_5005THREADS, and the (now deprecated) PERL_OBJECT
build has a C++ class to maintain interpreter state. In all three cases,
PERL_IMPLICIT_CONTEXT is also normally defined, and enables the
support for passing in a "hidden" first argument that represents all three
# see objXSUB.h
Under PERL_OBJECT in extensions (aka PERL_CAPI), or under
-MULTIPLICITY/USE_THREADS with PERL_IMPLICIT_CONTEXT in both core
+MULTIPLICITY/USE_5005THREADS with PERL_IMPLICIT_CONTEXT in both core
and extensions, it will become:
Perl_sv_setsv(aTHX_ foo, bar); # the canonical Perl "API"
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).
+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
=back
+=head1 Custom Operators
+
+Custom operator support is a new experimental feature that allows you do
+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>.) Currently, this feature must be enabled with the C
+flag C<-DPERL_CUSTOM_OPS>.
+
+Enabling the feature will create 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
projects / p5sagit/p5-mst-13.2.git / blobdiff