perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject cvs commit: modperl-docs/src/docs/2.0/devel/core_explained core_explained.pod
Date Tue, 05 Mar 2002 12:22:19 GMT
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: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org


Mime
View raw message