svn commit: r162015 - in perl/modperl/docs/trunk/src/docs/2.0/api: APR/Error.pod APR/Status.pod config.cfg

[ra...@apache.org]

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<L<APR|docs::2.0::api::APR>> applications written in Perl.
 
+It is worth noting that APR provides some macros in F<apr_errno.h>,
+C<APR_STATUS_IS_*>, 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<APR::Status documentation|docs::2.0::api::APR::Status>
+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<APR::Error documentation|docs::2.0::api::APR::Error>,
+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<APR::Const constant|docs::2.0::api::APR::Const>,
+there may be more than one condition satisfying the
+intent of this exception. For this purpose the APR C
+library provides in F<apr_errno.h> a series of macros, 
+C<APR_STATUS_IS_*>, which are the recommended way to check 
+for such conditions. For example, the C<APR_STATUS_IS_EAGAIN>
+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<APR::Status> is to provide functions corresponding
+to these macros.
+
+
+=head1 Functions
+
+
+
+=head2 C<is_EAGAIN>
+
+  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<APR_STATUS_IS_EAGAIN> macro.
+
+
+=head1 See Also
+
+L<mod_perl 2.0 documentation|docs::2.0::index>.
+
+
+=head1 Copyright
+
+mod_perl 2.0 and its core modules are copyrighted under
+The Apache Software License, Version 2.0.
+
+
+
+=head1 Authors
+
+L<The mod_perl development team and numerous
+contributors|about::contributors::people>.
+
+=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: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org