|
APR::Error - Perl API for APR/Apache/mod_perl exceptions |
APR::Error - Perl API for APR/Apache/mod_perl exceptions
eval { $obj->mp_method() };
if ($@ && $ref $@ eq 'APR::Error' && $@ == $some_code) {
# handle the exception
}
else {
die $@; # rethrow it
}
APR::Error handles APR/Apache/mod_perl exceptions for you, while
leaving you in control.
Apache and APR API return a status code for almost all methods, so if you didn't check the return code and handled any possible problems, you may have silent failures which may cause all kind of obscure problems. On the other hand checking the status code after each call is just too much of a kludge and makes quick prototyping/development almost impossible, not talking about the code readability. Having methods return status codes, also complicates the API if you need to return other values.
Therefore to keep things nice and make the API readable we decided to
not return status codes, but instead throw exceptions with
APR::Error objects for each method that fails. If you don't catch
those exceptions, everything works transparently - perl will intercept
the exception object and die() with a proper error message. So you
get all the errors logged without doing any work.
Now, in certain cases you don't want to just die, but instead the error needs to be trapped and handled. For example if some IO operation times out, may be it is OK to trap that and try again. If we were to die with an error message, you would have had to match the error message, which is ugly, inefficient and may not work at all if locale error strings are involved. Therefore you need to be able to get the original status code that Apache or APR has generated. And the exception objects give you that if you want to. Moreover the objects contain additional information, such as the function name (in case you were eval'ing several commands in one block), file and line number where that function was invoked from. More attributes could be added in the future.
APR::Error uses Perl operator overloading, such that in boolean and
numerical contexts, the object returns the status code; in the string
context the full error message is returned.
When intercepting exceptions you need to check whether $@ is an
object (reference). If your application uses other exception objects
you additionally need to check whether this is a an APR::Error
object. Therefore most of the time this is enough:
eval { $obj->mp_method() };
if ($@ && $ref $@ && $@ == $some_code)
warn "handled exception: $@";
}
But with other, non-mod_perl, exception objects you need to do:
eval { $obj->mp_method() };
if ($@ && $ref $@ eq 'APR::Error' && $@ == $some_code)
warn "handled exception: $@";
}
In theory you could even do:
eval { $obj->mp_method() };
if ($@ && $@ == $some_code)
warn "handled exception: $@";
}
but it's possible that the method will die with a plain string and not
an object, in which case $@ == $some_code won't quite
work. Remember that mod_perl throws exception objects only when Apache
and APR fail, and in a few other special cases of its own (like
exit|docs::2.0::api::ModPerl::Util/C_exit_).
warn "handled exception: $@" if $@ && $ref $@;
For example you wrote a code that performs a socket read:
my $rlen = $sock->recv(my $buff, 1024); warn "read $rlen bytes\n";
and in certain cases it times out. The code will die and log the reason for the failure, which is fine, but later on you may decide that you want to have another attempt to read before dying. In which case you rewrite the code to handle the exception like this:
use APR::Const -compile => qw(TIMEUP);
my $buff;
my $tries = 0;
RETRY: my $rlen = eval { $sock->recv($buff, 1024) };
if ($@) {
die $@ unless ref $@ && $@ == APR::TIMEUP;
goto RETRY if $tries++ < 3;
}
warn "read $rlen bytes\n";
Notice that we handle non-object and non-APR::Error exceptions as
well, by simply rethrowing them.
You certainly want to have a limit on how many times the code retries
the operation as in this example and you probably want to add some
fine grained sleep time between attempts, which can be achieved with
select. As a result the retry code may look like this:
use APR::Const -compile => qw(TIMEUP);
my $tries = 0;
RETRY: my $rlen = eval { $sock->recv($buff, 1024) };
if ($@) {
die $@ unless ref $@ && $@ == APR::TIMEUP;
if ($tries++ < 3) {
# sleep 250msec
select undef, undef, undef, 0.25;
goto RETRY;
}
}
warn "read $rlen bytes\n";
Finally, the class is called APR::Error because it needs to be used
outside mod_perl as well, when called from
APR|docs::2.0::api::APR applications written in Perl.
cluckcluck is an equivalent of Carp::cluck that works with
APR::Error exception objects.
confessconfess is an equivalent of Carp::confess that works with
APR::Error exception objects.
strerrorConvert APR error code to its string representation.
$error_str = APR::Error::strerror($rc);
$rc ( APR::Const status
constant|docs::2.0::api::APR::Const> )$error_str ( string )$rc. (Similar to the C function strerror(3))
Example:
Try to retrieve the bucket brigade, and if the return value doesn't indicate success or end of file (usually in protocol handlers) die, but give the user the human-readable version of the error and not just the code.
my $rc = $c->input_filters->get_brigade($bb_in,
Apache::MODE_GETLINE);
if ($rc != APR::SUCCESS && $rc != APR::EOF) {
my $error = APR::Error::strerror($rc);
die "get_brigade error: $rc: $error\n";
}
It's probably a good idea not to omit the numerical value in the error message, in case the error string is generated with non-English locale.
mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.
The mod_perl development team and numerous contributors.
|
APR::Error - Perl API for APR/Apache/mod_perl exceptions |