and "old-practice-declared-as-void" functions. Hence your code is at
mercy of this heuristics unless you use C<SV *> as return value.)
+=head2 Returning SVs, AVs and HVs through RETVAL
+
+When you're using RETVAL to return an C<SV *>, 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<perlguts>.) To make your life
+easier, the typemap file automatically makes C<RETVAL> mortal when
+you're returning an C<SV *>. 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<SV *>, it's unfortunately not as easy
+to have C<AV *> or C<HV *> as a return value. You I<should> 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<AV *>
+is not properly decremented. Thus, the above XSUB would leak memory
+whenever it is being called. The same problem exists for C<HV *>.
+
+When you're returning an C<AV *> or a C<HV *>, 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<SV *>.
+
=head2 The MODULE Keyword
The MODULE keyword is used to start the XS code and to specify the package
[ 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.
my ($day, $month);
day_month($day, time, $month);
+=head2 The C<length(NAME)> Keyword
+
+If one of the input arguments to the C function is the length of a string
+argument C<NAME>, one can substitute the name of the length-argument by
+C<length(NAME)> 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<dump_chars($string)>.
+
+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
Some people may be inclined to include an explicit C<return> in the above
XSUB, rather than letting control fall through to the end. In those
situations C<XSRETURN_EMPTY> should be used, instead. This will ensure that
-the XSUB stack is properly adjusted. Consult L<perlguts/"API LISTING"> for
-other C<XSRETURN> macros.
+the XSUB stack is properly adjusted. Consult L<perlapi> for other
+C<XSRETURN> macros.
Since C<XSRETURN_*> macros can be used with CODE blocks as well, one can
rewrite this example as:
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
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<overload/Fallback> for more details.
+
=head2 The INTERFACE: Keyword
This keyword declares the current XSUB as a keeper of the given
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}\")
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
#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;
projects / p5sagit/p5-mst-13.2.git / blobdiff