3
APR::Error - Perl API for APR/Apache/mod_perl exceptions
10
eval { $obj->mp_method() };
11
if ($@ && $ref $@ eq 'APR::Error' && $@ == $some_code) {
12
# handle the exception
21
C<APR::Error> handles APR/Apache/mod_perl exceptions for you, while
22
leaving you in control.
24
Apache and APR API return status code for almost all methods, so if
25
you didn't check the return code and handled any possible problems,
26
you may have silent failures which may cause all kind of obscure
27
problems. On the other hand checking the status code after each call
28
is just too much of a kludge and makes quick prototyping/development
29
almost impossible, not talking about the code readability. Having
30
methods return status codes, also complicates the API if you need to
33
Therefore to keep things nice and make the API readable we decided to
34
not return status codes, but instead throw exceptions with
35
C<APR::Error> objects for each method that fails. If you don't catch
36
those exceptions, everything works transparently - perl will intercept
37
the exception object and C<die()> with a proper error message. So you
38
get all the errors logged without doing any work.
40
Now, in certain cases you don't want to just die, but instead the
41
error needs to be trapped and handled. For example if some IO
42
operation times out, may be it is OK to trap that and try again. If we
43
were to die with an error message, you would have had to match the
44
error message, which is ugly, inefficient and may not work at all if
45
locale error strings are involved. Therefore you need to be able to
46
get the original status code that Apache or APR has generated. And the
47
exception objects give you that if you want to. Moreover the objects
48
contain additional information, such as the function name (in case you
49
were eval'ing several commands in one block), file and line number
50
where that function was invoked from. More attributes could be added
53
C<APR::Error> uses method overloading, such that in boolean and
54
numerical contexts, the object returns the status code; in the string
55
context the full error message is returned.
57
When intercepting exceptions you need to check whether C<$@> is an
58
object (reference). If your application uses other exception objects
59
you additionally need to check whether this is a an C<APR::Error>
60
object. Therefore most of the time this is enough:
62
eval { $obj->mp_method() };
63
if ($@ && $ref $@ && $@ == $some_code)
64
warn "handled exception: $@";
67
But with other, non-mod_perl, exception objects you need to do:
69
eval { $obj->mp_method() };
70
if ($@ && $ref $@ eq 'APR::Error' && $@ == $some_code)
71
warn "handled exception: $@";
74
In theory you could even do:
76
eval { $obj->mp_method() };
77
if ($@ && $@ == $some_code)
78
warn "handled exception: $@";
81
but it's possible that the method will die with a plain string and not
82
an object, in which case C<$@ == $some_code> won't quite
83
work. Remember that mod_perl throws exception objects only when Apache
84
and APR fail, and in a few other special cases of its own (like
85
C<L<exit|docs::2.0::api::ModPerl::Util/C_exit_>>).
87
warn "handled exception: $@" if $@ && $ref $@;
89
For example you wrote a code that performs L<a socket
90
read|docs::2.0::api::APR::Socket/C_recv_>:
92
my $buff = $sock->recv(1024);
93
my $rlen = length $buff;
94
warn "read $rlen bytes\n";
96
and in certain cases it times out. The code will die and log the
97
reason for the failure, which is fine, but later on you decide that
98
you want to give the read another chance before dying. In which case
99
you rewrite the code to handle the exception like so:
101
use APR::Const -compile => qw(TIMEUP);
102
my $buff = eval { $sock->recv(1024) };
104
die $@ unless ref $@ && $@ == APR::TIMEUP;
107
my $rlen = length $buff;
108
warn "read $rlen bytes\n";
110
Notice that we handle non-object and non-C<APR::Error> exceptions as
111
well, by simply rethrowing them.
114
Finally, the class is called C<APR::Error> because it needs to be used
115
outside mod_perl as well, when called from
116
C<L<APR|docs::2.0::api::APR>> applications written in perl.
123
C<cluck> is an equivalent of C<Carp::cluck> that works with
124
C<APR::Error> exception objects.
128
C<confess> is an equivalent of C<Carp::confess> that works with
129
C<APR::Error> exception objects.
134
L<mod_perl 2.0 documentation|docs::2.0::index>.
141
mod_perl 2.0 and its core modules are copyrighted under
142
The Apache Software License, Version 1.1.
149
L<The mod_perl development team and numerous
150
contributors|about::contributors::people>.
added
removed
docs/api/APR/Error.pod
