=head1 NAME

mod_perl 2.0 Source Code Explained

=head1 Description

This document explains how to navigate the mod_perl source code,
modify and rebuild the existing code and most important: how to add
new functionality.

=head1 Project's Filesystem Layout

In its pristine state the project is comprised of the following
directories and files residing at the root directory of the project:

  Apache-Test/      - test kit for mod_perl and Apache2::* modules
  ModPerl-Registry/ - ModPerl::Registry sub-project
  build/            - utilities used during project build
  docs/             - documentation
  lib/              - Perl modules
  src/              - C code that builds libmodperl.so
  t/                - mod_perl tests
  todo/             - things to be done
  util/             - useful utilities for developers
  xs/               - source xs code and maps
  Changes           - Changes file
  LICENSE           - ASF LICENSE document
  Makefile.PL       - generates all the needed Makefiles

After building the project, the following root directories and files
get generated:

  Makefile     - Makefile
  WrapXS/      - autogenerated XS code
  blib/        - ready to install version of the package

=head1 Directory src

=head2 Directory src/modules/perl/

The directory I<src/modules/perl> includes the C source files needed
to build the I<libmodperl> library.

Notice that several files in this directory are autogenerated during
the I<perl Makefile> stage.

When adding new source files to this directory you should add their
names to the C<@c_src_names> variable in I<lib/ModPerl/Code.pm>, so
they will be picked up by the autogenerated I<Makefile>.

=head1 Directory xs/

  Apache2/                 - Apache specific XS code
  APR/                     - APR specific XS code
  ModPerl/                 - ModPerl specific XS code
  maps/                    - 
  tables/                  - 
  Makefile.PL              - 
  modperl_xs_sv_convert.h  - 
  modperl_xs_typedefs.h    - 
  modperl_xs_util.h        - 
  typemap                  - 

=head2 xs/Apache2, xs/APR and xs/ModPerl

The I<xs/Apache2>, I<xs/APR> and I<xs/ModPerl> directories include I<.h> files which
have C and XS code in them. They all have the I<.h> extension because
they are always C<#include-d>, never compiled into their own object
file.  and only the file that C<#include-s> an I<.h> file from these
directories should be able to see what's in there.  Anything else
belongs in a I<src/modules/perl/foo.c> public API.

=head2 xs/maps

The I<xs/maps> directory includes mapping files which describe how
Apache Perl API should be constructed and various XS typemapping.

These files get modified whenever:

=over

=item *

a new function is added or the API of the existing one is modified.

=item *

a new struct is added or the existing one is modified

=item *

a new C datatype or Perl typemap is added or an existing one is
modified.

=back

The execution of:

  % make source_scan

or:

  % perl build/source_scan.pl 

converts these map files into their Perl table representation in the
I<xs/tables/current/> directory. This Perl representation is then used
during C<perl Makefile.PL> to generate the XS code in the I<./WrapXS/>
directory by the xs_generate() function. This XS code is combined of
the Apache API Perl glue and mod_perl specific extensions.

If you need to skip certain unwanted C defines from being picked by
the source scanning you can add them to the array
C<$Apache2::ParseSource::defines_unwanted> in
I<lib/Apache2/ParseSource.pm>.

Notice that I<source_scan> target is normally not run during the
project build process, since the source scanning is not stable yet,
therefore everytime the map files change, C<make source_scan> should
be run manually and the updated files ending up in the
I<xs/tables/current/> directory should be committed to the svn 
repository.

I<lib/ModPerl/CScan.pm> requires Data::Flow from CPAN
which is used by I<build/source_scan.pl>

There are three different types of map files in the I<xs/maps/>
directory:

=over

=item * Functions Mapping

  apache_functions.map
  modperl_functions.map
  apr_functions.map

=item * Structures Mapping

  apache_structures.map
  apr_structures.map

=item * Types Mapping

  apache_types.map
  apr_types.map
  modperl_types.map

=back

The following sections describe the syntax of the files in each group

=head3 Functions Mapping

The functions mapping file is comprised of groups of function
definitions. Each group starts with a header similar to XS syntax:

  MODULE=... PACKAGE=... PREFIX=... BOOT=... ISA=...

where:

=over

=item * C<MODULE>

the module name where the functions should be put.  e.g. C<MODULE
Apache2::Connection> will place the functions into 
I<WrapXS/Apache2/Connection.{pm,xs}>.

=item * C<PACKAGE>

