This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
fix several problems in the MY_CXT example in perlxs.pod
[perl5.git] / dist / ExtUtils-ParseXS / lib / perlxs.pod
index 085536e..12e2227 100644 (file)
@@ -61,7 +61,8 @@ uses B<typemaps> to determine how to map C function parameters
 and output values to Perl values and back.  The default typemap
 (which comes with Perl) handles many common C types.  A supplementary
 typemap may also be needed to handle any special structures and types
-for the library being linked.
+for the library being linked. For more information on typemaps,
+see L<perlxstypemap>.
 
 A file in XS format starts with a C language section which goes until the
 first C<MODULE =Z<>> directive.  Other XS directives and XSUB definitions
@@ -197,7 +198,7 @@ different semantics, see L<"The & Unary Operator">.
 
 It is convenient to think that the indirection operator
 C<*> should be considered as a part of the type and the address operator C<&>
-should be considered part of the variable.  See L<"The Typemap">
+should be considered part of the variable.  See L<perlxstypemap>
 for more info about handling qualifiers and unary operators in C types.
 
 The function name and the return type must be placed on
@@ -317,10 +318,19 @@ able to write:
 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 *>.
+whenever it is being called. The same problem exists for C<HV *>,
+C<CV *>, and C<SVREF> (which indicates a scalar reference, not
+a general C<SV *>).
+In XS code on perls starting with perl 5.16, you can override the
+typemaps for any of these types with a version that has proper
+handling of refcounts. In your C<TYPEMAP> section, do
 
-When you're returning an C<AV *> or a C<HV *>, you have to make sure
-their reference count is decremented by making the AV or HV mortal:
+  AV*  T_AVREF_REFCOUNT_FIXED
+
+to get the repaired variant. For backward compatibility with older
+versions of perl, you can instead decrement the reference count
+manually when you're returning one of the aforementioned
+types using C<sv_2mortal>:
 
   AV *
   array()
@@ -331,7 +341,8 @@ their reference count is decremented by making the AV or HV mortal:
       OUTPUT:
           RETVAL
 
-And also remember that you don't have to do this for an C<SV *>.
+Remember that you don't have to do this for an C<SV *>. The reference
+documentation for all core typemaps can be found in L<perlxstypemap>.
 
 =head2 The MODULE Keyword
 
@@ -545,7 +556,7 @@ not care about its initial contents.
 Starting with Perl 5.16, you can embed typemaps into your XS code
 instead of or in addition to typemaps in a separate file.  Multiple
 such embedded typemaps will be processed in order of appearance in
-the XS code and like local typemap files take precendence over the
+the XS code and like local typemap files take precedence over the
 default typemap, the embedded typemaps may overwrite previous
 definitions of TYPEMAP, INPUT, and OUTPUT stanzas.  The syntax for
 embedded typemaps is
@@ -557,7 +568,7 @@ embedded typemaps is
 where the C<TYPEMAP> keyword must appear in the first column of a
 new line.
 
-Refer to the section on L<The Typemap> for details on writing typemaps.
+Refer to L<perlxstypemap> for details on writing typemaps.
 
 =head2 Initializing Function Parameters
 
@@ -576,8 +587,8 @@ The following code demonstrates how to supply initialization code for
 function parameters.  The initialization code is eval'ed within double
 quotes by the compiler before it is added to the output so anything
 which should be interpreted literally [mainly C<$>, C<@>, or C<\\>]
-must be protected with backslashes.  The variables $var, $arg,
-and $type can be used as in typemaps.
+must be protected with backslashes.  The variables C<$var>, C<$arg>,
+and C<$type> can be used as in typemaps.
 
      bool_t
      rpcb_gettime(host,timep)
@@ -617,7 +628,7 @@ example has a two-fold purpose: first, when this line is processed by
 B<xsubpp>, the Perl snippet C<$v{timep}=$arg> is evaluated.  Second,
 the text of the evaluated snippet is output into the generated C file
 (inside a C comment)!  During the processing of C<char *host> line,
