X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlxs.pod;h=a8196975aabe43f9b8ee8c52fd781a407f50f612;hb=9137345a080bfc646c2f9440cdb7bd90b8b37428;hp=a2755b8f2de2549ada32720adf1b2dd04f3a9936;hpb=beb31b0bd6e9082c7b64de972d282e0324eb5049;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlxs.pod b/pod/perlxs.pod index a2755b8..a819697 100644 --- a/pod/perlxs.pod +++ b/pod/perlxs.pod @@ -66,14 +66,15 @@ for the library being linked. A file in XS format starts with a C language section which goes until the first C> directive. Other XS directives and XSUB definitions may follow this line. The "language" used in this part of the file -is usually referred to as the XS language. +is usually referred to as the XS language. B recognizes and +skips POD (see L) in both the C and XS language sections, which +allows the XS file to contain embedded documentation. 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 +168,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); -there may be two ways to describe this argument to B: +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 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,9 +209,9 @@ 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 -shows a function with its body left-adjusted. Most examples in this -document will indent the body for better readability. +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. CORRECT @@ -259,18 +276,73 @@ some heuristic code which tries to disambiguate between "truly-void" and "old-practice-declared-as-void" functions. Hence your code is at mercy of this heuristics unless you use C as return value.) +=head2 Returning SVs, AVs and HVs through RETVAL + +When you're using RETVAL to return an C, there's some magic +going on behind the scenes that should be mentioned. When you're +manipulating the argument stack using the ST(x) macro, for example, +you usually have to pay special attention to reference counts. (For +more about reference counts, see L.) To make your life +easier, the typemap file automatically makes C mortal when +you're returning an C. Thus, the following two XSUBs are more +or less equivalent: + + void + alpha() + PPCODE: + ST(0) = newSVpv("Hello World",0); + sv_2mortal(ST(0)); + XSRETURN(1); + + SV * + beta() + CODE: + RETVAL = newSVpv("Hello World",0); + OUTPUT: + RETVAL + +This is quite useful as it usually improves readability. While +this works fine for an C, it's unfortunately not as easy +to have C or C as a return value. You I be +able to write: + + AV * + array() + CODE: + RETVAL = newAV(); + /* do something with RETVAL */ + OUTPUT: + RETVAL + +But due to an unfixable bug (fixing it would break lots of existing +CPAN modules) in the typemap file, the reference count of the C +is not properly decremented. Thus, the above XSUB would leak memory +whenever it is being called. The same problem exists for C. + +When you're returning an C or a C, you have make sure +their reference count is decremented by making the AV or HV mortal: + + AV * + array() + CODE: + RETVAL = newAV(); + sv_2mortal((SV*)RETVAL); + /* do something with RETVAL */ + OUTPUT: + RETVAL + +And also remember that you don't have to do this for an C. + =head2 The MODULE Keyword -The MODULE keyword is used to start the XS code and to -specify the package of the functions which are being -defined. All text preceding the first MODULE keyword is -considered C code and is passed through to the output -untouched. Every XS module will have a bootstrap function -which is used to hook the XSUBs into Perl. The package name -of this bootstrap function will match the value of the last -MODULE statement in the XS source files. The value of -MODULE should always remain constant within the same XS -file, though this is not required. +The MODULE keyword is used to start the XS code and to specify the package +of the functions which are being defined. All text preceding the first +MODULE keyword is considered C code and is passed through to the output with +POD stripped, but otherwise untouched. Every XS module will have a +bootstrap function which is used to hook the XSUBs into Perl. The package +name of this bootstrap function will match the value of the last MODULE +statement in the XS source files. The value of MODULE should always remain +constant within the same XS file, though this is not required. The following example will start the XS code and will place all functions in a package named RPC. @@ -295,6 +367,10 @@ keyword and must follow immediately after it when used. [ XS code in package RPC ] +The same package name can be used more than once, allowing for +non-contiguous code. This is useful if you have a stronger ordering +principle than package names. + Although this keyword is optional and in some cases provides redundant information it should always be used. This keyword will ensure that the XSUBs appear in the desired package. @@ -365,6 +441,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) + POSTCALL: + 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 @@ -502,9 +603,9 @@ C. =head2 Default Parameter Values -Default values for XSUB arguments can be specified by -placing an assignment statement in the parameter list. The -default value may be a number or a string. Defaults should +Default values for XSUB arguments can be specified by placing an +assignment statement in the parameter list. The default value may +be a number, a string or the special string C. Defaults should always be used on the right-most parameters only. To allow the XSUB for rpcb_gettime() to have a default host @@ -534,7 +635,7 @@ the parameters in the correct order for that function. =head2 The PREINIT: Keyword The PREINIT: keyword allows extra variables to be declared immediately -before or after the declartions of the parameters from the INPUT: section +before or after the declarations of the parameters from the INPUT: section are emitted. If a variable is declared inside a CODE: section it will follow any typemap @@ -714,6 +815,116 @@ 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/OUT/IN_OUT Keywords + +In the list of parameters for an XSUB, one can precede parameter names +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). 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) + 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/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 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 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) + 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 The C Keyword + +If one of the input arguments to the C function is the length of a string +argument C, one can substitute the name of the length-argument by +C in the XSUB declaration. This argument must be omited when +the generated Perl function is called. E.g., + + void + dump_chars(char *s, short l) + { + short n = 0; + while (n < l) { + printf("s[%d] = \"\\%#03o\"\n", n, (int)s[n]); + n++; + } + } + + MODULE = x PACKAGE = x + + void dump_chars(char *s, short length(s)) + +should be called as C. + +This directive is supported with ANSI-type function declarations only. + =head2 Variable-length Parameter Lists XSUBs can have variable-length parameter lists by specifying an ellipsis @@ -910,8 +1121,8 @@ then not push return values on the stack. Some people may be inclined to include an explicit C in the above XSUB, rather than letting control fall through to the end. In those situations C should be used, instead. This will ensure that -the XSUB stack is properly adjusted. Consult L for -other C macros. +the XSUB stack is properly adjusted. Consult L for other +C macros. Since C macros can be used with CODE blocks as well, one can rewrite this example as: @@ -928,14 +1139,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 POSTCALL: section as well. Together with PREINIT: simplifications, this leads to: int rpcb_gettime(host) char *host time_t timep; - CLEANUP: + POSTCALL: if (RETVAL == 0) XSRETURN_UNDEF; @@ -956,6 +1167,18 @@ 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 POSTCALL: Keyword + +This keyword can be used when an XSUB requires special procedures +executed after the C subroutine call is performed. When the POSTCALL: +keyword is used it must precede OUTPUT: and CLEANUP: blocks which are +present in the XSUB. + +See examples in L<"The NO_OUTPUT Keyword"> and L<"Returning Undef And Empty Lists">. + +The POSTCALL: 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 @@ -1028,6 +1251,14 @@ prototypes. timep RETVAL +If the prototypes are enabled, you can disable it locally for a given +XSUB as in the following example: + + void + rpcb_gettime_noproto() + PROTOTYPE: DISABLE + ... + =head2 The ALIAS: Keyword The ALIAS: keyword allows an XSUB to have two or more unique Perl names @@ -1052,6 +1283,57 @@ C for this function. OUTPUT: timep +=head2 The OVERLOAD: Keyword + +Instead of writing an overloaded interface using pure Perl, you +can also use the OVERLOAD keyword to define additional Perl names +for your functions (like the ALIAS: keyword above). However, the +overloaded functions must be defined with three parameters (except +for the nomethod() function which needs four parameters). If any +function has the OVERLOAD: keyword, several additional lines +will be defined in the c file generated by xsubpp in order to +register with the overload magic. + +Since blessed objects are actually stored as RV's, it is useful +to use the typemap features to preprocess parameters and extract +the actual SV stored within the blessed RV. See the sample for +T_PTROBJ_SPECIAL below. + +To use the OVERLOAD: keyword, create an XS function which takes +three input parameters ( or use the c style '...' definition) like +this: + + SV * + cmp (lobj, robj, swap) + My_Module_obj lobj + My_Module_obj robj + IV swap + OVERLOAD: cmp <=> + { /* function defined here */} + +In this case, the function will overload both of the three way +comparison operators. For all overload operations using non-alpha +characters, you must type the parameter without quoting, seperating +multiple overloads with whitespace. Note that "" (the stringify +overload) should be entered as \"\" (i.e. escaped). + +=head2 The FALLBACK: Keyword + +In addition to the OVERLOAD keyword, if you need to control how +Perl autogenerates missing overloaded operators, you can set the +FALLBACK keyword in the module header section, like this: + + MODULE = RPC PACKAGE = RPC + + FALLBACK: TRUE + ... + +where FALLBACK can take any of the three values TRUE, FALSE, or +UNDEF. If you do not set any FALLBACK value when using OVERLOAD, +it defaults to UNDEF. FALLBACK is not used except when one or +more functions using OVERLOAD have been defined. Please see +L for more details. + =head2 The INTERFACE: Keyword This keyword declares the current XSUB as a keeper of the given @@ -1207,7 +1489,7 @@ of C<&>, but provide a pointer to this value when the C function is called. This is useful to avoid a CODE: block for a C function which takes a parameter by reference. Typically, the parameter should be not a pointer type (an -C or C but not a C or C). +C or C but not an C or C). The following XSUB will generate incorrect C code. The B compiler will turn this into code which calls C with parameters C<(char @@ -1233,13 +1515,19 @@ C<&> through, so the function call looks like C. OUTPUT: timep -=head2 Inserting Comments and C Preprocessor Directives +=head2 Inserting POD, 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. -Comments are allowed anywhere after the MODULE keyword. The compiler -will pass the preprocessor directives through untouched and will remove -the commented lines. +C preprocessor directives are allowed within BOOT:, PREINIT: INIT:, CODE:, +PPCODE:, POSTCALL:, 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. POD documentation is allowed at any point, both in the +C and XS language sections. POD must be terminated with a C<=cut> command; +C will exit with an error if it does not. It is very unlikely that +human generated C code will be mistaken for POD, as most indenting styles +result in whitespace in front of any line starting with C<=>. Machine +generated XS files may fall into this trap unless care is taken to +ensure that a space breaks the sequence "\n=". Comments can be added to XSUBs by placing a C<#> as the first non-whitespace of a line. Care should be taken to avoid making the @@ -1314,6 +1602,19 @@ methods will be called as this: THIS->set_blue( val ); +You could also write a single get/set method using an optional argument: + + int + color::blue( val = NO_INIT ) + int val + PROTOTYPE $;$ + CODE: + if (items > 1) + THIS->set_blue( val ); + RETVAL = THIS->blue(); + OUTPUT: + RETVAL + If the function's name is B then the C++ C function will be called and C will be given as its parameter. The generated C++ code for @@ -1378,7 +1679,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 POSTCALL: 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, @@ -1486,7 +1787,7 @@ getnetconfigent() XSUB and an object created by a normal Perl subroutine. The typemap is a collection of code fragments which are used by the B compiler to map C function parameters and values to Perl values. The -typemap file may consist of three sections labeled C, C, and +typemap file may consist of three sections labelled C, C, and C. An unlabelled initial section is assumed to be a C section. The INPUT section tells the compiler how to translate Perl values @@ -1497,10 +1798,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. @@ -1532,7 +1833,7 @@ double-colons (::), and declare C to be of that type: T_PTROBJ_SPECIAL if (sv_derived_from($arg, \"${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\")) { IV tmp = SvIV((SV*)SvRV($arg)); - $var = ($type) tmp; + $var = INT2PTR($type, tmp); } else croak(\"$var is not of type ${(my $ntt=$ntype)=~s/_/::/g;\$ntt}\") @@ -1546,6 +1847,138 @@ The INPUT and OUTPUT sections substitute underscores for double-colons on the fly, giving the desired effect. This example demonstrates some of the power and versatility of the typemap facility. +The INT2PTR macro (defined in perl.h) casts an integer to a pointer, +of a given type, taking care of the possible different size of integers +and pointers. There are also PTR2IV, PTR2UV, PTR2NV macros, +to map the other way, which may be useful in OUTPUT sections. + +=head2 Safely Storing Static Data in XS + +Starting with Perl 5.8, a macro framework has been defined to allow +static data to be safely stored in XS modules that will be accessed from +a multi-threaded Perl. + +Although primarily designed for use with multi-threaded Perl, the macros +have been designed so that they will work with non-threaded Perl as well. + +It is therefore strongly recommended that these macros be used by all +XS modules that make use of static data. + +The easiest way to get a template set of macros to use is by specifying +the C<-g> (C<--global>) option with h2xs (see L). + +Below is an example module that makes use of the macros. + + #include "EXTERN.h" + #include "perl.h" + #include "XSUB.h" + + /* Global Data */ + + #define MY_CXT_KEY "BlindMice::_guts" XS_VERSION + + typedef struct { + int count; + char name[3][100]; + } my_cxt_t; + + START_MY_CXT + + MODULE = BlindMice PACKAGE = BlindMice + + BOOT: + { + MY_CXT_INIT; + MY_CXT.count = 0; + strcpy(MY_CXT.name[0], "None"); + strcpy(MY_CXT.name[1], "None"); + strcpy(MY_CXT.name[2], "None"); + } + + int + newMouse(char * name) + char * name; + PREINIT: + dMY_CXT; + CODE: + if (MY_CXT.count >= 3) { + warn("Already have 3 blind mice") ; + RETVAL = 0; + } + else { + RETVAL = ++ MY_CXT.count; + strcpy(MY_CXT.name[MY_CXT.count - 1], name); + } + + char * + get_mouse_name(index) + int index + CODE: + dMY_CXT; + RETVAL = MY_CXT.lives ++; + if (index > MY_CXT.count) + croak("There are only 3 blind mice."); + else + RETVAL = newSVpv(MY_CXT.name[index - 1]); + + +B + +=over 5 + +=item MY_CXT_KEY + +This macro is used to define a unique key to refer to the static data +for an XS module. The suggested naming scheme, as used by h2xs, is to +use a string that consists of the module name, the string "::_guts" +and the module version number. + + #define MY_CXT_KEY "MyModule::_guts" XS_VERSION + +=item typedef my_cxt_t + +This struct typedef I always be called C -- the other +C macros assume the existence of the C typedef name. + +Declare a typedef named C that is a structure that contains +all the data that needs to be interpreter-local. + + typedef struct { + int some_value; + } my_cxt_t; + +=item START_MY_CXT + +Always place the START_MY_CXT macro directly after the declaration +of C. + +=item MY_CXT_INIT + +The MY_CXT_INIT macro initialises storage for the C struct. + +It I be called exactly once -- typically in a BOOT: section. + +=item dMY_CXT + +Use the dMY_CXT macro (a declaration) in all the functions that access +MY_CXT. + +=item MY_CXT + +Use the MY_CXT macro to access members of the C struct. For +example, if C is + + typedef struct { + int index; + } my_cxt_t; + +then use this to access the C member + + dMY_CXT; + MY_CXT.index = 2; + +=back + =head1 EXAMPLES File C: Interface to some ONC+ RPC bind library functions. @@ -1623,4 +2056,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 >.