the package name functions belong to, defaults to C<MODULE>.  The
value of I<guess> indicates that package name should be guessed based
on first argument found that maps to a Perl class.  If the value is
not defined and the function's name starts with I<ap_> the C<Apache2>
package will be used, if it starts with I<apr_> then the C<APR>
package is used.

=item * C<PREFIX>

prefix string to be stripped from the function name.  If not specified
it defaults to C<PACKAGE>, converted to C name convention, e.g.
C<APR::Base64> makes the prefix: I<apr_base64_>.  If the converted
prefix does not match, defaults to I<ap_> or I<apr_>.

=item * C<BOOT>

The C<BOOT> directive tells the XS generator, whether to add the boot
function to the autogenerated XS file or not. If the value of C<BOOT>
is not true or it's simply not declared, the boot function won't be
added.

If the value is true, a boot function will be added to the XS file.
Note, that this function is not declared in the map file.

The boot function name must be constructed from three parts:

  'mpxs_' . MODULE . '_BOOT'

where C<MODULE> is the one declared with C<MODULE=> in the map file.

For example if we want to have an XS boot function for a class
C<APR::IO>, we create this function in I<xs/APR/IO/APR__IO.h>:

  static void mpxs_APR__IO_BOOT(pTHX)
  {
     /* boot code here */
  }

and now we add the C<BOOT=1> declaration to the
I<xs/maps/modperl_functions.map> file:

  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:

  BOOT:
      mpxs_APR__IO_BOOT(aTHXo);


=item * C<ISA>

META: complete

=back

Every function definition is declared on a separate line (use C<\> if
the line is too long), using the following format:

  C function name | Dispatch function name | Argspec | Perl alias

where:

=over

=item * C function name

The name of the real C function.

Function names that do not begin with C</^\w/> are skipped. For
details see: C<%ModPerl::MapUtil::disabled_map>.

The return type can be specified before the C function name. It
defaults to I<return_type> in C<{Apache2,ModPerl}::FunctionTable>.

META: DEFINE nuances

=item * Dispatch function name

Dispatch function name defaults to C function name. If the dispatch
name is just a prefix (I<mpxs_>, I<MPXS_>) the C function name is
appended to it.

See the explanation about function naming and arguments passing.

=item * Argspec

The argspec defaults to arguments in
C<{Apache2,ModPerl}::FunctionTable>.  Argument types can be specified
to override those in the C<FunctionTable>.  Default values can be
specified, e.g. C<arg=default_value>. Argspec of C<...> indicates
I<passthru>, calling the function with C<(aTHX_ I32 items, SP **sp, SV
**MARK)>.

=item * Perl alias

the Perl alias will be created in the current C<PACKAGE>.

=back

=head3 Structures Mapping

See %ModPerl::MapUtil::disabled_map in lib/ModPerl/MapUtil.pm

META: complete

=head3 Types Mapping

META: complete

=head3 Modifying Maps

As explained in the beginning of this section, whenever the map file
is modified you need first to run:

  % make source_scan

Next check that the conversion to Perl tables is properly done by
verifying the resulting corresponding file in
I<xs/tables/current>. For example I<xs/maps/modperl_functions.map> is
converted into I<xs/tables/current/ModPerl/FunctionTable.pm>.

If you want to do a visual check on how XS code will be generated, run:

  % make xs_generate

and verify that the autogenerated XS code under the directory
I<./WrapXS> is correct. Notice that for functions, whose arguments or
return types can't be resolved, the XS glue won't be generated and a
warning will be printed. If that's the case add the missing type's
typemap to the types map file as explained in L<Adding Typemaps for
new C Data
Types|/Adding_Typemaps_for_new_C_Data_Types> and run the XS generation
stage again.

You can also build the project normally:

   % perl Makefile.PL ...

which runs the XS generation stage.

=head2 XS generation process

As mentioned before XS code is generated in the I<WrapXS> directory
either during C<perl Makefile.PL> via xs_generate() if
C<MP_GENERATE_XS=1> is used (which is the default) or explicitly via:

  % make xs_generate

In addition it creates a number of files in the I<xs/> directory:

  modperl_xs_sv_convert.h
  modperl_xs_typedefs.h

=head1 Gluing Existing APIs

If you have an API that you simply want to provide the Perl interface
without writing any code... 

META: complete

WrapXS allows you to adjust some arguments and supply default values
for function arguments without writing any code

META: complete

