NAME

APR::Status - Perl Interface to the APR_STATUS_IS_* macros

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
}

Description

An interface to apr_errno.h composite error codes.

As discussed in the 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 $some_code is an APR::Const constant, there may be more than one condition satisfying the intent of this exception. For this purpose the APR C library provides in apr_errno.h a series of macros, APR_STATUS_IS_*, which are the recommended way to check for such conditions. For example, the 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 APR::Status is to provide functions corresponding to these macros.

Functions

is_EAGAIN

Check if the error is matching EAGAIN and its variants (corresponds to the APR_STATUS_IS_EAGAIN macro).

$status = APR::Status::is_EAGAIN($error_code);

arg1: $error_code (integer or APR::Error object )

The error code or to check, normally $@ blessed into APR::Error object.

ret: $status ( boolean )

since: 1.999.23

For example, here is how you may want to handle socket read exceptions and do retries:

use APR::Status ();
# ....
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 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 APR::Const::EAGAIN unless you know what you are doing.

See Also

mod_perl 2.0 documentation.

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

Authors

The mod_perl development team and numerous contributors.