-$arg will evaluate to C<ST(0)>, and C<$v{timep}> will evaluate to
+C<$arg> will evaluate to C<ST(0)>, and C<$v{timep}> will evaluate to
 C<ST(1)>.
 
 =head2 Default Parameter Values
@@ -1319,7 +1330,7 @@ register with the overload magic.
 
 Since blessed objects are actually stored as RV's, it is useful
 to use the typemap features to preprocess parameters and extract
-the actual SV stored within the blessed RV. See the sample for
+the actual SV stored within the blessed RV.  See the sample for
 T_PTROBJ_SPECIAL below.
 
 To use the OVERLOAD: keyword, create an XS function which takes
@@ -1680,7 +1691,7 @@ called and C<THIS> will be given as its parameter.  The generated C++ code for
 
 will look like this:
 
-     color *THIS = ...;        // Initialized as in typemap
+     color *THIS = ...;  // Initialized as in typemap
 
      delete THIS;
 
@@ -1700,22 +1711,23 @@ The following is an example of a typemap that could be used for this C++
 example.
 
     TYPEMAP
-    color *            O_OBJECT
+    color *  O_OBJECT
 
     OUTPUT
     # The Perl object is blessed into 'CLASS', which should be a
     # char* having the name of the package for the blessing.
     O_OBJECT
-       sv_setref_pv( $arg, CLASS, (void*)$var );
+        sv_setref_pv( $arg, CLASS, (void*)$var );
 
     INPUT
     O_OBJECT
