Front page | perl.perl5.porters |
Postings from February 2000
[PATCH 5.5.64] perlxs
From: Ilya Zakharevich
February 22, 2000 19:58
[PATCH 5.5.64] perlxs
Message ID: 20000222225659.A15170@math.mps.ohio-state.edu
--- ./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.
-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);
+ 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
+ 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)
-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
+ 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
+ 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
+ day_month(day, unix_time, month)
+ int &day = NO_INIT
+ int unix_time
+ int &month = NO_INIT
+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:
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,
[PATCH 5.5.64] perlxs
by Ilya Zakharevich