X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlxs.pod;h=c09947d65c847a6a09393d2e3ed12f4e7227ca4d;hb=85b35914c9f3fc562f8a505e6508276be17f9d70;hp=cee8e168b053a612010a481ad066e1308b34d03a;hpb=d1be9408a3c14848d30728674452e191ba5fffaa;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlxs.pod b/pod/perlxs.pod index cee8e16..c09947d 100644 --- a/pod/perlxs.pod +++ b/pod/perlxs.pod @@ -276,6 +276,63 @@ 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 @@ -310,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. @@ -839,6 +900,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 @@ -1035,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: @@ -1165,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 @@ -1189,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 @@ -1702,6 +1847,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.