C<MPXS_> functions are final C<XSUBs> and always accept:

  aTHX_ I32 items, SP **sp, SV **MARK

as their arguments. Whereas C<mpxs_> functions are either intermediate
thin wrappers for the existing C functions or functions that do
something by themselves. C<MPXS_> functions also can be used for
writing thin wrappers for C macros.

=head1 Adding Wrappers for existing APIs and Creating New APIs

In certain cases the existing APIs need to be adjusted. There are a
few reasons for doing this.

First, is to make the given C API more Perlish. For example C
functions cannot return more than one value, and the pass by reference
technique is used. This is not Perlish. Perl has no problem returning
a list of value, and passing by reference is used only when an array
or a hash in addition to any other variables need to be passes or
returned from the function. Therefore we may want to adjust the C API
to return a list rather than passing a reference to a return value,
which is not intuitive for Perl programmers.

Second, is to adjust the functionality, i.e. we still use the C API
but may want to adjust its arguments before calling the original
function, or do something with return values. And of course optionally
adding some new code.

Third, is to create completely new APIs. It's quite possible that we
need more functionality built on top of the existing API. In that case
we simply create new APIs.

The following sections discuss various techniques for retrieving
function arguments and returning values to the caller. They range from
using usual C argument passing and returning to more complex Perl
arguments' stack manipulation. Once you know how to retrieve the
arguments in various situations and how to put the return values on
the stack, the rest is usually normal C programming potentially
involving using Perl APIs.

Let's look at various ways we can declare functions and what options
various declarions provide to us:

=head2 Functions Returning a Single Value (or Nothing)

If its know deterministically what the function returns and there is
only a single return value (or nothing is returned == I<void>), we are
on the C playground and we don't need to manipulate the returning
stack.  However if the function may return a single value or nothing
at all, depending on the inputs and the code, we have to manually
manipulate the stack and therefore this section doesn't apply.

Let's look at various requirements and implement these using simple
examples. The following testing code exercises the interfaces we are
about to develop, so refer to this code to see how the functions are
invoked from Perl and what is returned:

  file:t/response/TestApache2/coredemo.pm
  ----------------------------------------
  package TestApache2::coredemo;
  
  use strict;
  use warnings FATAL => 'all';
  
  use Apache2::Const -compile => 'OK';
  
  use Apache::Test;
  use Apache::TestUtil;
  
  use Apache2::CoreDemo;
  
  sub handler {
      my $r = shift;
  
      plan $r, tests => 7;
  
      my $a = 7;
      my $b = 3;
      my ($add, $subst);
  
      $add = Apache2::CoreDemo::print($a, $b);
      t_debug "print";
      ok !$add;
  
      $add = Apache2::CoreDemo::add($a, $b);
      ok t_cmp($a + $b, $add, "add");
  
      $add = Apache2::CoreDemo::add_sv($a, $b);
      ok t_cmp($a + $b, $add, "add: return sv");
  
      $add = Apache2::CoreDemo::add_sv_sv($a, $b);
      ok t_cmp($a + $b, $add, "add: pass/return svs");
  
      ($add, $subst) = @{ Apache2::CoreDemo::add_subst($a, $b) };
      ok t_cmp($a + $b, $add,   "add_subst: add");
      ok t_cmp($a - $b, $subst, "add_subst: subst");
  
      $subst = Apache2::CoreDemo::subst_sp($a, $b);
      ok t_cmp($a - $b, $subst, "subst via SP");
  
      Apache2::Const::OK;
  }
  
  1;

The first case is the simplest: pass two integer arguments, print
these to the STDERR stream and return nothing:

  file:xs/Apache2/CoreDemo/Apache2__CoreDemo.h
  ----------------------------------------------
  static MP_INLINE
  void mpxs_Apache2__CoreDemo_print(int a, int b)
  {
      fprintf(stderr, "%d, %d\n", a, b);
  }

  file:xs/maps/modperl_functions.map
  ----------------------------------
  MODULE=Apache2::CoreDemo
   mpxs_Apache2__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
don't need to change the code, but simply adjust the map file to be:

  file:xs/maps/modperl_functions.map
  ----------------------------------
  MODULE=Apache2::CoreDemo
   mpxs_Apache2__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
example we tell WrapXS to assign a value of C<0> to the argument b, if
it wasn't supplied by the caller. All the arguments must be listed and
in the same order as they are defined in the function.

