X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlxs.pod;h=15a7888697421f17e1b4e9fbac5d29a8d972f5ca;hb=83272a45226e83bd136d713158e9b44ace2dbc8d;hp=541f75e535f4d75bfb1f445f7200a8559768d5a5;hpb=cea6626fc5e04af2c1d079dd4d3784eb2c21174b;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlxs.pod b/pod/perlxs.pod index 541f75e..15a7888 100644 --- a/pod/perlxs.pod +++ b/pod/perlxs.pod @@ -310,6 +310,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. @@ -398,7 +402,7 @@ indicator. For example, NO_OUTPUT int delete_file(char *name) - POST_CALL: + POSTCALL: if (RETVAL != 0) croak("Error %d while deleting file '%s'", RETVAL, name); @@ -816,7 +820,7 @@ 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 +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 @@ -839,6 +843,31 @@ 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 @@ -1053,14 +1082,14 @@ rewrite this example as: OUTPUT: RETVAL -In fact, one can put this check into a POST_CALL: 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; - POST_CALL: + POSTCALL: if (RETVAL == 0) XSRETURN_UNDEF; @@ -1081,14 +1110,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 +=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 POST_CALL: +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. -The POST_CALL: block does not make a lot of sense when the C subroutine +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 @@ -1163,6 +1194,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 @@ -1187,6 +1226,40 @@ 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 INTERFACE: Keyword This keyword declares the current XSUB as a keeper of the given @@ -1342,7 +1415,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 @@ -1371,7 +1444,7 @@ C<&> through, so the function call looks like C. =head2 Inserting POD, Comments and C Preprocessor Directives C preprocessor directives are allowed within BOOT:, PREINIT: INIT:, CODE:, -PPCODE:, POST_CALL:, and CLEANUP: blocks, as well as outside the functions. +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 @@ -1532,7 +1605,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 POST_CALL: 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, @@ -1700,6 +1773,133 @@ 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. +=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.