Add all new utilities in the perlutil man page.

[perl5.git] / pod / perlxs.pod

diff --git a/pod/perlxs.pod b/pod/perlxs.pod
index c09947d..e6f1862 100644 (file)
--- a/pod/perlxs.pod
+++ b/pod/perlxs.pod
@@ -588,7 +588,7 @@ Here's a truly obscure example:
 
      bool_t
      rpcb_gettime(host,timep)
-          time_t &timep ; /* \$v{timep}=@{[$v{timep}=$arg]} */
+          time_t &timep; /* \$v{timep}=@{[$v{timep}=$arg]} */
           char *host + SvOK($v{timep}) ? SvPV($arg,PL_na) : NULL;
         OUTPUT:
           timep
@@ -904,7 +904,7 @@ However, the generated Perl function is called in very C-ish style:
 
 If one of the input arguments to the C function is the length of a string
 argument C<NAME>, one can substitute the name of the length-argument by
-C<length(NAME)> in the XSUB declaration.  This argument must be omited when
+C<length(NAME)> in the XSUB declaration.  This argument must be omitted when
 the generated Perl function is called.  E.g.,
 
   void
@@ -1833,7 +1833,7 @@ double-colons (::), and declare C<Net_Config> to be of that type:
         T_PTROBJ_SPECIAL
                 if (sv_derived_from($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")) {
                         IV tmp = SvIV((SV*)SvRV($arg));
-                $var = ($type) tmp;
+                        $var = INT2PTR($type, tmp);
                 }
                 else
                         croak(\"$var is not of type ${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")
@@ -1847,6 +1847,11 @@ The INPUT and OUTPUT sections substitute underscores for double-colons
 on the fly, giving the desired effect.  This example demonstrates some
 of the power and versatility of the typemap facility.
 
+The INT2PTR macro (defined in perl.h) casts an integer to a pointer, 
+of a given type, taking care of the possible different size of integers
+and pointers.  There are also PTR2IV, PTR2UV, PTR2NV macros,
+to map the other way, which may be useful in OUTPUT sections.
+
 =head2 Safely Storing Static Data in XS
 
 Starting with Perl 5.8, a macro framework has been defined to allow
@@ -1897,7 +1902,7 @@ Below is an example module that makes use of the macros.
           dMY_CXT;
         CODE:
           if (MY_CXT.count >= 3) {
-              warn("Already have 3 blind mice") ;
+              warn("Already have 3 blind mice");
               RETVAL = 0;
           }
           else {
@@ -1916,6 +1921,10 @@ Below is an example module that makes use of the macros.
         else
           RETVAL = newSVpv(MY_CXT.name[index - 1]);
 
+    void
+    CLONE(...)
+       CODE:
+       MY_CXT_CLONE;
 
 B<REFERENCE>
 
@@ -1951,7 +1960,10 @@ of C<my_cxt_t>.
 
 The MY_CXT_INIT macro initialises storage for the C<my_cxt_t> struct.
 
-It I<must> be called exactly once -- typically in a BOOT: section.
+It I<must> be called exactly once -- typically in a BOOT: section. If you
+are maintaining multiple interpreters, it should be called once in each
+interpreter instance, except for interpreters cloned from existing ones.
+(But see C<MY_CXT_CLONE> below.)
 
 =item dMY_CXT
 
@@ -1972,8 +1984,47 @@ then use this to access the C<index> member
     dMY_CXT;
     MY_CXT.index = 2;
 
+=item aMY_CXT/pMY_CXT
+
+C<dMY_CXT> may be quite expensive to calculate, and to avoid the overhead
+of invoking it in each function it is possible to pass the declaration
+onto other functions using the C<aMY_CXT>/C<pMY_CXT> macros, eg
+
+    void sub1() {
+       dMY_CXT;
+       MY_CXT.index = 1;
+       sub2(aMY_CXT);
+    }
+
+    void sub2(pMY_CXT) {
+       MY_CXT.index = 2;
+    }
+
+Analogously to C<pTHX>, there are equivalent forms for when the macro is the
+first or last in multiple arguments, where an underscore represents a
+comma, i.e.  C<_aMY_CXT>, C<aMY_CXT_>, C<_pMY_CXT> and C<pMY_CXT_>.
+
+=item MY_CXT_CLONE
+
+By default, when a new interpreter is created as a copy of an existing one
+(eg via C<<threads->new()>>), both interpreters share the same physical
+my_cxt_t structure. Calling C<MY_CXT_CLONE> (typically via the package's
+C<CLONE()> function), causes a byte-for-byte copy of the structure to be
+taken, and any future dMY_CXT will cause the copy to be accessed instead.
+
+=item MY_CXT_INIT_INTERP(my_perl)
+
+=item dMY_CXT_INTERP(my_perl)
+
+These are versions of the macros which take an explicit interpreter as an
+argument.
+
 =back
 
+Note that these macros will only work together within the I<same> source
+file; that is, a dMY_CTX in one source file will access a different structure
+than a dMY_CTX in another source file.
+
 =head1 EXAMPLES
 
 File C<RPC.xs>: Interface to some ONC+ RPC bind library functions.