-       if( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) )
-               $var = ($type)SvIV((SV*)SvRV( $arg ));
-       else{
-               warn( \"${Package}::$func_name() -- $var is not a blessed SV reference\" );
-               XSRETURN_UNDEF;
-       }
+        if( sv_isobject($arg) && (SvTYPE(SvRV($arg)) == SVt_PVMG) )
+            $var = ($type)SvIV((SV*)SvRV( $arg ));
+        else{
+            warn("${Package}::$func_name() -- " .
+                "$var is not a blessed SV reference");
+            XSRETURN_UNDEF;
+        }
 
 =head2 Interface Strategy
 
@@ -1823,8 +1835,9 @@ trim the name to the word DESTROY as Perl will expect.
           printf("Now in NetconfigPtr::DESTROY\n");
           free( netconf );
 
-This example requires the following typemap entry.  Consult the typemap
-section for more information about adding new typemaps for an extension.
+This example requires the following typemap entry.  Consult
+L<perlxstypemap> for more information about adding new typemaps
+for an extension.
 
      TYPEMAP
      Netconfig *  T_PTROBJ
@@ -1840,78 +1853,6 @@ does not care, that this object is a C struct and not a Perl object.  In
 this sense, there is no difference between the object created by the
 getnetconfigent() XSUB and an object created by a normal Perl subroutine.
 
-=head2 The Typemap
-
-The typemap is a collection of code fragments which are used by the B<xsubpp>
-compiler to map C function parameters and values to Perl values.  The
-typemap file may consist of three sections labelled C<TYPEMAP>, C<INPUT>, and
-C<OUTPUT>.  An unlabelled initial section is assumed to be a C<TYPEMAP>
-section.  The INPUT section tells
-the compiler how to translate Perl values
-into variables of certain C types.  The OUTPUT section tells the compiler
-how to translate the values from certain C types into values Perl can
-understand.  The TYPEMAP section tells the compiler which of the INPUT and
-OUTPUT code fragments should be used to map a given C type to a Perl value.
-The section labels C<TYPEMAP>, C<INPUT>, or C<OUTPUT> must begin
-in the first column on a line by themselves, and must be in uppercase.
-
-The default typemap in the F<lib/ExtUtils> directory of the Perl source
-contains many useful types which can be used by Perl extensions.  Some
-extensions define additional typemaps which they keep in their own directory.
-These additional typemaps may reference INPUT and OUTPUT maps in the main
-typemap.  The B<xsubpp> compiler will allow the extension's own typemap to
-override any mappings which are in the default typemap.  Instead of using
-an additional F<typemap> file, typemaps may be embedded verbatim in XS
-with a heredoc-like syntax.  See the documentation on the C<TYPEMAP:> XS
-keyword.
-
-Most extensions which require a custom typemap will need only the TYPEMAP
-section of the typemap file.  The custom typemap used in the
-getnetconfigent() example shown earlier demonstrates what may be the typical
-use of extension typemaps.  That typemap is used to equate a C structure
-with the T_PTROBJ typemap.  The typemap used by getnetconfigent() is shown
-here.  Note that the C type is separated from the XS type with a tab and
-that the C unary operator C<*> is considered to be a part of the C type name.
-
-       TYPEMAP
-       Netconfig *<tab>T_PTROBJ
-
-Here's a more complicated example: suppose that you wanted C<struct
-netconfig> to be blessed into the class C<Net::Config>.  One way to do
-this is to use underscores (_) to separate package names, as follows:
-
-        typedef struct netconfig * Net_Config;
-
-And then provide a typemap entry C<T_PTROBJ_SPECIAL> that maps underscores to
-double-colons (::), and declare C<Net_Config> to be of that type:
-
-
-        TYPEMAP
-        Net_Config      T_PTROBJ_SPECIAL
-
-        INPUT
-        T_PTROBJ_SPECIAL
-                if (sv_derived_from($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")) {
-                        IV tmp = SvIV((SV*)SvRV($arg));
-                        $var = INT2PTR($type, tmp);
-                }
-                else
-                        croak(\"$var is not of type ${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")
-
-        OUTPUT
-        T_PTROBJ_SPECIAL
-                sv_setref_pv($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\",
-                (void*)$var);
-
-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
@@ -1957,7 +1898,6 @@ Below is an example module that makes use of the macros.
 
     int
     newMouse(char * name)
-        char * name;
         PREINIT:
           dMY_CXT;
         CODE:
@@ -1969,24 +1909,28 @@ Below is an example module that makes use of the macros.
               RETVAL = ++ MY_CXT.count;
               strcpy(MY_CXT.name[MY_CXT.count - 1], name);
           }
+        OUTPUT:
+          RETVAL
 
     char *
     get_mouse_name(index)
-      int index
-      CODE:
-        dMY_CXT;
-        RETVAL = MY_CXT.lives ++;
-        if (index > MY_CXT.count)
-          croak("There are only 3 blind mice.");
-        else
-          RETVAL = newSVpv(MY_CXT.name[index - 1]);
+          int index
+        PREINIT:
+          dMY_CXT;
+        CODE:
+          if (index > MY_CXT.count)
+            croak("There are only 3 blind mice.");
+          else
+            RETVAL = MY_CXT.name[index - 1];
+        OUTPUT:
+          RETVAL
 
     void
     CLONE(...)
        CODE:
-       MY_CXT_CLONE;
+         MY_CXT_CLONE;
 
-B<REFERENCE>
+=head3 MY_CXT REFERENCE
 
 =over 5
 
@@ -2018,7 +1962,7 @@ of C<my_cxt_t>.
 
 =item MY_CXT_INIT
 
-The MY_CXT_INIT macro initialises storage for the C<my_cxt_t> struct.
+The MY_CXT_INIT macro initializes storage for the C<my_cxt_t> struct.
 
 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
@@ -2139,7 +2083,7 @@ File C<RPC.xs>: Interface to some ONC+ RPC bind library functions.
           printf("NetconfigPtr::DESTROY\n");
           free( netconf );
 
-File C<typemap>: Custom typemap for RPC.xs.
+File C<typemap>: Custom typemap for RPC.xs. (cf. L<perlxstypemap>)
 
      TYPEMAP
      Netconfig *  T_PTROBJ
@@ -2173,7 +2117,8 @@ File C<rpctest.pl>: Perl test program for the RPC extension.
 
 =head1 XS VERSION
 
-This document covers features supported by C<xsubpp> 1.935.
+This document covers features supported by C<ExtUtils::ParseXS>
+(also known as C<xsubpp>) 3.13_01.
 
 =head1 AUTHOR