Front page | perl.perl5.porters |
Postings from October 2000
Re: [PATCH 5.005_64 missed]
From: Ilya Zakharevich
October 1, 2000 15:50
Re: [PATCH 5.005_64 missed]
Message ID: 20001001185010.A14152@monk.mps.ohio-state.edu
On Sun, Oct 01, 2000 at 05:35:20PM -0500, Jarkko Hietaniemi wrote:
> > http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2000-02/msg01325.html
> > missed 5.7.0.
> Otherwise it looks good for 5.7.1 but it seems that in the thread
> there were some additional concerns and comments by Sarathy and Tim
> which need to be addressed in some way.
Oh, I see. These concernes were all addressed long time ago. The
patch is *documenting* things, not *creating* them. But I forgot to
uppercase names in the patch. Drat. A new version follows.
--- ./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,