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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]