svn commit: r162039 - in /perl/modperl/docs/trunk/src/docs/2.0/api/APR: Const.pod Status.pod

[st...@apache.org]

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<Resource temporarily unavailable>, 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<L<APR::Status::is_EAGAIN|docs::2.0::api::APR::Status/C_is_EAGAIN_>>
+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<APR::Error documentation|docs::2.0::api::APR::Error>,
-it is possible to handle APR/Apache/mod_perl exceptions
-in the following way:
+An interface to F<apr_errno.h> composite error codes.
+
+As discussed in the C<L<APR::Error|docs::2.0::api::APR::Error>>
+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<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
+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 \
@@ -43,19 +45,58 @@
 to these macros.
 
 
+
+
 =head1 Functions
 
 
 
 =head2 C<is_EAGAIN>
 
+Check if the error is matching C<EAGAIN> and its variants (corresponds
+to the C<APR_STATUS_IS_EAGAIN> macro).
+
+  $status = APR::Status::is_EAGAIN($error_code);
+
+=over 4
+
+=item arg1: C<$error_code> (integer or C<L<APR::Error
+object|docs::2.0::api::APR::Error>> )
+
+The error code or to check, normally C<$@> blessed into C<L<APR::Error
+object|docs::2.0::api::APR::Error>>.
+
+=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<L<APR::Const::EAGAIN|docs::2.0::api::APR::Const/C_APR__Const__EAGAIN_>>
+may work on some Unices, but then it will certainly break on
+win32. Thefore make sure to use this macro and not
+C<APR::Const::EAGAIN> unless you know what you are doing.
 
-This corresponds to the C<APR_STATUS_IS_EAGAIN> macro.
 
 
 =head1 See Also



---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org