X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlxs.pod;h=781afe60bfaaecb6c80d2ec6b72da0e418c2fef0;hb=22d4bb9ccb8701e68f9243547d7e3a3c55f70908;hp=c696e19d16c79aed2297c7b30a4813d78816f050;hpb=4b19af017623bfa3bb72bb164598a517f586e0d3;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlxs.pod b/pod/perlxs.pod index c696e19..781afe6 100644 --- a/pod/perlxs.pod +++ b/pod/perlxs.pod @@ -71,9 +71,8 @@ is usually referred to as the XS language. See L for a tutorial on the whole extension creation process. Note: For some extensions, Dave Beazley's SWIG system may provide a -significantly more convenient mechanism for creating the extension glue -code. See L for more -information. +significantly more convenient mechanism for creating the extension +glue code. See http://www.swig.org/ for more information. =head2 On The Road @@ -167,21 +166,37 @@ argument and returns a single value. sin(x) 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) + +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 -there may be two ways to describe this argument to B: + 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 like this: char * s - char &s + char &c Both these XS declarations correspond to the C 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 +207,7 @@ separate lines and should be flush left-adjusted. 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 +380,31 @@ Likewise, C can be used to reenable it for the remainder of the OUTPUT section. See L 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 return type, the return value of this C subroutine should not +be returned from the generated Perl subroutine. + +With this keyword present L 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 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) + POST_CALL: + 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 +754,70 @@ 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 + +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 + +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 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/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 + + 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 +1032,14 @@ rewrite this example as: OUTPUT: RETVAL -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: int rpcb_gettime(host) char *host time_t timep; - CLEANUP: + POST_CALL: if (RETVAL == 0) XSRETURN_UNDEF; @@ -956,6 +1060,16 @@ any CODE:, PPCODE:, or OUTPUT: blocks which are present in the XSUB. The 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 +1350,7 @@ C<&> through, so the function call looks like C. =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. @@ -1391,7 +1505,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, @@ -1510,10 +1624,10 @@ OUTPUT code fragments should be used to map a given C type to a Perl value. The section labels C, C, or C must begin in the first column on a line by themselves, and must be in uppercase. -The default typemap in the C 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 +The default typemap in the C 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 compiler will allow the extension's own typemap to override any mappings which are in the default typemap. @@ -1636,4 +1750,4 @@ This document covers features supported by C 1.935. Originally written by Dean Roehrich >. -Maintained since 1996 by The Perl Porters >. +Maintained since 1996 by The Perl Porters >.