From: Ilya Zakharevich Date: Wed, 29 Nov 2000 02:13:14 +0000 (-0500) Subject: Re: [PATCH 5.7.0] OUT keyword for xsubpp X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=cb79badd91dded24306a8c1551cce98a7b6c0b76;p=p5sagit%2Fp5-mst-13.2.git Re: [PATCH 5.7.0] OUT keyword for xsubpp Date: Wed, 29 Nov 2000 02:13:14 -0500 Message-ID: <20001129021314.A2532@monk.mps.ohio-state.edu> OUT keyword nits. Subject: Re: [PATCH 5.7.0] OUT keyword for xsubpp From: Ilya Zakharevich Date: Wed, 29 Nov 2000 03:09:04 -0500 Message-ID: <20001129030904.A2754@monk.mps.ohio-state.edu> OUT and IN_OUT documentation. p4raw-id: //depot/perl@7915 --- diff --git a/lib/ExtUtils/xsubpp b/lib/ExtUtils/xsubpp index 6724c59..bb8f3aa 100755 --- a/lib/ExtUtils/xsubpp +++ b/lib/ExtUtils/xsubpp @@ -1079,7 +1079,7 @@ while (fetch_para()) { $orig_args =~ s/\\\s*/ /g; # process line continuations - my %only_output; + my %only_outlist; if ($process_argtypes and $orig_args =~ /\S/) { my $args = "$orig_args ,"; if ($args =~ /^( (??{ $C_arg }) , )* $ /x) { @@ -1105,7 +1105,7 @@ while (fetch_para()) { $arg_types{$name} = $arg; $_ = "$name$default"; } - $only_output{$_} = 1 if $out_type =~ /^OUT/; + $only_outlist{$_} = 1 if $out_type eq "OUTLIST"; push @outlist, $name if $out_type =~ /OUTLIST$/; $in_out{$name} = $out_type if $out_type; } @@ -1119,7 +1119,7 @@ while (fetch_para()) { if ($process_inout and s/^(IN|IN_OUTLIST|OUTLIST|IN_OUT|OUT)\s+//) { my $out_type = $1; next if $out_type eq 'IN'; - $only_output{$_} = 1 if $out_type =~ /^OUT/; + $only_outlist{$_} = 1 if $out_type eq "OUTLIST"; push @outlist, $name if $out_type =~ /OUTLIST$/; $in_out{$_} = $out_type; } @@ -1144,7 +1144,7 @@ while (fetch_para()) { last; } } - if ($only_output{$args[$i]}) { + if ($only_outlist{$args[$i]}) { push @args_num, undef; } else { push @args_num, ++$num_args; diff --git a/pod/perlxs.pod b/pod/perlxs.pod index bd4e99c..a4db596 100644 --- a/pod/perlxs.pod +++ b/pod/perlxs.pod @@ -754,29 +754,37 @@ thus C is initialized on the declaration line, and our assignment C is not performed too early. Otherwise one would need to have the assignment C in a CODE: or INIT: section.) -=head2 The IN/OUTLIST/IN_OUTLIST Keywords +=head2 The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords In the list of parameters for an XSUB, one can precede parameter names -by the C/C/C keywords. C keyword is a default, -the other two keywords indicate how the Perl interface should differ from -the C interface. - -Parameters preceded by C/C keywords are considered to -be used by the C subroutine I. C 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 -function. - -Parameters preceded by C I 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 +by the C/C/C/C/C keywords. +C keyword is the default, the other keywords indicate how the Perl +interface should differ from the C interface. + +Parameters preceded by C/C/C/C +keywords are considered to be used by the C subroutine I. C/C keywords indicate that the C subroutine +does not inspect the memory pointed by this parameter, but will write +through this pointer to provide additional return values. + +Parameters preceded by C keyword do not appear in the usage +signature of the generated Perl function. + +Parameters preceded by C/C/C I appear as +parameters to the Perl function. With the exception of +C-parameters, 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 return type or -C was used) followed by all the C -and C parameters (in the order of appearance). Say, an XSUB +C was used) followed by all the C +and C parameters (in the order of appearance). On the +return from the XSUB the C/C Perl parameter will be +modified to have the values written by the C function. + +For example, an XSUB void day_month(OUTLIST day, IN unix_time, OUTLIST month) @@ -792,17 +800,30 @@ The C signature of the corresponding function should be void day_month(int *day, int unix_time, int *month); -The C/C/C keywords can be mixed with ANSI-style -declarations, as in +The C/C/C/C/C 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 keyword is omitted). -The C parameters are somewhat similar to parameters introduced -with L and put into the C section (see -L). Say, the same C function can be interfaced with as +The C parameters are identical with parameters introduced with +L and put into the C section (see L). The C parameters are very similar, the +only difference being that the value C function writes through the +pointer would not modify the Perl parameter, but is put in the output +list. + +The C/C parameter differ from C/C +parameters only by the the initial value of the Perl parameter not +being read (and not being given to the C function - which gets some +garbage instead). For example, the same C function as above can be +interfaced with as + + void day_month(OUT int day, int unix_time, OUT int month); + +or void day_month(day, unix_time, month)