develooper Front page | perl.perl5.porters | Postings from February 2000

[PATCH 5.5.64] perlxs

Thread Next
Ilya Zakharevich
February 22, 2000 19:58
[PATCH 5.5.64] perlxs
Message ID:
--- ./pod/perlxs.pod.pre	Sun Jan 23 08:07:24 2000
+++ ./pod/perlxs.pod	Tue Feb 22 20:56:10 2000
@@ -167,21 +167,37 @@ argument and returns a single value.
        double x
-When using parameters with C pointer types, as in
+Optionally, one can merge the description of types and the list of
+argument names, rewriting this as
-     double string_to_double(char *s);
+     double
+     sin(double x)
-there may be two ways to describe this argument to B<xsubpp>:
+This makes this XSUB look similar to an ANSI C declaration.  An optional
+semicolon is allowed after the argument list, as in
+     double
+     sin(double x);
+Parameters with C pointer types can have different semantic: C functions
+with similar declarations
+     bool string_looks_as_a_number(char *s);
+     bool make_char_uppercase(char *c);
+are used in absolutely incompatible manner.  Parameters to these functions
+could be described B<xsubpp> like this:
      char *  s
-     char    &s
+     char    &c
 Both these XS declarations correspond to the C<char*> C type, but they have
-different semantics.  It is convenient to think that the indirection operator
+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"> and
-L<"The & Unary Operator"> for more info about handling qualifiers and unary
-operators in C types.
+should be considered part of the variable.  See L<"The Typemap">
+for more info about handling qualifiers and unary operators in C types.
 The function name and the return type must be placed on
 separate lines and should be flush left-adjusted.
@@ -192,7 +208,7 @@ separate lines and should be flush left-
     double x                       sin(x)
 				     double x
-The function body may be indented or left-adjusted.  The following example
+The rest of the function description may be indented or left-adjusted.  The following example
 shows a function with its body left-adjusted.  Most examples in this
 document will indent the body for better readability.
@@ -365,6 +381,31 @@ Likewise,  C<SETMAGIC: ENABLE> can be us
 remainder of the OUTPUT section.  See L<perlguts> for more details
 about 'set' magic.
+=head2 The NO_OUTPUT Keyword
+The NO_OUTPUT can be placed as the first token of the XSUB.  This keyword
+indicates that while the C subroutine we provide an interface to has
+a non-C<void> return type, the return value of this C subroutine should not
+be returned from the generated Perl subroutine.
+With this keyword present L<The RETVAL Variable> is created, and in the
+generated call to the subroutine this variable is assigned to, but the value
+of this variable is not going to be used in the auto-generated code.
+This keyword makes sense only if C<RETVAL> is going to be accessed by the
+user-supplied code.  It is especially useful to make a function interface
+more Perl-like, especially when the C return value is just an error condition
+indicator.  For example,
+  NO_OUTPUT int
+  delete_file(char *name)
+      if (RETVAL != 0)
+	  croak("Error %d while deleting file '%s'", RETVAL, name);
+Here the generated XS function returns nothing on success, and will die()
+with a meaningful error message on error.
 =head2 The CODE: Keyword
 This keyword is used in more complicated XSUBs which require
@@ -714,6 +755,70 @@ thus C<host> is initialized on the decla
 C<h = host> is not performed too early.  Otherwise one would need to have the
 assignment C<h = host> in a CODE: or INIT: section.)
+=head2 The in/outlist/in_outlist Keywords
+In the list of parameters for an XSUB, one can precede parameter names
+by the C<in>/C<outlist>/C<in_outlist> keywords.  C<in> keyword is a default,
+the other two keywords indicate how the Perl interface should differ from
+the C interface.
+Parameters preceded by C<outlist>/C<in_outlist> keywords are considered to
+be used by the C subroutine I<via pointers>.  C<outlist> keyword indicates
+that the C subroutine does not inspect the memory pointed by this parameter,
+but will write through this pointer to provide additional return values.
+Such parameters do not appear in the usage signature of the generated Perl
+Parameters preceded by C<in_outlist> I<do> appear as parameters to the
+Perl function.  These parameters are converted to the corresponding C type,
+then pointers to these data are given as arguments to the C function.  It
+is expected that the C function will write through these pointers 
+The return list of the generated Perl function consists of the C return value
+from the function (unless the XSUB is of C<void> return type or
+C<The NO_INIT Keyword> was used) followed by all the C<outlist>
+and C<in_outlist> parameters (in the order of appearence).  Say, an XSUB
+  void
+  day_month(outlist day, in unix_time, outlist month)
+    int day
+    int unix_time
+    int month
+should be used from Perl as
+  my ($day, $month) = day_month(time);
+The C signature of the corresponding function should be
+  void day_month(int *day, int unix_time, int *month);
+The C<in>/C<outlist>/C<in_outlist> keywords can be mixed with ANSI-style
+declarations, as in
+  void
+  day_month(outlist int day, int unix_time, outlist int month)
+(here the optional C<in> keyword is omitted).
+The C<in_outlist> parameters are somewhat similar to parameters introduced
+with L<The & Unary Operator> and put into the C<OUTPUT:> section (see
+L<The OUTPUT: Keyword>).  Say, the same C function can be interfaced with as
+  void
+  day_month(day, unix_time, month)
+      int &day = NO_INIT
+      int  unix_time
+      int &month = NO_INIT
+    OUTPUT:
+      day
+      month
+However, the generated Perl function is called in very C-ish style:
+  my ($day, $month);
+  day_month($day, time, $month);
 =head2 Variable-length Parameter Lists
 XSUBs can have variable-length parameter lists by specifying an ellipsis
@@ -928,14 +1033,14 @@ rewrite this example as:
-In fact, one can put this check into a CLEANUP: section as well.  Together
+In fact, one can put this check into a POST_CALL: section as well.  Together
 with PREINIT: simplifications, this leads to:
           char *host
           time_t  timep;
 	  if (RETVAL == 0)
@@ -956,6 +1061,16 @@ any CODE:, PPCODE:, or OUTPUT: blocks wh
 code specified for the cleanup block will be added as the last statements
 in the XSUB.
+=head2 The POST_CALL: Keyword
+This keyword can be used when an XSUB requires special procedures
+executed after the C subroutine call is performed.  When the POST_CALL:
+keyword is used it must precede OUTPUT: and CLEANUP: blocks which are
+present in the XSUB.
+The POST_CALL: block does not make a lot of sense when the C subroutine
+call is supplied by user by providing either CODE: or PPCODE: section.
 =head2 The BOOT: Keyword
 The BOOT: keyword is used to add code to the extension's bootstrap
@@ -1236,7 +1351,7 @@ C<&> through, so the function call looks
 =head2 Inserting Comments and C Preprocessor Directives
 C preprocessor directives are allowed within BOOT:, PREINIT: INIT:,
-CODE:, PPCODE:, and CLEANUP: blocks, as well as outside the functions.
+CODE:, PPCODE:, POST_CALL:, and CLEANUP: blocks, as well as outside the functions.
 Comments are allowed anywhere after the MODULE keyword.  The compiler
 will pass the preprocessor directives through untouched and will remove
 the commented lines.
@@ -1378,7 +1493,7 @@ of failure.  They may be
 candidates to return undef or an empty list in case of failure.  If the
 failure may be detected without a call to the C function, you may want to use
 an INIT: section to report the failure.  For failures detectable after the C
-function returns one may want to use a CLEANUP: section to process the
+function returns one may want to use a POST_CALL: section to process the
 failure.  In more complicated cases use CODE: or PPCODE: sections.
 If many functions use the same failure indication based on the return value,

Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About