1docs::api::APR::Error(3U)ser Contributed Perl Documentatidooncs::api::APR::Error(3)
2
3
4

NAME

6       APR::Error - Perl API for APR/Apache/mod_perl exceptions
7

Synopsis

9         eval { $obj->mp_method() };
10         if ($@ && $ref $@ eq 'APR::Error' && $@ == $some_code) {
11             # handle the exception
12         }
13         else {
14             die $@; # rethrow it
15         }
16

Description

18       "APR::Error" handles APR/Apache/mod_perl exceptions for you, while
19       leaving you in control.
20
21       Apache and APR API return a status code for almost all methods, so if
22       you didn't check the return code and handled any possible problems, you
23       may have silent failures which may cause all kind of obscure problems.
24       On the other hand checking the status code after each call is just too
25       much of a kludge and makes quick prototyping/development almost
26       impossible, not talking about the code readability. Having methods
27       return status codes, also complicates the API if you need to return
28       other values.
29
30       Therefore to keep things nice and make the API readable we decided to
31       not return status codes, but instead throw exceptions with "APR::Error"
32       objects for each method that fails. If you don't catch those
33       exceptions, everything works transparently - perl will intercept the
34       exception object and "die()" with a proper error message. So you get
35       all the errors logged without doing any work.
36
37       Now, in certain cases you don't want to just die, but instead the error
38       needs to be trapped and handled. For example if some IO operation times
39       out, may be it is OK to trap that and try again. If we were to die with
40       an error message, you would have had to match the error message, which
41       is ugly, inefficient and may not work at all if locale error strings
42       are involved. Therefore you need to be able to get the original status
43       code that Apache or APR has generated. And the exception objects give
44       you that if you want to. Moreover the objects contain additional
45       information, such as the function name (in case you were eval'ing
46       several commands in one block), file and line number where that
47       function was invoked from. More attributes could be added in the
48       future.
49
50       "APR::Error" uses Perl operator overloading, such that in boolean and
51       numerical contexts, the object returns the status code; in the string
52       context the full error message is returned.
53
54       When intercepting exceptions you need to check whether $@ is an object
55       (reference). If your application uses other exception objects you
56       additionally need to check whether this is a an "APR::Error" object.
57       Therefore most of the time this is enough:
58
59         eval { $obj->mp_method() };
60         if ($@ && $ref $@ && $@ == $some_code)
61             warn "handled exception: $@";
62         }
63
64       But with other, non-mod_perl, exception objects you need to do:
65
66         eval { $obj->mp_method() };
67         if ($@ && $ref $@ eq 'APR::Error' && $@ == $some_code)
68             warn "handled exception: $@";
69         }
70
71       In theory you could even do:
72
73         eval { $obj->mp_method() };
74         if ($@ && $@ == $some_code)
75             warn "handled exception: $@";
76         }
77
78       but it's possible that the method will die with a plain string and not
79       an object, in which case "$@ == $some_code" won't quite work. Remember
80       that mod_perl throws exception objects only when Apache and APR fail,
81       and in a few other special cases of its own (like "exit").
82
83         warn "handled exception: $@" if $@ && $ref $@;
84
85       There are two ways to figure out whether an error fits your case. In
86       most cases you just compare $@ with an the error constant. For example
87       if a socket has a timeout set and the data wasn't read within the
88       timeout limit a "APR::Const::TIMEUP")
89
90         use APR::Const -compile => qw(TIMEUP);
91         $sock->timeout_set(1_000_000); # 1 sec
92         my $buff;
93         eval { $sock->recv($buff, BUFF_LEN) };
94         if ($@ && ref $@ && $@ == APR::Const::TIMEUP) {
95
96         }
97
98       However there are situations, where on different Operating Systems a
99       different error code will be returned. In which case to simplify the
100       code you should use the special subroutines provided by the
101       "APR::Status" class. One such condition is socket "recv()" timeout,
102       which on Unix throws the "EAGAIN" error, but on other system it throws
103       a different error. In this case "APR::Status::is_EAGAIN" should be
104       used.
105
106       Let's look at a complete example. Here is a code that performs a socket
107       read:
108
109         my $rlen = $sock->recv(my $buff, 1024);
110         warn "read $rlen bytes\n";
111
112       and in certain cases it times out. The code will die and log the reason
113       for the failure, which is fine, but later on you may decide that you
114       want to have another attempt to read before dying and add some fine
115       grained sleep time between attempts, which can be achieved with
116       "select". Which gives us:
117
118         use APR::Status ();
119         # ....
120         my $tries = 0;
121         my $buffer;
122         RETRY: my $rlen = eval { $sock->recv($buffer, SIZE) };
123         if ($@)
124             die $@ unless ref $@ && APR::Status::is_EAGAIN($@);
125             if ($tries++ < 3) {
126                 # sleep 250msec
127                 select undef, undef, undef, 0.25;
128                 goto RETRY;
129             }
130             else {
131                 # do something else
132             }
133         }
134         warn "read $rlen bytes\n"
135
136       Notice that we handle non-object and non-"APR::Error" exceptions as
137       well, by simply re-throwing them.
138
139       Finally, the class is called "APR::Error" because it needs to be used
140       outside mod_perl as well, when called from "APR" applications written
141       in Perl.
142

API

144   "cluck"
145       "cluck" is an equivalent of "Carp::cluck" that works with "APR::Error"
146       exception objects.
147
148   "confess"
149       "confess" is an equivalent of "Carp::confess" that works with
150       "APR::Error" exception objects.
151
152   "strerror"
153       Convert APR error code to its string representation.
154
155         $error_str = APR::Error::strerror($rc);
156
157       ret: $rc ( "APR::Const status constant" )
158           The numerical value for the return (error) code
159
160       ret: $error_str ( string )
161           The string error message corresponding to the numerical value
162           inside $rc.  (Similar to the C function strerror(3))
163
164       since: 2.0.00
165
166       Example:
167
168       Try to retrieve the bucket brigade, and if the return value doesn't
169       indicate success or end of file (usually in protocol handlers) die, but
170       give the user the human-readable version of the error and not just the
171       code.
172
173         my $rc = $c->input_filters->get_brigade($bb_in,
174                                                 Apache2::Const::MODE_GETLINE);
175         if ($rc != APR::Const::SUCCESS && $rc != APR::Const::EOF) {
176             my $error = APR::Error::strerror($rc);
177             die "get_brigade error: $rc: $error\n";
178         }
179
180       It's probably a good idea not to omit the numerical value in the error
181       message, in case the error string is generated with non-English locale.
182

See Also

184       mod_perl 2.0 documentation.
185
187       mod_perl 2.0 and its core modules are copyrighted under The Apache
188       Software License, Version 2.0.
189

Authors

191       The mod_perl development team and numerous contributors.
192
193
194
195perl v5.12.0                      2007-11-12          docs::api::APR::Error(3)
Impressum