You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs-cvs@perl.apache.org by ra...@apache.org on 2005/04/03 00:53:43 UTC
svn commit: r159841 - in perl/modperl/docs/trunk/src/docs/2.0/devel/core:
coding_style.pod explained.pod
Author: randyk
Date: Sat Apr 2 14:53:42 2005
New Revision: 159841
URL: http://svn.apache.org/viewcvs?view=rev&rev=159841
Log:
s/Apache/Apache2/
Modified:
perl/modperl/docs/trunk/src/docs/2.0/devel/core/coding_style.pod
perl/modperl/docs/trunk/src/docs/2.0/devel/core/explained.pod
Modified: perl/modperl/docs/trunk/src/docs/2.0/devel/core/coding_style.pod
URL: http://svn.apache.org/viewcvs/perl/modperl/docs/trunk/src/docs/2.0/devel/core/coding_style.pod?view=diff&r1=159840&r2=159841
==============================================================================
--- perl/modperl/docs/trunk/src/docs/2.0/devel/core/coding_style.pod (original)
+++ perl/modperl/docs/trunk/src/docs/2.0/devel/core/coding_style.pod Sat Apr 2 14:53:42 2005
@@ -221,7 +221,7 @@
use IO::File ();
-(explain how to use Apache::Status to find imported/exported
+(explain how to use Apache2::Status to find imported/exported
functions)
=back
Modified: perl/modperl/docs/trunk/src/docs/2.0/devel/core/explained.pod
URL: http://svn.apache.org/viewcvs/perl/modperl/docs/trunk/src/docs/2.0/devel/core/explained.pod?view=diff&r1=159840&r2=159841
==============================================================================
--- perl/modperl/docs/trunk/src/docs/2.0/devel/core/explained.pod (original)
+++ perl/modperl/docs/trunk/src/docs/2.0/devel/core/explained.pod Sat Apr 2 14:53:42 2005
@@ -13,7 +13,7 @@
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 @@
=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 @@
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 @@
=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 @@
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 @@
=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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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: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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
=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 @@
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 @@
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',
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org