Diff of /perl/modperl/docs/trunk/src/docs/2.0/api/APR/Status.pod

Parent Directory | Revision Log | Patch

--- perl/modperl/docs/trunk/src/docs/2.0/api/APR/Status.pod	2005/04/20 19:17:46	162038
+++ perl/modperl/docs/trunk/src/docs/2.0/api/APR/Status.pod	2005/04/20 19:18:58	162039
@@ -9,30 +9,32 @@ APR::Status - Perl Interface to the APR_
   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 @@ The purpose of C<APR::Status> is to prov
 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