svn commit: r162039 - in /perl/modperl/docs/trunk/src/docs/2.0/api/APR: Const.pod Status.pod
Author: stas
Date: Wed Apr 20 12:18:58 2005
New Revision: 162039
URL: http://svn.apache.org/viewcvs?rev=162039&view=rev
Log:
improve the APR::Status docs
Modified:
perl/modperl/docs/trunk/src/docs/2.0/api/APR/Const.pod
perl/modperl/docs/trunk/src/docs/2.0/api/APR/Status.pod
Modified: perl/modperl/docs/trunk/src/docs/2.0/api/APR/Const.pod
URL:
http://svn.apache.org/viewcvs/perl/modperl/docs/trunk/src/docs/2.0/api/APR/Const.pod?rev=162039&r1=162038&r2=162039&view=diff
==
--- perl/modperl/docs/trunk/src/docs/2.0/api/APR/Const.pod (original)
+++ perl/modperl/docs/trunk/src/docs/2.0/api/APR/Const.pod Wed Apr 20 12:18:58
2005
@@ -117,7 +117,10 @@
=back
The error I, may be returned by many
-different system calls, especially IO calls.
+different system calls, especially IO calls. Most likely you want to
+use the
+C>
+function instead.
Modified: perl/modperl/docs/trunk/src/docs/2.0/api/APR/Status.pod
URL:
http://svn.apache.org/viewcvs/perl/modperl/docs/trunk/src/docs/2.0/api/APR/Status.pod?rev=162039&r1=162038&r2=162039&view=diff
==
--- perl/modperl/docs/trunk/src/docs/2.0/api/APR/Status.pod (original)
+++ perl/modperl/docs/trunk/src/docs/2.0/api/APR/Status.pod Wed Apr 20 12:18:58
2005
@@ -9,30 +9,32 @@
use APR::Status ();
eval { $obj->mp_method() };
if ($@ && $ref $@ eq 'APR::Error' && APR::Status::is_EAGAIN($@)) {
-# APR_STATUS_IS_EAGAIN(s) of apr_errno.h is satisfied
+ # APR_STATUS_IS_EAGAIN(s) of apr_errno.h is satisfied
}
+
+
=head1 Description
-As discussed in the
-L,
-it is possible to handle APR/Apache/mod_perl exceptions
-in the following way:
+An interface to F composite error codes.
+
+As discussed in the C>
+manpage, it is possible to handle APR/Apache/mod_perl exceptions in
+the following way:
eval { $obj->mp_method() };
if ($@ && $ref $@ eq 'APR::Error' && $@ == $some_code)
warn "handled exception: $@";
}
-However, in cases where C<$some_code> is an
-L,
-there may be more than one condition satisfying the
-intent of this exception. For this purpose the APR C
-library provides in F a series of macros,
-C, which are the recommended way to check
-for such conditions. For example, the C
-macro is defined as
+However, in cases where C<$some_code> is an L, there may be more than one
+condition satisfying the intent of this exception. For this purpose
+the APR C library provides in F a series of macros,
+C, which are the recommended way to check for such
+conditions. For example, the C macro is defined
+as
#define APR_STATUS_IS_EAGAIN(s) ((s) == APR_EAGAIN \
|| (s) == APR_OS_START_SYSERR + ERROR_NO_DATA \
@@ -43,19 +45,58 @@
to these macros.
+
+
=head1 Functions
=head2 C
+Check if the error is matching C and its variants (corresponds
+to the C macro).
+
+ $status = APR::Status::is_EAGAIN($error_code);
+
+=over 4
+
+=item arg1: C<$error_code> (integer or C> )
+
+The error code or to check, normally C<$@> blessed into C>.
+
+=item ret: C<$status> ( boolean )
+
+=item since: 1.999.23
+
+=back
+
+For example, here is how you may want to handle socket read exceptions
+and do retries:
+
use APR::Status ();
#
- if ($@ && $ref $@ eq 'APR::Error' && APR::Status::is_EAGAIN($@)) {
-# APR_STATUS_IS_EAGAIN(s) of apr_errno.h is satisfied
+ my $tries = 0;
+ RETRY: eval { $socket->recv(my $buffer, SIZE) };
+ if ($@ && ref($@) && APR::Status::is_EAGAIN($@)) {
+ if ($tries++ < 3) {
+ goto RETRY;
+ }
+ else {
+ # do something else
+ }
}
+ else {
+ die "eval block has failed: $@";
+ }
+
+Notice that just checking against
+C>
+may work on some Unices, but then it will certainly break on
+win32. Thefore make sure to use this macro and not
+C unless you know what you are doing.
-This corresponds to the C macro.
=head1 See Also
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
svn commit: r162015 - in perl/modperl/docs/trunk/src/docs/2.0/api: APR/Error.pod APR/Status.pod config.cfg
Author: randyk
Date: Tue Apr 19 22:14:07 2005
New Revision: 162015
URL: http://svn.apache.org/viewcvs?view=rev&rev=162015
Log:
add documentation for APR::Status.
Added:
perl/modperl/docs/trunk/src/docs/2.0/api/APR/Status.pod (with props)
Modified:
perl/modperl/docs/trunk/src/docs/2.0/api/APR/Error.pod
perl/modperl/docs/trunk/src/docs/2.0/api/config.cfg
Modified: perl/modperl/docs/trunk/src/docs/2.0/api/APR/Error.pod
URL:
http://svn.apache.org/viewcvs/perl/modperl/docs/trunk/src/docs/2.0/api/APR/Error.pod?view=diff&r1=162014&r2=162015
==
--- perl/modperl/docs/trunk/src/docs/2.0/api/APR/Error.pod (original)
+++ perl/modperl/docs/trunk/src/docs/2.0/api/APR/Error.pod Tue Apr 19 22:14:07
2005
@@ -132,6 +132,12 @@
outside mod_perl as well, when called from
C> applications written in Perl.
+It is worth noting that APR provides some macros in F,
+C, which are the recommended way to check for
+some error conditions, especially in cases when different
+circumstances can lead to the intent of a single condition.
+See the L
+for an interface to some of these macros.
=head1 API
Added: perl/modperl/docs/trunk/src/docs/2.0/api/APR/Status.pod
URL:
http://svn.apache.org/viewcvs/perl/modperl/docs/trunk/src/docs/2.0/api/APR/Status.pod?view=auto&rev=162015
==
--- perl/modperl/docs/trunk/src/docs/2.0/api/APR/Status.pod (added)
+++ perl/modperl/docs/trunk/src/docs/2.0/api/APR/Status.pod Tue Apr 19 22:14:07
2005
@@ -0,0 +1,78 @@
+=head1 NAME
+
+APR::Status - Perl Interface to the APR_STATUS_IS_* macros
+
+
+
+=head1 Synopsis
+
+ use APR::Status ();
+ eval { $obj->mp_method() };
+ if ($@ && $ref $@ eq 'APR::Error' && APR::Status::is_EAGAIN($@)) {
+# APR_STATUS_IS_EAGAIN(s) of apr_errno.h is satisfied
+ }
+
+
+=head1 Description
+
+As discussed in the
+L,
+it is possible to handle APR/Apache/mod_perl exceptions
+in the following way:
+
+ eval { $obj->mp_method() };
+ if ($@ && $ref $@ eq 'APR::Error' && $@ == $some_code)
+ warn "handled exception: $@";
+ }
+
+However, in cases where C<$some_code> is an
+L,
+there may be more than one condition satisfying the
+intent of this exception. For this purpose the APR C
+library provides in F a series of macros,
+C, which are the recommended way to check
+for such conditions. For example, the C
+macro is defined as
+
+ #define APR_STATUS_IS_EAGAIN(s) ((s) == APR_EAGAIN \
+ || (s) == APR_OS_START_SYSERR + ERROR_NO_DATA \
+ || (s) == APR_OS_START_SYSERR + SOCEWOULDBLOCK \
+ || (s) == APR_OS_START_SYSERR + ERROR_LOCK_VIOLATION)
+
+The purpose of C is to provide functions corresponding
+to these macros.
+
+
+=head1 Functions
+
+
+
+=head2 C
+
+ use APR::Status ();
+ #
+ if ($@ && $ref $@ eq 'APR::Error' && APR::Status::is_EAGAIN($@)) {
+# APR_STATUS_IS_EAGAIN(s) of apr_errno.h is satisfied
+ }
+
+This corresponds to the C macro.
+
+
+=head1 See Also
+
+L.
+
+
+=head1 Copyright
+
+mod_perl 2.0 and its core modules are copyrighted under
+The Apache Software License, Version 2.0.
+
+
+
+=head1 Authors
+
+L.
+
+=cut
Propchange: perl/modperl/docs/trunk/src/docs/2.0/api/APR/Status.pod
--
svn:eol-style = native
Modified: perl/modperl/docs/trunk/src/docs/2.0/api/config.cfg
URL:
http://svn.apache.org/viewcvs/perl/modperl/docs/trunk/src/docs/2.0/api/config.cfg?view=diff&r1=162014&r2=162015
==
--- perl/modperl/docs/trunk/src/docs/2.0/api/config.cfg (original)
+++ perl/modperl/docs/trunk/src/docs/2.0/api/config.cfg Tue Apr 19 22:14:07 2005
@@ -60,6 +60,7 @@
APR/Pool.pod
APR/SockAddr.pod
APR/Socket.pod
+APR/Status.pod
APR/String.pod
APR/Table.pod
APR/ThreadMutex.pod
-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
