X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlguts.pod;h=aa32b068481da34add96eb59c955d3dc70fd406b;hb=1e73acc8af3eecb1b36ee831483e1e9a7b3d1662;hp=0d9e2efce69ba00b8399db1cc022af8177455cca;hpb=d7f8936a2fe7fc93635b0b501d1f941d30d3399f;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index 0d9e2ef..aa32b06 100644
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -126,11 +126,11 @@ Also remember that C doesn't allow you to safely say C<foo(SvPV(s, len),
 len);>. It might work with your compiler, but it won't work for everyone.
 Break this sort of statement up into separate assignments:
 
-	SV *s;
-	STRLEN len;
-	char * ptr;
-	ptr = SvPV(s, len);
-	foo(ptr, len);
+    SV *s;
+    STRLEN len;
+    char * ptr;
+    ptr = SvPV(s, len);
+    foo(ptr, len);
 
 If you want to know if the scalar value is TRUE, you can use:
 
@@ -970,7 +970,8 @@ 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.
 
-The C<MGVTBL> has five pointers to the following routine types:
+The C<MGVTBL> has five (or sometimes eight) pointers to the following
+routine types:
 
     int  (*svt_get)(SV* sv, MAGIC* mg);
     int  (*svt_set)(SV* sv, MAGIC* mg);
@@ -978,6 +979,11 @@ The C<MGVTBL> has five pointers to the following routine types:
     int  (*svt_clear)(SV* sv, MAGIC* mg);
     int  (*svt_free)(SV* sv, MAGIC* mg);
 
+    int  (*svt_copy)(SV *sv, MAGIC* mg, SV *nsv, const char *name, int namlen);
+    int  (*svt_dup)(MAGIC *mg, CLONE_PARAMS *param);
+    int  (*svt_local)(SV *nsv, MAGIC *mg);
+
+
 This MGVTBL structure is set at compile-time in F<perl.h> and there are
 currently 19 types (or 21 with overloading turned on).  These different
 structures contain pointers to various routines that perform additional
@@ -991,6 +997,10 @@ actions depending on which function is being called.
     svt_clear		Clear something the SV represents.
     svt_free            Free any extra storage associated with the SV.
 
+    svt_copy		copy tied variable magic to a tied element
+    svt_dup		duplicate a magic structure during thread cloning
+    svt_local		copy magic to local value during 'local'
+
 For instance, the MGVTBL structure called C<vtbl_sv> (which corresponds
 to an C<mg_type> of C<PERL_MAGIC_sv>) contains:
 
@@ -1002,6 +1012,13 @@ called.  All the various routines for the various magical types begin
 with C<magic_>.  NOTE: the magic routines are not considered part of
 the Perl API, and may not be exported by the Perl library.
 
+The last three slots are a recent addition, and for source code
+compatibility they are only checked for if one of the three flags
+MGf_COPY, MGf_DUP or MGf_LOCAL is set in mg_flags. This means that most
+code can continue declaring a vtable as a 5-element value. These three are
+currently used exclusively by the threading code, and are highly subject
+to change.
+
 The current kinds of Magic Virtual Tables are:
 
     mg_type
@@ -1021,6 +1038,8 @@ The current kinds of Magic Virtual Tables are:
     e  PERL_MAGIC_envelem        vtbl_envelem   %ENV hash element
     f  PERL_MAGIC_fm             vtbl_fm        Formline ('compiled' format)
     g  PERL_MAGIC_regex_global   vtbl_mglob     m//g target / study()ed string
+    H  PERL_MAGIC_hints          vtbl_sig       %^H hash
+    h  PERL_MAGIC_hintselem      vtbl_hintselem %^H hash element
     I  PERL_MAGIC_isa            vtbl_isa       @ISA array
     i  PERL_MAGIC_isaelem        vtbl_isaelem   @ISA array element
     k  PERL_MAGIC_nkeys          vtbl_nkeys     scalar(keys()) lvalue
@@ -1043,7 +1062,6 @@ The current kinds of Magic Virtual Tables are:
     y  PERL_MAGIC_defelem        vtbl_defelem   Shadow "foreach" iterator
 						variable / smart parameter
 						vivification
-    *  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   back pointer to a weak ref 
@@ -1093,6 +1111,17 @@ sv_magic, so you can safely allocate it on the stack.
         uf.uf_index = 0;
         sv_magic(sv, 0, PERL_MAGIC_uvar, (char*)&uf, sizeof(uf));
 
+Attaching C<PERL_MAGIC_uvar> to arrays is permissible but has no effect.
+
+For hashes there is a specialized hook that gives control over hash
+keys (but not values).  This hook calls C<PERL_MAGIC_uvar> 'get' magic
+if the "set" function in the C<ufuncs> structure is NULL.  The hook
+is activated whenever the hash is accessed with a key specified as
+an C<SV> through the functions C<hv_store_ent>, C<hv_fetch_ent>,
+C<hv_delete_ent>, and C<hv_exists_ent>.  Accessing the key as a string
+through the functions without the C<..._ent> suffix circumvents the
+hook.  See L<Hash::Util::Fieldhash/Guts> for a detailed description.
+
 Note that because multiple extensions may be using C<PERL_MAGIC_ext>
 or C<PERL_MAGIC_uvar> magic, it is important for extensions to take
 extra care to avoid conflict.  Typically only using the magic on
@@ -2167,16 +2196,18 @@ after that are the arguments. The first column is a set of flags:
 
 =item A
 
-This function is a part of the public API.
+This function is a part of the public API. All such functions should also
+have 'd', very few do not.
 
 =item p
 
-This function has a C<Perl_> prefix; i.e. 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
 
 This function has documentation using the C<apidoc> feature which we'll
-look at in a second.
+look at in a second.  Some functions have 'd' but not 'A'; docs are good.
 
 =back
 
@@ -2186,12 +2217,13 @@ Other available flags are:
 
 =item s
 
-This is a static function and is defined as C<S_whatever>, and usually
-called within the sources as C<whatever(...)>.
+This is a static function and is defined as C<STATIC S_whatever>, and
+usually called within the sources as C<whatever(...)>.
 
 =item n
 
-This does not use C<aTHX_> and C<pTHX> to pass interpreter context. (See
+This does not need a interpreter context, so the definition has no
+C<pTHX>, and it follows that callers don't use C<aTHX>.  (See
 L<perlguts/Background and PERL_IMPLICIT_CONTEXT>.)
 
 =item r
@@ -2236,6 +2268,10 @@ This function is visible to extensions included in the Perl core.
 Binary backward compatibility; this function is a macro but also has
 a C<Perl_> implementation (which is exported).
 
+=item others
+
+See the comments at the top of C<embed.fnc> for others.
+
 =back
 
 If you edit F<embed.pl> or F<embed.fnc>, you will need to run
@@ -2579,7 +2615,7 @@ 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>.) 
+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
@@ -2611,9 +2647,7 @@ 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.
+directly support the creation of custom ops by name.
 
 =head1 AUTHORS