uvchr_to_utf8() and utf8n_to_uvchr() are mathoms on ASCII based

[perl5.git] / pod / perlxs.pod

diff --git a/pod/perlxs.pod b/pod/perlxs.pod
index e5f5f75..7360c57 100644 (file)
--- a/pod/perlxs.pod
+++ b/pod/perlxs.pod
@@ -276,6 +276,63 @@ some heuristic code which tries to disambiguate between "truly-void"
 and "old-practice-declared-as-void" functions. Hence your code is at
 mercy of this heuristics unless you use C<SV *> as return value.)
 
 and "old-practice-declared-as-void" functions. Hence your code is at
 mercy of this heuristics unless you use C<SV *> as return value.)
 

+=head2 Returning SVs, AVs and HVs through RETVAL
+
+When you're using RETVAL to return an C<SV *>, there's some magic
+going on behind the scenes that should be mentioned. When you're
+manipulating the argument stack using the ST(x) macro, for example,
+you usually have to pay special attention to reference counts. (For
+more about reference counts, see L<perlguts>.) To make your life
+easier, the typemap file automatically makes C<RETVAL> mortal when
+you're returning an C<SV *>. Thus, the following two XSUBs are more
+or less equivalent:
+
+  void
+  alpha()
+      PPCODE:
+          ST(0) = newSVpv("Hello World",0);
+          sv_2mortal(ST(0));
+          XSRETURN(1);
+  
+  SV *
+  beta()
+      CODE:
+          RETVAL = newSVpv("Hello World",0);
+      OUTPUT:
+          RETVAL
+
+This is quite useful as it usually improves readability. While
+this works fine for an C<SV *>, it's unfortunately not as easy
+to have C<AV *> or C<HV *> as a return value. You I<should> be
+able to write:
+
+  AV *
+  array()
+      CODE:
+          RETVAL = newAV();
+          /* do something with RETVAL */
+      OUTPUT:
+          RETVAL
+
+But due to an unfixable bug (fixing it would break lots of existing
+CPAN modules) in the typemap file, the reference count of the C<AV *>
+is not properly decremented. Thus, the above XSUB would leak memory
+whenever it is being called. The same problem exists for C<HV *>.
+
+When you're returning an C<AV *> or a C<HV *>, you have make sure
+their reference count is decremented by making the AV or HV mortal:
+
+  AV *
+  array()
+      CODE:
+          RETVAL = newAV();
+          sv_2mortal((SV*)RETVAL);
+          /* do something with RETVAL */
+      OUTPUT:
+          RETVAL
+
+And also remember that you don't have to do this for an C<SV *>.
+

 =head2 The MODULE Keyword
 
 The MODULE keyword is used to start the XS code and to specify the package
 =head2 The MODULE Keyword
 
 The MODULE keyword is used to start the XS code and to specify the package


@@ -310,6 +367,10 @@ keyword and must follow immediately after it when used.
 
      [ XS code in package RPC ]
 
 
      [ XS code in package RPC ]
 

+The same package name can be used more than once, allowing for
+non-contiguous code. This is useful if you have a stronger ordering
+principle than package names.
+

 Although this keyword is optional and in some cases provides redundant
 information it should always be used.  This keyword will ensure that the
 XSUBs appear in the desired package.
 Although this keyword is optional and in some cases provides redundant
 information it should always be used.  This keyword will ensure that the
 XSUBs appear in the desired package.


@@ -843,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
 
 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
 the generated Perl function is called.  E.g.,
 
   void


@@ -1060,8 +1121,8 @@ then not push return values on the stack.
 Some people may be inclined to include an explicit C<return> in the above
 XSUB, rather than letting control fall through to the end.  In those
 situations C<XSRETURN_EMPTY> should be used, instead.  This will ensure that
 Some people may be inclined to include an explicit C<return> in the above
 XSUB, rather than letting control fall through to the end.  In those
 situations C<XSRETURN_EMPTY> should be used, instead.  This will ensure that

-the XSUB stack is properly adjusted.  Consult L<perlguts/"API LISTING"> for
-other C<XSRETURN> macros.
+the XSUB stack is properly adjusted.  Consult L<perlapi> for other
+C<XSRETURN> macros.

 
 Since C<XSRETURN_*> macros can be used with CODE blocks as well, one can
 rewrite this example as:
 
 Since C<XSRETURN_*> macros can be used with CODE blocks as well, one can
 rewrite this example as:


@@ -1190,6 +1251,14 @@ prototypes.
           timep
           RETVAL
 
           timep
           RETVAL
 

+If the prototypes are enabled, you can disable it locally for a given
+XSUB as in the following example:
+
+    void
+    rpcb_gettime_noproto()
+        PROTOTYPE: DISABLE
+    ...
+

 =head2 The ALIAS: Keyword
 
 The ALIAS: keyword allows an XSUB to have two or more unique Perl names
 =head2 The ALIAS: Keyword
 
 The ALIAS: keyword allows an XSUB to have two or more unique Perl names


@@ -1248,6 +1317,23 @@ characters, you must type the parameter without quoting, seperating
 multiple overloads with whitespace.  Note that "" (the stringify 
 overload) should be entered as \"\" (i.e. escaped).
 
 multiple overloads with whitespace.  Note that "" (the stringify 
 overload) should be entered as \"\" (i.e. escaped).
 

+=head2 The FALLBACK: Keyword
+
+In addition to the OVERLOAD keyword, if you need to control how
+Perl autogenerates missing overloaded operators, you can set the
+FALLBACK keyword in the module header section, like this:
+
+    MODULE = RPC  PACKAGE = RPC
+
+    FALLBACK: TRUE
+    ...
+
+where FALLBACK can take any of the three values TRUE, FALSE, or
+UNDEF.  If you do not set any FALLBACK value when using OVERLOAD,
+it defaults to UNDEF.  FALLBACK is not used except when one or 
+more functions using OVERLOAD have been defined.  Please see
+L<overload/Fallback> for more details.
+

 =head2 The INTERFACE: Keyword
 
 This keyword declares the current XSUB as a keeper of the given
 =head2 The INTERFACE: Keyword
 
 This keyword declares the current XSUB as a keeper of the given


@@ -1747,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));
         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}\")
                 }
                 else
                         croak(\"$var is not of type ${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")


@@ -1761,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.
 
 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
 =head2 Safely Storing Static Data in XS
 
 Starting with Perl 5.8, a macro framework has been defined to allow