SvOK(SV*)
The scalar C<undef> value is stored in an SV instance called C<PL_sv_undef>.
-Its address can be used whenever an C<SV*> is needed.
-However, you have to be careful when using C<&PL_sv_undef> as a value in AVs
-or HVs (see L<AVs, HVs and undefined values>).
+
+Its address can be used whenever an C<SV*> is needed. Make sure that
+you don't try to compare a random sv with C<&PL_sv_undef>. For example
+when interfacing Perl code, it'll work correctly for:
+
+ foo(undef);
+
+But won't work when called as:
+
+ $x = undef;
+ foo($x);
+
+So to repeat always use SvOK() to check whether an sv is defined.
+
+Also you have to be careful when using C<&PL_sv_undef> as a value in
+AVs or HVs (see L<AVs, HVs and undefined values>).
There are also the two values C<PL_sv_yes> and C<PL_sv_no>, which contain
boolean TRUE and FALSE values, respectively. Like C<PL_sv_undef>, their
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
+numeric conversion has occurred 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.
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> E<gt>= 0 a malloc'd
-copy of the name is stored in C<mg_ptr> field.
+C<mg_len> field and if C<name> is non-null then either a C<savepvn> copy of
+C<name> or C<name> itself is stored in the C<mg_ptr> field, depending on
+whether C<namlen> is greater than zero or equal to zero respectively. As a
+special case, if C<(name && namlen == HEf_SVKEY)> then C<name> is assumed
+to contain an C<SV*> and is stored as-is with its REFCNT incremented.
The sv_magic function uses C<how> to determine which, if any, predefined
"Magic Virtual Table" should be assigned to the C<mg_virtual> field.
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.
+See also C<sv_magicext> in L<perlapi> for a more flexible way to add magic
+to an SV.
+
There is also a function to add magic to an C<HV>:
void hv_magic(HV *hv, GV *gv, int how);
* PERL_MAGIC_glob vtbl_glob GV (typeglob)
# PERL_MAGIC_arylen vtbl_arylen Array length ($#ary)
. PERL_MAGIC_pos vtbl_pos pos() lvalue
- < PERL_MAGIC_backref vtbl_backref ???
+ < PERL_MAGIC_backref vtbl_backref back pointer to a weak ref
~ PERL_MAGIC_ext (none) Available for use by extensions
+ : PERL_MAGIC_symtab (none) hash used as symbol table
+ % PERL_MAGIC_rhash (none) hash used as restricted hash
+ @ PERL_MAGIC_arylen_p vtbl_arylen_p pointer to $#a from @a
+
When an uppercase and lowercase letter both exist in the table, then the
uppercase letter is typically used to represent some kind of composite type
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.
+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)>
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>).
+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)))
- PUSHs(sv_2mortal(newSVnv(3.141592)))
And now the Perl program calling C<tzname>, the two values will be assigned
as in:
do not need to call C<EXTEND> to extend the stack.
Despite their suggestions in earlier versions of this document the macros
-C<PUSHi>, C<PUSHn> and C<PUSHp> are I<not> suited to XSUBs which return
-multiple results, see L</Putting a C value on Perl stack>.
+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>.
The following three macros are used to initially allocate memory :
- New(x, pointer, number, type);
- Newc(x, pointer, number, type, cast);
- Newz(x, pointer, number, type);
-
-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 (most Perl developers now
-use run-time memory checkers), so this argument can be any number.
+ Newx(pointer, number, type);
+ Newxc(pointer, number, type, cast);
+ Newxz(pointer, number, type);
-The second argument C<pointer> should be the name of a variable that will
+The first argument C<pointer> should be the name of a variable that will
point to the newly allocated memory.
-The third and fourth arguments C<number> and C<type> specify how many of
+The second and third arguments C<number> and C<type> specify how many of
the specified type of data structure should be allocated. The argument
-C<type> is passed to C<sizeof>. The final argument to C<Newc>, C<cast>,
+C<type> is passed to C<sizeof>. The final argument to C<Newxc>, C<cast>,
should be used if the C<pointer> argument is different from the C<type>
argument.
-Unlike the C<New> and C<Newc> macros, the C<Newz> macro calls C<memzero>
+Unlike the C<Newx> and C<Newxc> macros, the C<Newxz> macro calls C<memzero>
to zero out all the newly allocated memory.
=head3 Reallocation
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[pni]>.
+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:
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, use C<XPUSHs>,
-which bypasses C<TARG>.
+to 20.
-On a related note, if you do use C<(X)PUSH[npi]>, then you're going to
+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>.
+macros can make use of the local variable C<TARG>. See also C<dTARGET>
+and C<dXSTARG>.
=head2 Scratchpads
=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.
+functions, in F<run.c> and in F<dump.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
support for passing in a "hidden" first argument that represents all three
data structures.
+Two other "encapsulation" macros are the PERL_GLOBAL_STRUCT and
+PERL_GLOBAL_STRUCT_PRIVATE (the latter turns on the former, and the
+former turns on MULTIPLICITY.) The PERL_GLOBAL_STRUCT causes all the
+internal variables of Perl to be wrapped inside a single global struct,
+struct perl_vars, accessible as (globals) &PL_Vars or PL_VarsPtr or
+the function Perl_GetVars(). The PERL_GLOBAL_STRUCT_PRIVATE goes
+one step further, there is still a single struct (allocated in main()
+either from heap or from stack) but there are no global data symbols
+pointing to it. In either case the global struct should be initialised
+as the very first thing in main() using Perl_init_global_struct() and
+correspondingly tear it down after perl_free() using Perl_free_global_struct(),
+please see F<miniperlmain.c> for usage details. You may also need
+to use C<dVAR> in your coding to "declare the global variables"
+when you are using them. dTHX does this for you automatically.
+
+For backward compatibility reasons defining just PERL_GLOBAL_STRUCT
+doesn't actually hide all symbols inside a big global struct: some
+PerlIO_xxx vtables are left visible. The PERL_GLOBAL_STRUCT_PRIVATE
+then hides everything (see how the PERLIO_FUNCS_DECL is used).
+
All this obviously requires a way for the Perl internal functions to be
either subroutines taking some kind of structure as the first
argument, or subroutines taking nothing as the first argument. To
macro with the underscore for functions that take explicit arguments,
or the form without the argument for functions with no explicit arguments.
+If one is compiling Perl with the C<-DPERL_GLOBAL_STRUCT> the C<dVAR>
+definition is needed if the Perl global variables (see F<perlvars.h>
+or F<globvar.sym>) are accessed in the function and C<dTHX> is not
+used (the C<dTHX> includes the C<dVAR> if necessary). One notices
+the need for C<dVAR> only with the said compile-time define, because
+otherwise the Perl global variables are visible as-is.
+
=head2 Should I do anything special if I call perl from multiple threads?
If you create interpreters in one thread and then proceed to call them in
=item p
-This function has a C<Perl_> prefix; ie, it is defined as C<Perl_av_fetch>
+This function has a C<Perl_> prefix; i.e. it is defined as C<Perl_av_fetch>
=item d
AV *av = ...;
UV uv = PTR2UV(av);
+=head2 Exception Handling
+
+There are a couple of macros to do very basic exception handling in XS
+modules. You have to define C<NO_XSLOCKS> before including F<XSUB.h> to
+be able to use these macros:
+
+ #define NO_XSLOCKS
+ #include "XSUB.h"
+
+You can use these macros if you call code that may croak, but you need
+to do some cleanup before giving control back to Perl. For example:
+
+ dXCPT; /* set up necessary variables */
+
+ XCPT_TRY_START {
+ code_that_may_croak();
+ } XCPT_TRY_END
+
+ XCPT_CATCH
+ {
+ /* do cleanup here */
+ XCPT_RETHROW;
+ }
+
+Note that you always have to rethrow an exception that has been
+caught. Using these macros, it is not possible to just catch the
+exception and ignore it. If you have to ignore the exception, you
+have to use the C<call_*> function.
+
+The advantage of using the above macros is that you don't have
+to setup an extra function for C<call_*>, and that using these
+macros is faster than using C<call_*>.
+
=head2 Source Documentation
There's an effort going on to document the internal functions and
Please try and supply some documentation if you add functions to the
Perl core.
+=head2 Backwards compatibility
+
+The Perl API changes over time. New functions are added or the interfaces
+of existing functions are changed. The C<Devel::PPPort> module tries to
+provide compatibility code for some of these changes, so XS writers don't
+have to code it themselves when supporting multiple versions of Perl.
+
+C<Devel::PPPort> generates a C header file F<ppport.h> that can also
+be run as a Perl script. To generate F<ppport.h>, run:
+
+ perl -MDevel::PPPort -eDevel::PPPort::WriteFile
+
+Besides checking existing XS code, the script can also be used to retrieve
+compatibility information for various API calls using the C<--api-info>
+command line switch. For example:
+
+ % perl ppport.h --api-info=sv_magicext
+
+For details, see C<perldoc ppport.h>.
+
=head1 Unicode Support
Perl 5.6.0 introduced Unicode support. It's important for porters and XS
projects / p5sagit/p5-mst-13.2.git / blobdiff