1docs::api::APR::Error(3U)ser Contributed Perl Documentatidooncs::api::APR::Error(3)
2
6 APR::Error - Perl API for APR/Apache/mod_perl exceptions
7
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
18 "APR::Error" handles APR/Apache/mod_perl exceptions for you, while
19 leaving you in control.
20 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 impos‐
26 sible, not talking about the code readability. Having methods return
27 status codes, also complicates the API if you need to return other val‐
28 ues.
29 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 excep‐
33 tions, everything works transparently - perl will intercept the excep‐
34 tion object and "die()" with a proper error message. So you get all the
35 errors logged without doing any work.
36 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 infor‐
45 mation, such as the function name (in case you were eval'ing several
46 commands in one block), file and line number where that function was
47 invoked from. More attributes could be added in the future.
48 "APR::Error" uses Perl operator overloading, such that in boolean and
50 numerical contexts, the object returns the status code; in the string
51 context the full error message is returned.
52 When intercepting exceptions you need to check whether $@ is an object
54 (reference). If your application uses other exception objects you addi‐
55 tionally need to check whether this is a an "APR::Error" object. There‐
56 fore most of the time this is enough:
57 eval { $obj->mp_method() };
59 if ($@ && $ref $@ && $@ == $some_code)
60 warn "handled exception: $@";
61 }
62 But with other, non-mod_perl, exception objects you need to do:
64 eval { $obj->mp_method() };
66 if ($@ && $ref $@ eq 'APR::Error' && $@ == $some_code)
67 warn "handled exception: $@";
68 }
69 In theory you could even do:
71 eval { $obj->mp_method() };
73 if ($@ && $@ == $some_code)
74 warn "handled exception: $@";
75 }
76 but it's possible that the method will die with a plain string and not
78 an object, in which case "$@ == $some_code" won't quite work. Remember
79 that mod_perl throws exception objects only when Apache and APR fail,
80 and in a few other special cases of its own (like "exit").
81 warn "handled exception: $@" if $@ && $ref $@;
83 There are two ways to figure out whether an error fits your case. In
85 most cases you just compare $@ with an the error constant. For example
86 if a socket has a timeout set and the data wasn't read within the time‐
87 out limit a "APR::Const::TIMEUP")
88 use APR::Const -compile => qw(TIMEUP);
90 $sock->timeout_set(1_000_000); # 1 sec
91 my $buff;
92 eval { $sock->recv($buff, BUFF_LEN) };
93 if ($@ && ref $@ && $@ == APR::Const::TIMEUP) {
94 }
96 However there are situations, where on different Operating Systems a
98 different error code will be returned. In which case to simplify the
99 code you should use the special subroutines provided by the "APR::Sta‐
100 tus" class. One such condition is socket "recv()" timeout, which on
101 Unix throws the "EAGAIN" error, but on other system it throws a differ‐
102 ent error. In this case "APR::Status::is_EAGAIN" should be used.
103 Let's look at a complete example. Here is a code that performs a socket
105 read:
106 my $rlen = $sock->recv(my $buff, 1024);
108 warn "read $rlen bytes\n";
109 and in certain cases it times out. The code will die and log the reason
111 for the failure, which is fine, but later on you may decide that you
112 want to have another attempt to read before dying and add some fine
113 grained sleep time between attempts, which can be achieved with
114 "select". Which gives us:
115 use APR::Status ();
117 # ....
118 my $tries = 0;
119 my $buffer;
120 RETRY: my $rlen = eval { $sock->recv($buffer, SIZE) };
121 if ($@)
122 die $@ unless ref $@ && APR::Status::is_EAGAIN($@);
123 if ($tries++ < 3) {
124 # sleep 250msec
125 select undef, undef, undef, 0.25;
126 goto RETRY;
127 }
128 else {
129 # do something else
130 }
131 }
132 warn "read $rlen bytes\n"
133 Notice that we handle non-object and non-"APR::Error" exceptions as
135 well, by simply re-throwing them.
136 Finally, the class is called "APR::Error" because it needs to be used
138 outside mod_perl as well, when called from "APR" applications written
139 in Perl.
140
142 "cluck"
143 "cluck" is an equivalent of "Carp::cluck" that works with "APR::Error"
145 exception objects.
146 "confess"
148 "confess" is an equivalent of "Carp::confess" that works with
150 "APR::Error" exception objects.
151 "strerror"
153 Convert APR error code to its string representation.
155 $error_str = APR::Error::strerror($rc);
157 ret: $rc ( "APR::Const status constant" )
159 The numerical value for the return (error) code
160 ret: $error_str ( string )
162 The string error message corresponding to the numerical value
163 inside $rc. (Similar to the C function strerror(3))
164 since: 2.0.00
166 Example:
168 Try to retrieve the bucket brigade, and if the return value doesn't
170 indicate success or end of file (usually in protocol handlers) die, but
171 give the user the human-readable version of the error and not just the
172 code.
173 my $rc = $c->input_filters->get_brigade($bb_in,
175 Apache2::Const::MODE_GETLINE);
176 if ($rc != APR::Const::SUCCESS && $rc != APR::Const::EOF) {
177 my $error = APR::Error::strerror($rc);
178 die "get_brigade error: $rc: $error\n";
179 }
180 It's probably a good idea not to omit the numerical value in the error
182 message, in case the error string is generated with non-English locale.
183
185 mod_perl 2.0 documentation.
186
188 mod_perl 2.0 and its core modules are copyrighted under The Apache
189 Software License, Version 2.0.
190
192 The mod_perl development team and numerous contributors.
193perl v5.8.8 2006-11-19 docs::api::APR::Error(3)