You may add an extra test that test teh default value assignment:

      $add = Apache2::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/Apache2/CoreDemo/Apache2__CoreDemo.h
  ----------------------------------------------
  static MP_INLINE
  int mpxs_Apache2__CoreDemo_add(int a, int b)
  {
      return a + b;
  }

  file:xs/maps/modperl_functions.map
  ----------------------------------
  MODULE=Apache2::CoreDemo
   mpxs_Apache2__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/Apache2/CoreDemo/Apache2__CoreDemo.h
  ----------------------------------------------
  static MP_INLINE
  SV *mpxs_Apache2__CoreDemo_add_sv(pTHX_ int a, int b)
  {
      return newSViv(a + b);
  }

  file:xs/maps/modperl_functions.map
  ----------------------------------
  MODULE=Apache2::CoreDemo
   mpxs_Apache2__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
return the scalar ourselves. This is of course to demonstrate that you
can return a Perl scalar, which can be a reference to a complex Perl
datastructure, which we will see in the fifth example.

The forth case demonstrates that you can pass Perl variables to your
functions without needing XSUB to do the conversion. In all previous
examples XSUB was automatically converting Perl scalars in the
argument list to the corresponding C variables, using the typemap
definitions.

  file:xs/Apache2/CoreDemo/Apache2__CoreDemo.h
  ----------------------------------------------
  static MP_INLINE
  SV *mpxs_Apache2__CoreDemo_add_sv_sv(pTHX_ SV *a_sv, SV *b_sv)
  {
      int a = (int)SvIV(a_sv);
      int b = (int)SvIV(b_sv);
      
      return newSViv(a + b);
  }

  file:xs/maps/modperl_functions.map
  ----------------------------------
  MODULE=Apache2::CoreDemo
   mpxs_Apache2__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
addition operation, convert the result to a Perl Scalar of kind I<IV>
(Integer Value) and return it directly to the caller.

In case where more than one value needs to be returned, we can still
implement this without directly manipulating the stack before a
function returns. The fifth case demonstrates a function that returns
the result of addition and substruction operations on its arguments:

  file:xs/Apache2/CoreDemo/Apache2__CoreDemo.h
  ----------------------------------------------
  static MP_INLINE
  SV *mpxs_Apache2__CoreDemo_add_subst(pTHX_ int a, int b)
  {
      AV *av = newAV();
  
      av_push(av, newSViv(a + b));
      av_push(av, newSViv(a - b));
  
      return newRV_noinc((SV*)av);   
  }

  file:xs/maps/modperl_functions.map
  ----------------------------------
  MODULE=Apache2::CoreDemo
   mpxs_Apache2__CoreDemo_add_subst

