X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=XSUB.h;h=cfcad5d595a1bbc8d99004c6bd5cb1bb3d9d4f5f;hb=0bee9efe6e3302b0bae554ca99f35705369270f2;hp=18f5b81d230a1dc6224d024e5548e17ffda09f99;hpb=6f4183fe04888927cb36b966262c959c5166404b;p=p5sagit%2Fp5-mst-13.2.git diff --git a/XSUB.h b/XSUB.h index 18f5b81..cfcad5d 100644 --- a/XSUB.h +++ b/XSUB.h @@ -1,9 +1,53 @@ #ifndef _INC_PERL_XSUB_H #define _INC_PERL_XSUB_H 1 +/* first, some documentation for xsubpp-generated items */ + +/* +=for apidoc Amn|char*|CLASS +Variable which is setup by C to indicate the +class name for a C++ XS constructor. This is always a C. See C. + +=for apidoc Amn|(whatever)|RETVAL +Variable which is setup by C to hold the return value for an +XSUB. This is always the proper type for the XSUB. See +L. + +=for apidoc Amn|(whatever)|THIS +Variable which is setup by C to designate the object in a C++ +XSUB. This is always the proper type for the C++ object. See C and +L. + +=for apidoc Amn|I32|items +Variable which is setup by C to indicate the number of +items on the stack. See L. + +=for apidoc Amn|I32|ix +Variable which is setup by C to indicate which of an +XSUB's aliases was used to invoke it. See L. + +=for apidoc Am|SV*|ST|int ix +Used to access elements on the XSUB's stack. + +=for apidoc AmU||XS +Macro to declare an XSUB and its C parameter list. This is handled by +C. + +=for apidoc Ams||dXSARGS +Sets up stack and mark pointers for an XSUB, calling dSP and dMARK. This +is usually handled automatically by C. Declares the C +variable to indicate the number of items on the stack. + +=for apidoc Ams||dXSI32 +Sets up the C variable for an XSUB which has aliases. This is usually +handled automatically by C. + +=cut +*/ + #define ST(off) PL_stack_base[ax + (off)] -#if defined(CYGWIN) && defined(USE_DYNAMIC_LOADING) +#if defined(__CYGWIN__) && defined(USE_DYNAMIC_LOADING) # define XS(name) __declspec(dllexport) void name(pTHXo_ CV* cv) #else # define XS(name) void name(pTHXo_ CV* cv) @@ -34,14 +78,75 @@ #define XSINTERFACE_FUNC_SET(cv,f) \ CvXSUBANY(cv).any_dptr = (void (*) (pTHXo_ void*))(f) -#define XSRETURN(off) \ - STMT_START { \ - PL_stack_sp = PL_stack_base + ax + ((off) - 1); \ - return; \ - } STMT_END - /* Simple macros to put new mortal values onto the stack. */ /* Typically used to return values from XS functions. */ + +/* +=for apidoc Am|void|XST_mIV|int pos|IV iv +Place an integer into the specified position C on the stack. The +value is stored in a new mortal SV. + +=for apidoc Am|void|XST_mNV|int pos|NV nv +Place a double into the specified position C on the stack. The value +is stored in a new mortal SV. + +=for apidoc Am|void|XST_mPV|int pos|char* str +Place a copy of a string into the specified position C on the stack. +The value is stored in a new mortal SV. + +=for apidoc Am|void|XST_mNO|int pos +Place C<&PL_sv_no> into the specified position C on the +stack. + +=for apidoc Am|void|XST_mYES|int pos +Place C<&PL_sv_yes> into the specified position C on the +stack. + +=for apidoc Am|void|XST_mUNDEF|int pos +Place C<&PL_sv_undef> into the specified position C on the +stack. + +=for apidoc Am|void|XSRETURN|int nitems +Return from XSUB, indicating number of items on the stack. This is usually +handled by C. + +=for apidoc Am|void|XSRETURN_IV|IV iv +Return an integer from an XSUB immediately. Uses C. + +=for apidoc Am|void|XSRETURN_NV|NV nv +Return an double from an XSUB immediately. Uses C. + +=for apidoc Am|void|XSRETURN_PV|char* str +Return a copy of a string from an XSUB immediately. Uses C. + +=for apidoc Ams||XSRETURN_NO +Return C<&PL_sv_no> from an XSUB immediately. Uses C. + +=for apidoc Ams||XSRETURN_YES +Return C<&PL_sv_yes> from an XSUB immediately. Uses C. + +=for apidoc Ams||XSRETURN_UNDEF +Return C<&PL_sv_undef> from an XSUB immediately. Uses C. + +=for apidoc Ams||XSRETURN_EMPTY +Return an empty list from an XSUB immediately. + +=for apidoc AmU||newXSproto +Used by C to hook up XSUBs as Perl subs. Adds Perl prototypes to +the subs. + +=for apidoc AmU||XS_VERSION +The version identifier for an XS module. This is usually +handled automatically by C. See C. + +=for apidoc Ams||XS_VERSION_BOOTCHECK +Macro to verify that a PM module's $VERSION variable matches the XS +module's C variable. This is usually handled automatically by +C. See L. + +=cut +*/ + #define XST_mIV(i,v) (ST(i) = sv_2mortal(newSViv(v)) ) #define XST_mNV(i,v) (ST(i) = sv_2mortal(newSVnv(v)) ) #define XST_mPV(i,v) (ST(i) = sv_2mortal(newSVpv(v,0))) @@ -49,11 +154,17 @@ #define XST_mNO(i) (ST(i) = &PL_sv_no ) #define XST_mYES(i) (ST(i) = &PL_sv_yes ) #define XST_mUNDEF(i) (ST(i) = &PL_sv_undef) - + +#define XSRETURN(off) \ + STMT_START { \ + PL_stack_sp = PL_stack_base + ax + ((off) - 1); \ + return; \ + } STMT_END + #define XSRETURN_IV(v) STMT_START { XST_mIV(0,v); XSRETURN(1); } STMT_END #define XSRETURN_NV(v) STMT_START { XST_mNV(0,v); XSRETURN(1); } STMT_END #define XSRETURN_PV(v) STMT_START { XST_mPV(0,v); XSRETURN(1); } STMT_END -#define XSRETURN_PVN(v) STMT_START { XST_mPVN(0,v,n); XSRETURN(1); } STMT_END +#define XSRETURN_PVN(v,n) STMT_START { XST_mPVN(0,v,n); XSRETURN(1); } STMT_END #define XSRETURN_NO STMT_START { XST_mNO(0); XSRETURN(1); } STMT_END #define XSRETURN_YES STMT_START { XST_mYES(0); XSRETURN(1); } STMT_END #define XSRETURN_UNDEF STMT_START { XST_mUNDEF(0); XSRETURN(1); } STMT_END