Parent Directory
| 
Revision Log
| 
Patch
--- perl/modperl/docs/trunk/src/docs/2.0/devel/core/explained.pod 2005/04/02 22:46:23 159840
+++ perl/modperl/docs/trunk/src/docs/2.0/devel/core/explained.pod 2005/04/02 22:53:42 159841
@@ -13,7 +13,7 @@ new functionality.
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 Apache::* modules
+ Apache-Test/ - test kit for mod_perl and Apache2::* modules
ModPerl-Registry/ - ModPerl::Registry sub-project
build/ - utilities used during project build
docs/ - documentation
@@ -50,20 +50,20 @@ they will be picked up by the autogenera
=head1 Directory xs/
- Apache/ - 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 -
+ 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/Apache, xs/APR and xs/ModPerl
+=head2 xs/Apache2, xs/APR and xs/ModPerl
-The I<xs/Apache>, I<xs/APR> and I<xs/ModPerl> directories include I<.h> files which
+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
@@ -110,8 +110,8 @@ the Apache API Perl glue and mod_perl sp
If you need to skip certain unwanted C defines from being picked by
the source scanning you can add them to the array
-C<$Apache::ParseSource::defines_unwanted> in
-I<lib/Apache/ParseSource.pm>.
+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,
@@ -164,15 +164,15 @@ where:
=item * C<MODULE>
the module name where the functions should be put. e.g. C<MODULE
-Apache::Connection> will place the functions into
-I<WrapXS/Apache/Connection.{pm,xs}>.
+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<Apache>
+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.
@@ -245,7 +245,7 @@ Function names that do not begin with C<
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<{Apache,ModPerl}::FunctionTable>.
+defaults to I<return_type> in C<{Apache2,ModPerl}::FunctionTable>.
META: DEFINE nuances
@@ -260,7 +260,7 @@ See the explanation about function namin
=item * Argspec
The argspec defaults to arguments in
-C<{Apache,ModPerl}::FunctionTable>. Argument types can be specified
+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
@@ -395,19 +395,19 @@ examples. The following testing code exe
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/coredemo.pm
+ file:t/response/TestApache2/coredemo.pm
----------------------------------------
- package TestApache::coredemo;
+ package TestApache2::coredemo;
use strict;
use warnings FATAL => 'all';
- use Apache::Const -compile => 'OK';
+ use Apache2::Const -compile => 'OK';
use Apache::Test;
use Apache::TestUtil;
- use Apache::CoreDemo;
+ use Apache2::CoreDemo;
sub handler {
my $r = shift;
@@ -418,27 +418,27 @@ invoked from Perl and what is returned:
my $b = 3;
my ($add, $subst);
- $add = Apache::CoreDemo::print($a, $b);
+ $add = Apache2::CoreDemo::print($a, $b);
t_debug "print";
ok !$add;
- $add = Apache::CoreDemo::add($a, $b);
+ $add = Apache2::CoreDemo::add($a, $b);
ok t_cmp($a + $b, $add, "add");
- $add = Apache::CoreDemo::add_sv($a, $b);
+ $add = Apache2::CoreDemo::add_sv($a, $b);
ok t_cmp($a + $b, $add, "add: return sv");
- $add = Apache::CoreDemo::add_sv_sv($a, $b);
+ $add = Apache2::CoreDemo::add_sv_sv($a, $b);
ok t_cmp($a + $b, $add, "add: pass/return svs");
- ($add, $subst) = @{ Apache::CoreDemo::add_subst($a, $b) };
+ ($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 = Apache::CoreDemo::subst_sp($a, $b);
+ $subst = Apache2::CoreDemo::subst_sp($a, $b);
ok t_cmp($a - $b, $subst, "subst via SP");
- Apache::OK;
+ Apache2::OK;
}
1;
@@ -446,18 +446,18 @@ invoked from Perl and what is returned:
The first case is the simplest: pass two integer arguments, print
these to the STDERR stream and return nothing:
- file:xs/Apache/CoreDemo/Apache__CoreDemo.h
+ file:xs/Apache2/CoreDemo/Apache2__CoreDemo.h
----------------------------------------------
static MP_INLINE
- void mpxs_Apache__CoreDemo_print(int a, int b)
+ void mpxs_Apache2__CoreDemo_print(int a, int b)
{
fprintf(stderr, "%d, %d\n", a, b);
}
file:xs/maps/modperl_functions.map
----------------------------------
- MODULE=Apache::CoreDemo
- mpxs_Apache__CoreDemo_print
+ 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
@@ -465,8 +465,8 @@ don't need to change the code, but simpl
file:xs/maps/modperl_functions.map
----------------------------------
- MODULE=Apache::CoreDemo
- mpxs_Apache__CoreDemo_print | | a, b=0
+ 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
@@ -476,40 +476,40 @@ in the same order as they are defined in
You may add an extra test that test teh default value assignment:
- $add = Apache::CoreDemo::add($a);
+ $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/Apache/CoreDemo/Apache__CoreDemo.h
+ file:xs/Apache2/CoreDemo/Apache2__CoreDemo.h
----------------------------------------------
static MP_INLINE
- int mpxs_Apache__CoreDemo_add(int a, int b)
+ int mpxs_Apache2__CoreDemo_add(int a, int b)
{
return a + b;
}
file:xs/maps/modperl_functions.map
----------------------------------
- MODULE=Apache::CoreDemo
- mpxs_Apache__CoreDemo_add
+ 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/Apache/CoreDemo/Apache__CoreDemo.h
+ file:xs/Apache2/CoreDemo/Apache2__CoreDemo.h
----------------------------------------------
static MP_INLINE
- SV *mpxs_Apache__CoreDemo_add_sv(pTHX_ int a, int b)
+ SV *mpxs_Apache2__CoreDemo_add_sv(pTHX_ int a, int b)
{
return newSViv(a + b);
}
file:xs/maps/modperl_functions.map
----------------------------------
- MODULE=Apache::CoreDemo
- mpxs_Apache__CoreDemo_add_sv
+ 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
@@ -523,10 +523,10 @@ examples XSUB was automatically converti
argument list to the corresponding C variables, using the typemap
definitions.
- file:xs/Apache/CoreDemo/Apache__CoreDemo.h
+ file:xs/Apache2/CoreDemo/Apache2__CoreDemo.h
----------------------------------------------
static MP_INLINE
- SV *mpxs_Apache__CoreDemo_add_sv_sv(pTHX_ SV *a_sv, SV *b_sv)
+ 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);
@@ -536,8 +536,8 @@ definitions.
file:xs/maps/modperl_functions.map
----------------------------------
- MODULE=Apache::CoreDemo
- mpxs_Apache__CoreDemo_add_sv_sv
+ 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
@@ -549,10 +549,10 @@ implement this without directly manipula
function returns. The fifth case demonstrates a function that returns
the result of addition and substruction operations on its arguments:
- file:xs/Apache/CoreDemo/Apache__CoreDemo.h
+ file:xs/Apache2/CoreDemo/Apache2__CoreDemo.h
----------------------------------------------
static MP_INLINE
- SV *mpxs_Apache__CoreDemo_add_subst(pTHX_ int a, int b)
+ SV *mpxs_Apache2__CoreDemo_add_subst(pTHX_ int a, int b)
{
AV *av = newAV();
@@ -564,18 +564,18 @@ the result of addition and substruction
file:xs/maps/modperl_functions.map
----------------------------------
- MODULE=Apache::CoreDemo
- mpxs_Apache__CoreDemo_add_subst
+ MODULE=Apache2::CoreDemo
+ mpxs_Apache2__CoreDemo_add_subst
If you look at the corresponding testing code:
- ($add, $subst) = @{ Apache::CoreDemo::add_subst($a, $b) };
+ ($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<Apache::CoreDemo::add_sv> function which
+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
@@ -588,10 +588,10 @@ or their types may vary and aren't known
notice that we still know that we are returning at compile time (zero
or one arguments), I<int> in this example:
- file:xs/Apache/CoreDemo/Apache__CoreDemo.h
+ file:xs/Apache2/CoreDemo/Apache2__CoreDemo.h
----------------------------------------------
static MP_INLINE
- int mpxs_Apache__CoreDemo_subst_sp(pTHX_ I32 items, SV **MARK, SV **SP)
+ int mpxs_Apache2__CoreDemo_subst_sp(pTHX_ I32 items, SV **MARK, SV **SP)
{
int a, b;
@@ -607,8 +607,8 @@ or one arguments), I<int> in this exampl
file:xs/maps/modperl_functions.map
----------------------------------
- MODULE=Apache::CoreDemo
- mpxs_Apache__CoreDemo_subst_sp | | ...
+ 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
@@ -647,19 +647,19 @@ many return values will be or it's known
one return value--something that C cannot handle via its return
mechanism.
-Let's rewrite the function C<mpxs_Apache__CoreDemo_add_subst> from
+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/Apache/CoreDemo/Apache__CoreDemo.h
+ file:xs/Apache2/CoreDemo/Apache2__CoreDemo.h
----------------------------------------------
- static XS(MPXS_Apache__CoreDemo_add_subst_sp)
+ static XS(MPXS_Apache2__CoreDemo_add_subst_sp)
{
dXSARGS;
int a, b;
if (items != 2) {
- Perl_croak(aTHX_ "usage: Apache::CoreDemo::add_subst_sp($a, $b)");
+ 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));
@@ -683,8 +683,8 @@ file:
file:xs/maps/modperl_functions.map
----------------------------------
- MODULE=Apache::CoreDemo
- DEFINE_add_subst_sp | MPXS_Apache__CoreDemo_add_subst_sp | ...
+ 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
@@ -698,7 +698,7 @@ column when the C<MPXS_> function is dec
documentation the Perl side arguments are listed. For example you can
say:
- DEFINE_add_subst_sp | MPXS_Apache__CoreDemo_add_subst_sp | x, y
+ 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
@@ -772,7 +772,7 @@ the stack manipulation process in great
Finally we test the function in the list and scalar contexts:
- file:t/response/TestApache/coredemo.pm
+ file:t/response/TestApache2/coredemo.pm
----------------------------------------
...
my $a = 7;
@@ -780,12 +780,12 @@ Finally we test the function in the list
my ($add, $subst);
# list context
- ($add, $subst) = Apache::CoreDemo::add_subst_sp($a, $b);
+ ($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 = Apache::CoreDemo::add_subst_sp($a, $b);
+ $add = Apache2::CoreDemo::add_subst_sp($a, $b);
ok t_cmp($a + $b, $add, "add_subs_spt scalar context: add");
...
@@ -795,18 +795,18 @@ Let's say you have a C macro which you w
interface for. For example let's take a simple macro which performs
the power of function:
- file:xs/Apache/CoreDemo/Apache__CoreDemo.h
+ file:xs/Apache2/CoreDemo/Apache2__CoreDemo.h
----------------------------------------------
- #define mpxs_Apache__CoreDemo_power(x, y) pow(x, y)
+ #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=Apache::CoreDemo
+ MODULE=Apache2::CoreDemo
double:DEFINE_power | | double:x, double:y
-This works very similar to the C<MPXS_Apache__CoreDemo_add_subst_sp>
+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
@@ -816,12 +816,12 @@ 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
+ file:t/response/TestApache2/coredemo.pm
----------------------------------------
...
my $a = 7;
my $b = 3;
- my $power = Apache::CoreDemo::power($a, $b);
+ my $power = Apache2::CoreDemo::power($a, $b);
ok t_cmp($a ** $b, $power, "power macro");
...
@@ -835,15 +835,15 @@ arguments are the same as Perl arguments
The map entry will look like:
- MODULE=Apache::CoreDemo
+ 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/Apache/CoreDemo/Apache__CoreDemo.h
+ file:xs/Apache2/CoreDemo/Apache2__CoreDemo.h
----------------------------------------------
- #define mpxs_Apache__CoreDemo_foo(x, y) foo(aTHX_ x, y)
+ #define mpxs_Apache2__CoreDemo_foo(x, y) foo(aTHX_ x, y)
=head1 Wrappers for modperl_, apr_ and ap_ APIs
@@ -851,7 +851,7 @@ empty string with non-threaded Perls. An
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
+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.
@@ -889,13 +889,13 @@ Perl function's name in the forth column
file:xs/maps/apr_functions.map
----------------------------------
- MODULE=Apache::CoreDemo
+ MODULE=Apache2::CoreDemo
modperl_power | MPXS_ | x, y | mypower
-and the Perl function will be called C<Apache::CoreDemo::mypower>.
+and the Perl function will be called C<Apache2::CoreDemo::mypower>.
The C<MPXS_> wrapper's implementation is similar to
-L<MPXS_Apache__CoreDemo_add_subst_sp
+L<MPXS_Apache2__CoreDemo_add_subst_sp
|/Functions_Returning_Variable_Number_of_Values>.
=head1 MP_INLINE vs C Macros vs Normal Functions
@@ -1058,7 +1058,7 @@ typemap in the autogenerated I<WrapXS/ty
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
+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.
@@ -1093,7 +1093,7 @@ Now proceed on adding the glue code for
=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
+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>.
@@ -1124,7 +1124,7 @@ in case of Apache constants remove the l
C</_(t|e)$/>. For example I<ap_conn_keepalive_e> needs to be added as:
my %enums_wanted = (
- Apache => { map { $_, 1 } qw(conn_keepalive) },
+ Apache2 => { map { $_, 1 } qw(conn_keepalive) },
);
After adding/modifying the datastructures make sure to run C<make
@@ -1133,7 +1133,7 @@ wanted constant or enum were picked by t
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/Apache/ConstantsTable.pm
+ % more xs/tables/current/Apache2/ConstantsTable.pm
...
'read_type' => [
'APR_BLOCK_READ',
| infrastructure at apache.org | ViewVC Help |
| Powered by ViewVC 1.1.26 |