If you look at the corresponding testing code:

      ($add, $subst) = @{ Apache2::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<Apache2::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
structure, which represents an array. Since only the I<SV>
datastructures are allowed to be put on stack, we take a reference
I<RV> (which is of an I<SV> kind) to the existing I<AV> and return it.

The sixth case demonstrates a situation where the number of arguments
or their types may vary and aren't known at compile time. Though
notice that we still know that we are returning at compile time (zero
or one arguments), I<int> in this example:

  file:xs/Apache2/CoreDemo/Apache2__CoreDemo.h
  ----------------------------------------------
  static MP_INLINE
  int mpxs_Apache2__CoreDemo_subst_sp(pTHX_ I32 items, SV **MARK, SV **SP)
  {
      int a, b;
  
      if (items != 2) {
          Perl_croak(aTHX_ "usage: ...");
      }
      
      a = mp_xs_sv2_int(*MARK);
      b = mp_xs_sv2_int(*(MARK+1));
      
      return a - b;
  }

  file:xs/maps/modperl_functions.map
  ----------------------------------
  MODULE=Apache2::CoreDemo
   mpxs_Apache2__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
function. The macro C<MARK> points to the first argument passed by the
caller in the Perl namespace. For example to access the second
argument to retrieve the value of C<b> we use C<*(MARK+1)>, which if
you remember represented as an I<SV> variable, which nees to be
converted to the corresponding C type.

In this example we use the macro I<mp_xs_sv2_int>, automatically
generated based on the data from the I<xs/typemap> and
I<xs/maps/*_types.map> files, and placed into the
I<xs/modperl_xs_sv_convert.h> file. In the case of I<int> C type the
macro is:

  #define mp_xs_sv2_int(sv) (int)SvIV(sv)

which simply converts the I<SV> variable on the stack and generates an
I<int> value.

While in this example you have an access to the stack, you cannot
manipulate the return values, because the XSUB wrapper expects a
single return value of type I<int>, so even if you put something on
the stack it will be ignored.


=head2 Functions Returning Variable Number of Values

We saw earlier that if we want to return an array one of the ways to
go is to return a reference to an array as a single return value,
which fits the C paradigm. So we simply declare the return value as
C<SV*>.

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 its return
mechanism.

Let's rewrite the function C<mpxs_Apache2__CoreDemo_add_subst> from
the earlier section to return two results instead of a reference to a
list:

  file:xs/Apache2/CoreDemo/Apache2__CoreDemo.h
  ----------------------------------------------
  static XS(MPXS_Apache2__CoreDemo_add_subst_sp)
  {
      dXSARGS;
      int a, b;
      
      if (items != 2) {
          Perl_croak(aTHX_ "usage: Apache2::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=Apache2::CoreDemo
  DEFINE_add_subst_sp | MPXS_Apache2__CoreDemo_add_subst_sp | ...

The C<mpxs_> functions declare in the third column the arguments that
they expect to receive (and optionally the default values). The
C<MPXS> functions are the real C<XSUBs> and therefore they always
accept:

  aTHX_ I32 items, SP **sp, SV **MARK

as their arguments. Therefore it doesn't matter what is placed in this
column when the C<MPXS_> function is declared. Usually for
documentation the Perl side arguments are listed. For example you can
say:

  DEFINE_add_subst_sp | MPXS_Apache2__CoreDemo_add_subst_sp | x, y

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:

	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/TestApache2/coredemo.pm
  ----------------------------------------
  ...
  my $a = 7;
  my $b = 3;
  my ($add, $subst);
  
  # list context
  ($add, $subst) = Apache2::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 = Apache2::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/Apache2/CoreDemo/Apache2__CoreDemo.h
  ----------------------------------------------
  #define mpxs_Apache2__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=Apache2::CoreDemo
  double:DEFINE_power | | double:x, double:y

This works very similar to the C<MPXS_Apache2__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/TestApache2/coredemo.pm
  ----------------------------------------
  ...
  my $a = 7;
  my $b = 3;
  my $power = Apache2::CoreDemo::power($a, $b);
  ok t_cmp($a ** $b, $power, "power macro");
  ...

=head2 Passing aTHX for DEFINE map entries

Let's say you have a function or a C macro which you want to provide a
Perl interface for, and you don't need to write a wrapper since C
arguments are the same as Perl arguments. For example:

  char *foo(aTHX_ int bar);

The map entry will look like:

  MODULE=Apache2::CoreDemo
  char *:DEFINE_foo | | int:bar

But there is no way to pass C<aTHX_> since this is a macro and it's an
empty string with non-threaded Perls. Another macro comes to help:

  file:xs/Apache2/CoreDemo/Apache2__CoreDemo.h
  ----------------------------------------------
  #define mpxs_Apache2__CoreDemo_foo(x, y) foo(aTHX_ x, y)


=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_Apache2__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 for C<MPXS_> 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, but here we use C<x> and C<y> to
remind us that these two arguments are passed from Perl.

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_modperl_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=Apache2::CoreDemo
  modperl_power | MPXS_ | x, y | mypower

and the Perl function will be called C<Apache2::CoreDemo::mypower>.

The C<MPXS_> wrapper's implementation is similar to
L<MPXS_Apache2__CoreDemo_add_subst_sp
|/Functions_Returning_Variable_Number_of_Values>.

=head1 MP_INLINE vs C Macros vs Normal Functions

To make the code maintainable and reusable functions and macros are
used in when programming in C (and other languages :).

When function is marked as I<inlined> it's merely a hint to the
compiler to replace the call to a function with the code inside this
function (i.e. inlined). Not every function can be inlined. Some
typical reasons why inlining is sometimes not done include:

=over

=item *

the function calls itself, that is, is recursive

=item *

the function contains loops such as C<for(;;)> or C<while()>

=item *

the function size is too large

=back

Most of the advantage of inline functions comes from avoiding the
overhead of calling an actual function. Such overhead includes saving
registers, setting up stack frames, etc. But with large functions the
overhead becomes less important.

Use the C<MP_INLINE> keyword in the declaration of the functions that
are to be inlined. The functions should be inlined when:

=over

=item *

Only ever called once (the I<wrappers> that are called from I<.xs>
files), no matter what the size of code is.

=item *

Short bodies of code called in a I<hot> code (like
I<modperl_env_hv_store>, which is called many times inside of a loop),
where it is cleaner to see the code in function form rather than macro
with lots of C<\>'s. Remember that an inline function takes much more
space than a normal functions if called from many places in the code.

=back

Of course C macros are a bit faster then inlined functions, since
there is not even I<short jump> to be made, the code is literally
copied into the place it's called from. However using macros comes at
a price:

=over

=item *

Also unlike macros, in functions argument types are checked, and
necessary conversions are performed correctly. With macros it's
possible that weird things will happen if the caller has passed
arguments of the wrong type when calling a macro.

=item *

One should be careful to pass only absolute values as I<"arguments">
to macros. Consider a macro that returns an absolute value of the
passed argument:

  #define ABS(v) ( (v) >= 0 ? (v) : -(v) )

In our example if you happen to pass a function it will be called
twice:

  abs_val = ABS(f());

Since it'll be extended as:

  abs_val = f() >= 0 ? f() : -f();

You cannot do simple operation like increment--in our example it will
be called twice:

  abs_val = ABS(i++);

Because it becomes:

  abs_val = i++ >= 0 ? i++ : -i++;

=item *

It's dangerous to use the if() condition without enclosing the code in
C<{}>, since the macro may be called from inside another if-else
condition, which may cause the else part called if the if() part from
the macro fails.

But we always use C<{}> for the code inside the if-else condition, so
it's not a problem here.

=item *

A multi-line macro can cause problems if someone uses the macro in a
context that demands a single statement.

  while (foo) MYMACRO(bar);

But again, we always enclose any code in conditional with C<{}>, so
it's not a problem for us.

=item *

Inline functions present a problem for debuggers and profilers,
because the function is expanded at the point of call and loses its
identity. This makes the debugging process a nightmare.

A compiler will typically have some option available to disable
inlining.

=back

In all other cases use normal functions.

=head1 Adding New Interfaces



=head2 Adding Typemaps for new C Data Types

Sometimes when a new interface is added it may include C data types
for which we don't have corresponding XS typemaps yet. 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<Apache2::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 C<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/Apache2/ParseSource.pm>. To add a new type of C<DEFINE> constants
adjust the C<%defines_wanted> variable, for C<enums> modify
C<%enums_wanted>.

For example to import all C<DEFINE>s starting with C<APR_FLOCK_> add:

  my %defines_wanted = (
      ...
      APR => {
          ...
          flock     => [qw{APR_FLOCK_}],
          ...
      },
  );

When deciding which constants are to be exported, the regular
expression will be used, so in our example all matches
C</^APR_FLOCK_/> will be imported into the Perl API.

For example to import an I<read_type_e> C<enum> for APR, add:

  my %enums_wanted = (
      APR => { map { $_, 1 } qw(apr_read_type) },
  );

Notice that I<_e> part at the end of the enum name has gone.

in case of Apache constants remove the leading C<ap_> and terminating
C</_(t|e)$/>. For example I<ap_conn_keepalive_e> needs to be added as:

  my %enums_wanted = (
      Apache2 => { map { $_, 1 } qw(conn_keepalive) },
  );

After adding/modifying the datastructures make sure to run C<make
source_scan> or C<perl build/source_scan.pl> and verify that the
wanted constant or enum were picked by the source scanning
process. Simply grep I<xs/tables/current> for the wanted string. For
example after adding I<apr_read_type_e> enum we can check:

  % more xs/tables/current/Apache2/ConstantsTable.pm
  ...
    'read_type' => [
      'APR_BLOCK_READ',
      'APR_NONBLOCK_READ'
    ],

Of course the newly added constant or enum's typemap should be
declared in the appropriate I<xs/maps/*_types.map> files, so the XS
conversion of arguments will be performed correctly. For example
I<apr_read_type> is an APR enum so it's declared in
I<xs/maps/apr_types.map>:

  apr_read_type          | IV

C<IV> is used as a typemap, Since enum is just an integer. In more
complex cases the typemap can be different. (META: examples)


=head1 Maintainers

Maintainer is the person(s) you should contact with updates,
corrections and patches.

Stas Bekman [http://stason.org/]

=head1 Authors

=over 

=item *

Stas Bekman [http://stason.org/]

=back

Only the major authors are listed above. For contributors see the
Changes file.

=cut