stas 02/03/05 04:22:19
Modified: src/docs/2.0/devel/core_explained core_explained.pod
Log:
- new section "Adding Typemaps for new Data Types"
Revision Changes Path
1.14 +71 -1
modperl-docs/src/docs/2.0/devel/core_explained/core_explained.pod
Index: core_explained.pod
===================================================================
RCS file:
/home/cvs/modperl-docs/src/docs/2.0/devel/core_explained/core_explained.pod,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- core_explained.pod 3 Jan 2002 07:21:04 -0000 1.13
+++ core_explained.pod 5 Mar 2002 12:22:19 -0000 1.14
@@ -197,6 +197,8 @@
MODULE=APR::IO PACKAGE=APR::IO BOOT=1
+Notice that the C<PACKAGE=> declaration is a must.
+
When I<make xs_generate> is run (after running I<make source_scan>),
it autogenerates I<Wrap/APR/IO/IO.xs> and amongst other things will
include:
@@ -435,7 +437,75 @@
In all other cases use normal functions.
-=head1 Importing Constants and Enums into Perl API
+=head1 Adding New Interfaces
+
+
+
+=head2 Adding Typemaps for new Data Types
+
+Sometimes when a new interface is added it may include C data types
+for which we don't yet have a Perl typemap. In such a case, the first
+thing to do is to provide the required typemaps.
+
+Let's add a prototype for the I<typedef struct scoreboard> data type
+defined in I<httpd-2.0/include/scoreboard.h>.
+
+First we include the relevant header files in
+I<src/modules/perl/modperl_apache_includes.h>:
+
+ #include "scoreboard.h"
+
+If you want to specify your own type and don't have a header file for
+it (e.g. if you extend some existing datatype within mod_perl) you may
+add the I<typedef> to I<src/modules/perl/modperl_types.h>.
+
+After deciding that C<Apache::Scoreboard> is the Perl class will be
+used for manipulating C I<scoreboard> data structures, we map the
+I<scoreboard> data structure to the C<Apache::Scoreboard>
+class. Therefore we add to I<xs/maps/apache_types.map>:
+
+ struct scoreboard | Apache::Scoreboard
+
+Since we want the I<scoreboard> data structure to be an opaque object
+on the perl side, we simply let mod_perl use the default C<T_PTROBJ>
+typemap. After running C<make xs_generate> you can check the assigned
+typemap in the autogenerated I<WrapXS/typemap> file.
+
+If you need to do some special handling while converting from C to
+Perl and back, you need to add the conversion functions to the
+I<xs/typemap> file. For example the C<Apache::RequestRec> objects need
+special handling, so you can see the special C<INPUT> and C<OUTPUT>
+typemappings for the corresponding C<T_APACHEOBJ> object type.
+
+Now we run C<make xs_generate> and find the following definitions in
+the autogenerated files:
+
+ file:xs/modperl_xs_typedefs.h
+ -----------------------------
+ typedef scoreboard * Apache__Scoreboard;
+
+ file:xs/modperl_xs_sv_convert.h
+ -------------------------------
+ #define mp_xs_sv2_Apache__Scoreboard(sv) \
+ ((SvROK(sv) && (SvTYPE(SvRV(sv)) == SVt_PVMG)) \
+ || (Perl_croak(aTHX_ "argument is not a blessed reference \
+ (expecting an Apache::Scoreboard derived object)"),0) ? \
+ (scoreboard *)SvIV((SV*)SvRV(sv)) : (scoreboard *)NULL)
+
+ #define mp_xs_Apache__Scoreboard_2obj(ptr) \
+ sv_setref_pv(sv_newmortal(), "Apache::Scoreboard", (void*)ptr)
+
+The file I<xs/modperl_xs_typedefs.h> declares the typemapping from C
+to Perl and equivalent to the C<TYPEMAP> section of the XS's
+I<typemap> file. The second file I<xs/modperl_xs_sv_convert.h>
+generates two macros. The first macro is used to convert from Perl to
+C datatype and equivalent to the I<typemap> file's C<INPUT>
+section. The second macro is used to convert from C to Perl datatype
+and equivalent to the I<typemap>'s <OUTPUT> section.
+
+Now proceed on adding the glue code for the new interface.
+
+=head2 Importing Constants and Enums into Perl API
To I<import> httpd and APR constants and enums into Perl API, edit
I<lib/Apache/ParseSource.pm>. To add a new type of C<DEFINE> constants
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
