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 Wed, 20 Mar 2002 07:10:21 GMT
stas        02/03/19 23:10:21

  Modified:    src/docs/2.0/devel/core_explained core_explained.pod
  Log:
  - cover the mapping and implementation of the glue code for macros and
  MPXS_ wrappers
  
  Revision  Changes    Path
  1.18      +259 -55   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.17
  retrieving revision 1.18
  diff -u -r1.17 -r1.18
  --- core_explained.pod	18 Mar 2002 07:19:18 -0000	1.17
  +++ core_explained.pod	20 Mar 2002 07:10:21 -0000	1.18
  @@ -299,20 +299,6 @@
     modperl_xs_sv_convert.h
     modperl_xs_typedefs.h
   
  -=head1 mpxs_ vs MPXS_
  -
  -[SCRATCH THAT]
  -If you look at the source code there are functions starting with
  -I<mpxs_> and those with I<MPXS_>.
  -
  -If you want to mess directly with the stack (i.e. without specifying
  -the prototype of the function), there are two ways to do that. Either
  -the function has to have a prototype C<...> (which stands for
  -I<items>, I<MARK> and I<SP> arguments) or prefixed with I<MPXS_>,
  -which are hooked directly into newXS().
  -
  -[/SCRATCH THAT]
  -
   =head1 Gluing Existing APIs
   
   If you have an API that you simply want to provide the Perl interface
  @@ -374,9 +360,9 @@
   about to develop, so refer to this code to see how the functions are
   invoked from Perl and what is returned:
   
  -  file:t/response/TestApache/scoreboard.pm
  +  file:t/response/TestApache/coredemo.pm
     ----------------------------------------
  -  package TestApache::scoreboard;
  +  package TestApache::coredemo;
     
     use strict;
     use warnings FATAL => 'all';
  @@ -386,7 +372,7 @@
     use Apache::Test;
     use Apache::TestUtil;
     
  -  use Apache::Scoreboard;
  +  use Apache::CoreDemo;
     
     sub handler {
         my $r = shift;
  @@ -397,24 +383,24 @@
         my $b = 3;
         my ($add, $subst);
     
  -      $add = Apache::Scoreboard::print($a, $b);
  +      $add = Apache::CoreDemo::print($a, $b);
         t_debug "print";
         ok !$add;
     
  -      $add = Apache::Scoreboard::add($a, $b);
  +      $add = Apache::CoreDemo::add($a, $b);
         ok t_cmp($a + $b, $add, "add");
     
  -      $add = Apache::Scoreboard::add_sv($a, $b);
  +      $add = Apache::CoreDemo::add_sv($a, $b);
         ok t_cmp($a + $b, $add, "add: return sv");
     
  -      $add = Apache::Scoreboard::add_sv_sv($a, $b);
  +      $add = Apache::CoreDemo::add_sv_sv($a, $b);
         ok t_cmp($a + $b, $add, "add: pass/return svs");
     
  -      ($add, $subst) = @{ Apache::Scoreboard::add_subst($a, $b) };
  +      ($add, $subst) = @{ Apache::CoreDemo::add_subst($a, $b) };
         ok t_cmp($a + $b, $add,   "add_subst: add");
         ok t_cmp($a - $b, $subst, "add_subst: subst");
     
  -      $subst = Apache::Scoreboard::subst_sp($a, $b);
  +      $subst = Apache::CoreDemo::subst_sp($a, $b);
         ok t_cmp($a - $b, $subst, "subst via SP");
     
         Apache::OK;
  @@ -425,18 +411,18 @@
   The first case is the simplest: pass two integer arguments, print
   these to the STDERR stream and return nothing:
   
  -  file:xs/Apache/Scoreboard/Apache__Scoreboard.h
  +  file:xs/Apache/CoreDemo/Apache__CoreDemo.h
     ----------------------------------------------
     static MP_INLINE
  -  void mpxs_Apache__Scoreboard_print(int a, int b)
  +  void mpxs_Apache__CoreDemo_print(int a, int b)
     {
         fprintf(stderr, "%d, %d\n", a, b);
     }
   
     file:xs/maps/modperl_functions.map
     ----------------------------------
  -  MODULE=Apache::Scoreboard
  -   mpxs_Apache__Scoreboard_print
  +  MODULE=Apache::CoreDemo
  +   mpxs_Apache__CoreDemo_print
   
   Now let's say that the I<b> argument is optional and in case it wasn't
   provided, we want to use a default value, e.g. 0. In that case we
  @@ -444,8 +430,8 @@
   
     file:xs/maps/modperl_functions.map
     ----------------------------------
  -  MODULE=Apache::Scoreboard
  -   mpxs_Apache__Scoreboard_print | | a, b=0
  +  MODULE=Apache::CoreDemo
  +   mpxs_Apache__CoreDemo_print | | a, b=0
   
   In the previous example, we didn't list the arguments in the map file
   since they were automatically retrieved from the source code. In this
  @@ -455,40 +441,40 @@
   
   You may add an extra test that test teh default value assignment:
   
  -      $add = Apache::Scoreboard::add($a);
  +      $add = Apache::CoreDemo::add($a);
         ok t_cmp($a + 0, $add, "add (b=0 default)");
   
   The second case: pass two integer arguments and return their sum:
   
  -  file:xs/Apache/Scoreboard/Apache__Scoreboard.h
  +  file:xs/Apache/CoreDemo/Apache__CoreDemo.h
     ----------------------------------------------
     static MP_INLINE
  -  int mpxs_Apache__Scoreboard_add(int a, int b)
  +  int mpxs_Apache__CoreDemo_add(int a, int b)
     {
         return a + b;
     }
   
     file:xs/maps/modperl_functions.map
     ----------------------------------
  -  MODULE=Apache::Scoreboard
  -   mpxs_Apache__Scoreboard_add
  +  MODULE=Apache::CoreDemo
  +   mpxs_Apache__CoreDemo_add
   
   The third case is similar to the previous one, but we return the sum
   as as a Perl scalar. Though in C we say SV*, in the Perl space we will
   get a normal scalar:
   
  -  file:xs/Apache/Scoreboard/Apache__Scoreboard.h
  +  file:xs/Apache/CoreDemo/Apache__CoreDemo.h
     ----------------------------------------------
     static MP_INLINE
  -  SV *mpxs_Apache__Scoreboard_add_sv(pTHX_ int a, int b)
  +  SV *mpxs_Apache__CoreDemo_add_sv(pTHX_ int a, int b)
     {
         return newSViv(a + b);
     }
   
     file:xs/maps/modperl_functions.map
     ----------------------------------
  -  MODULE=Apache::Scoreboard
  -   mpxs_Apache__Scoreboard_add_sv
  +  MODULE=Apache::CoreDemo
  +   mpxs_Apache__CoreDemo_add_sv
   
   In the second example the XSUB function was converting the returned
   I<int> value to a Perl scalar behind the scenes. In this example we
  @@ -502,10 +488,10 @@
   argument list to the corresponding C variables, using the typemap
   definitions.
   
  -  file:xs/Apache/Scoreboard/Apache__Scoreboard.h
  +  file:xs/Apache/CoreDemo/Apache__CoreDemo.h
     ----------------------------------------------
     static MP_INLINE
  -  SV *mpxs_Apache__Scoreboard_add_sv_sv(pTHX_ SV *a_sv, SV *b_sv)
  +  SV *mpxs_Apache__CoreDemo_add_sv_sv(pTHX_ SV *a_sv, SV *b_sv)
     {
         int a = (int)SvIV(a_sv);
         int b = (int)SvIV(b_sv);
  @@ -515,8 +501,8 @@
   
     file:xs/maps/modperl_functions.map
     ----------------------------------
  -  MODULE=Apache::Scoreboard
  -   mpxs_Apache__Scoreboard_add_sv_sv
  +  MODULE=Apache::CoreDemo
  +   mpxs_Apache__CoreDemo_add_sv_sv
   
   So this example is the same simple case of addition, though we
   manually convert the Perl variables to C variables, perform the
  @@ -528,10 +514,10 @@
   function returns. The fifth case demonstrates a function that returns
   the result of addition and substruction operations on its arguments:
   
  -  file:xs/Apache/Scoreboard/Apache__Scoreboard.h
  +  file:xs/Apache/CoreDemo/Apache__CoreDemo.h
     ----------------------------------------------
     static MP_INLINE
  -  SV *mpxs_Apache__Scoreboard_add_subst(pTHX_ int a, int b)
  +  SV *mpxs_Apache__CoreDemo_add_subst(pTHX_ int a, int b)
     {
         AV *av = newAV();
     
  @@ -543,18 +529,18 @@
   
     file:xs/maps/modperl_functions.map
     ----------------------------------
  -  MODULE=Apache::Scoreboard
  -   mpxs_Apache__Scoreboard_add_subst
  +  MODULE=Apache::CoreDemo
  +   mpxs_Apache__CoreDemo_add_subst
   
   If you look at the corresponding testing code:
   
  -      ($add, $subst) = @{ Apache::Scoreboard::add_subst($a, $b) };
  +      ($add, $subst) = @{ Apache::CoreDemo::add_subst($a, $b) };
         ok t_cmp($a + $b, $add,   "add_subst: add");
         ok t_cmp($a - $b, $subst, "add_subst: subst");
   
   you can see that this technique comes at a price of needing to
   dereference the return value to turn it into a list. The actual code
  -is very similar to the C<Apache::Scoreboard::add_sv> function which
  +is very similar to the C<Apache::CoreDemo::add_sv> function which
   was doing only the addition operation and returning a Perl
   scalar. Here we perform the addition and the substraction operation
   and push the two results into a previously created I<AV*> data
  @@ -567,10 +553,10 @@
   notice that we still know that we are returning at compile time (zero
   or one arguments), I<int> in this example:
   
  -  file:xs/Apache/Scoreboard/Apache__Scoreboard.h
  +  file:xs/Apache/CoreDemo/Apache__CoreDemo.h
     ----------------------------------------------
     static MP_INLINE
  -  int mpxs_Apache__Scoreboard_subst_sp(pTHX_ I32 items, SV **MARK, SV **SP)
  +  int mpxs_Apache__CoreDemo_subst_sp(pTHX_ I32 items, SV **MARK, SV **SP)
     {
         int a, b;
     
  @@ -586,8 +572,8 @@
   
     file:xs/maps/modperl_functions.map
     ----------------------------------
  -  MODULE=Apache::Scoreboard
  -   mpxs_Apache__Scoreboard_subst_sp | | ...
  +  MODULE=Apache::CoreDemo
  +   mpxs_Apache__CoreDemo_subst_sp | | ...
   
   In the map file we use a special token C<...> which tells the XSUB
   constructor to pass C<items>, C<MARK> and C<SP> arguments to the
  @@ -623,13 +609,231 @@
   
   This section talks about cases where it's unknown at compile time how
   many return values will be or it's known that there will be more than
  -one return value--something that C cannot handle via return mechanism.
  +one return value--something that C cannot handle via its return
  +mechanism.
  +
  +Let's rewrite the function C<mpxs_Apache__CoreDemo_add_subst> from
  +the earlier section to return two results instead of a reference to a
  +list:
  +
  +  file:xs/Apache/CoreDemo/Apache__CoreDemo.h
  +  ----------------------------------------------
  +  static XS(MPXS_Apache__CoreDemo_add_subst_sp)
  +  {
  +      dXSARGS;
  +      int a, b;
  +      
  +      if (items != 2) {
  +          Perl_croak(aTHX_ "usage: Apache::CoreDemo::add_subst_sp($a, $b)");
  +      }
  +      a = mp_xs_sv2_int(ST(0));
  +      b = mp_xs_sv2_int(ST(1));
  +      
  +      SP -= items;
  +      
  +      if (GIMME == G_ARRAY) {
  +  	EXTEND(sp, 2);
  +  	PUSHs(sv_2mortal(newSViv(a + b)));
  +  	PUSHs(sv_2mortal(newSViv(a - b)));
  +      }
  +      else {
  +          XPUSHs(sv_2mortal(newSViv(a + b)));
  +      }
  +  
  +      PUTBACK;
  +  }
  +
  +Before explaining the function here is the prototype we add to the map
  +file:
  +
  +  file:xs/maps/modperl_functions.map
  +  ----------------------------------
  +  MODULE=Apache::CoreDemo
  +  DEFINE_add_subst_sp | MPXS_Apache__CoreDemo_add_subst_sp | ...
  +
  +This declaration say that C<MPXS_Apache__CoreDemo_add_subst_sp>
  +function will be called from the XS wrapper for the
  +C<Apache::CoreDemo::add_subst_sp> with arguments:
  +
  +  aTHX_ I32 items, SP **sp, SV **MARK
  +
  +that's what the C<...> part in the third column stands for.
  +
  +In this function we manually manipulate the stack to retrieve the
  +arguments passed on the Perl side and put the results back onto the
  +stack.  Therefore the first thing we do is to initialize a few special
  +variables using the C<dXSARGS> macro defined in I<XSUB.h>, which in
  +fact calls a bunch of other macros. These variables help to manipulate
  +the stack. C<dSP> is one of these macros and it declares and initial­
  +izes a local copy of the Perl stack pointer C<sp> which . This local
  +copy should always be accessed as C<SP>.
  +
  +We retrieve the original function arguments using the C<ST()>
  +macros. C<ST(0)> and C<ST(1)> point to the first and the second
  +argument on the stack, respectively. But first we check that we have
  +exactly two arguments on the stack, and if not we abort the
  +function. The C<items> variable is the function argument.
  +
  +Once we have retrieved all the arguments from the stack we set the
  +local stack pointer C<SP> to point to the bottom of the stack (like
  +there are no items on the stack):
  +
  +      SP -= items;
  +
  +Now we can do whatever processing is needed and put the results back
  +on the stack. In our example we return the results of addition and
  +substraction operations if the function is called in the list
  +context. In the scalar context the function returns only the result of
  +the addition operation. We use the C<GIMME> macro which tells us the
  +context.
  +
  +In the list context we make sure that we have two spare slots on the
  +stack since we are going to push two items, and then we push them
  +using the C<PUSHs> macro:
  +
  +	EXTEND(sp, 2);
  +	PUSHs(sv_2mortal(newSViv(a + b)));
  +	PUSHs(sv_2mortal(newSViv(a - b)));
  +
  +Alternatively we could use:
   
  -META: ...
  +	XPUSHs(sv_2mortal(newSViv(a + b)));
  +	XPUSHs(sv_2mortal(newSViv(a - b)));
   
  +The C<XPUSHs> macro eI<X>tends the stack before pushing the item into
  +it if needed. If we plan to push more than a single item onto the
  +stack, it's more efficient to extend the stack in one call.
  +
  +In the scalar context we push only one item, so here we use the
  +C<XPUSHs> macro:
  +
  +       XPUSHs(sv_2mortal(newSViv(a + b)));
  +
  +The last command we call is:
  +
  +      PUTBACK;
  +
  +which makes the local stack pointer global. This is a must call if the
  +state of the stack was changed when the function is about to
  +return. The stack changes if something was popped from or pushed to
  +it, or both and changed the number of items on the stack.
  +
  +In our example we don't need to call C<PUTBACK> if the function is
  +called in the list context. Because in this case we return two
  +variables, the same as two function arguments, the count didn't
  +change. Though in the scalar context we push onto the stack only one
  +argument, so the function won't return what is expected. The simplest
  +way to avoid errors here is to always call C<PUTBACK> when the stack
  +is changed.
  +
  +For more information refer to the I<perlcall> manpage which explains
  +the stack manipulation process in great details.
  +
  +Finally we test the function in the list and scalar contexts:
  +
  +  file:t/response/TestApache/coredemo.pm
  +  ----------------------------------------
  +  ...
  +  my $a = 7;
  +  my $b = 3;
  +  my ($add, $subst);
  +  
  +  # list context
  +  ($add, $subst) = Apache::CoreDemo::add_subst_sp($a, $b);
  +  ok t_cmp($a + $b, $add,   "add_subst_sp list context: add");
  +  ok t_cmp($a - $b, $subst, "add_subst_sp list context: subst");
  +  
  +  # scalar context
  +  $add = Apache::CoreDemo::add_subst_sp($a, $b);
  +  ok t_cmp($a + $b, $add,   "add_subs_spt scalar context: add");
  +  ...
  +
  +=head2 Wrappers Functions for C Macros
  +
  +Let's say you have a C macro which you want to provide a Perl
  +interface for. For example let's take a simple macro which performs
  +the power of function:
  +
  +  file:xs/Apache/CoreDemo/Apache__CoreDemo.h
  +  ----------------------------------------------
  +  #define mpxs_Apache__CoreDemo_power(x, y) pow(x, y)
  +
  +To create the XS glue code we use the following entry in the map file:
  +
  +  file:xs/maps/modperl_functions.map
  +  ----------------------------------
  +  MODULE=Apache::CoreDemo
  +  double:DEFINE_power | | double:x, double:y
  +
  +This works very similar to the C<MPXS_Apache__CoreDemo_add_subst_sp>
  +function presented earlier. But since this is a macro the XS wrapper
  +needs to know the types of the arguments and the return type, so these
  +are added. The return type is added just before the function name and
  +separated from it by the colon (C<:>), the argument types are
  +specified in the third column. The type is always separated from the
  +name of the variable by the colon (C<:>).
  +
  +And of course finally we need to test that the function works in Perl:
  +
  +  file:t/response/TestApache/coredemo.pm
  +  ----------------------------------------
  +  ...
  +  my $a = 7;
  +  my $b = 3;
  +  my $power = Apache::CoreDemo::power($a, $b);
  +  ok t_cmp($a ** $b, $power, "power macro");
  +  ...
  +
  +=head1 Wrappers for modperl_, apr_ and ap_ APIs
  +
  +If you already have a C function whose name starts from I<modperl_>,
  +I<apr_> or I<ap_> and you want to do something before calling the real
  +C function, you can write a XS wrapper using the same method as in the
  +L<MPXS_Apache__CoreDemo_add_subst_sp
  +|/Functions_Returning_Variable_Number_of_Values>. The only difference
  +is that it'll be clearly seen in the map file that this is a wrapper
  +for an existing C API.
  +
  +Let's say that we have an existing C function apr_power(), this is how
  +we declare its wrapper:
  +
  +  file:xs/maps/apr_functions.map
  +  ----------------------------------
  +  MODULE=APR::Foo
  +  apr_power | MPXS_ | x, y
  +
  +The first column specifies the existing function's name, the second
  +tells that the XS wrapper will use the C<MPXS_> prefix, which means
  +that the wrapper must be called C<MPXS_apr_power>. The third column
  +specifies the argument names, but no matter what you specify there the
  +C<...> will be passed:
  +
  +  aTHX_ I32 items, SP **sp, SV **MARK
  +
  +so you can leave that column empty.
  +
  +If the forth column is empty this function will be called
  +C<APR::Foo::power> in the Perl namespace. But you can use that column
  +to give a different Perl name, e.g with:
  +
  +  apr_power | MPXS_ | x, y | pow
  +
  +This function will be available from Perl as C<APR::Foo::pow>.
  +
  +Similarly you can write a C<MPXS_odperl_power> wrapper for a
  +C<modperl_power()> function but here you have to explicitly give the
  +Perl function's name in the forth column:
  +
  +  file:xs/maps/apr_functions.map
  +  ----------------------------------
  +  MODULE=Apache::CoreDemo
  +  modperl_power | MPXS_ | x, y | mypower
   
  -=head2 Mapping Macro's to XS subs
  +and the Perl function will be called C<Apache::CoreDemo::mypower>.
   
  +The C<MPXS_> wrapper's implementation is similar to
  +L<MPXS_Apache__CoreDemo_add_subst_sp
  +|/Functions_Returning_Variable_Number_of_Values>.
   
   =head1 MP_INLINE vs C Macros vs Normal Functions
   
  
  
  

---------------------------------------------------------------------
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