1docs::api::APR::Socket(U3s)er Contributed Perl Documentatdioocns::api::APR::Socket(3)
2
6 APR::Socket - Perl API for APR sockets
7
9 use APR::Socket ();
10 ### set the socket to the blocking mode if it isn't already
12 ### and read in the loop and echo it back
13 use APR::Const -compile => qw(SO_NONBLOCK);
14 if ($sock->opt_get(APR::Const::SO_NONBLOCK)) {
15 $sock->opt_set(APR::Const::SO_NONBLOCK => 0);
16 }
17 # read from/write to the socket (w/o handling possible failures)
18 my $wanted = 1024;
19 while ($sock->recv(my $buff, $wanted)) {
20 $sock->send($buff);
21 }
22 ### get/set IO timeout and try to read some data
24 use APR::Const -compile => qw(TIMEUP);
25 # timeout is in usecs!
26 my $timeout = $sock->timeout_get();
27 if ($timeout < 10_000_000) {
28 $sock->timeout_set(20_000_000); # 20 secs
29 }
30 # now read, while handling timeouts
31 my $wanted = 1024;
32 my $buff;
33 my $rlen = eval { $sock->recv($buff, $wanted) };
34 if ($@ && ref $@ && $@ == APR::Const::TIMEUP) {
35 # timeout, do something, e.g.
36 warn "timed out, will try again later";
37 }
38 else {
39 warn "asked for $wanted bytes, read $rlen bytes\n";
40 # do something with the data
41 }
42 # non-blocking io poll
44 $sock->opt_set(APR::Const::SO_NONBLOCK => 1);
45 my $rc = $sock->poll($c->pool, 1_000_000, APR::Const::POLLIN);
46 if ($rc == APR::Const::SUCCESS) {
47 # read the data
48 }
49 else {
50 # handle the condition
51 }
52
54 "APR::Socket" provides the Perl interface to APR sockets.
55
57 "APR::Socket" provides the following methods:
58 "opt_get"
60 Query socket options for the specified socket
61 $val = $sock->opt_get($opt);
63 obj: $sock ( "APR::Socket object" )
65 the socket object to query
66 arg1: $opt ( "APR::Const constant" )
68 the socket option we would like to configure. Here are the
69 available socket options.
70 ret: $val ( integer )
72 the currently set value for the socket option you've queried for
73 excpt: "APR::Error"
75 since: 2.0.00
76 Examples can be found in the socket options constants section. For
78 example setting the IO to the blocking mode.
79 "opt_set"
81 Setup socket options for the specified socket
82 $sock->opt_set($opt, $val);
84 obj: $sock ( "APR::Socket object" object )
86 the socket object to set up.
87 arg1: $opt ( "APR::Const" constant )
89 the socket option we would like to configure. Here are the
90 available socket options.
91 arg2: $val ( integer )
93 value for the option. Refer to the socket options section to learn
94 about the expected values.
95 ret: no return value
97 excpt: "APR::Error"
98 since: 2.0.00
99 Examples can be found in the socket options constants section. For
101 example setting the IO to the blocking mode.
102 "poll"
104 Poll the socket for events:
105 $rc = $sock->poll($pool, $timeout, $events);
107 obj: $sock ( "APR::Socket object" )
109 The socket to poll
110 arg1: $pool ( "APR::Pool object" )
112 usually "$c->pool".
113 arg2: $timeout ( integer )
115 The amount of time to wait (in milliseconds) for the specified
116 events to occur.
117 arg3: $events ( "APR::Const :poll constants" )
119 The events for which to wait.
120 For example use "APR::Const::POLLIN" to wait for incoming data to
122 be available, "APR::Const::POLLOUT" to wait until it's possible to
123 write data to the socket and "APR::Const::POLLPRI" to wait for
124 priority data to become available.
125 ret: $rc ( "APR::Const constant" )
127 If "APR::Const::SUCCESS" is received than the polling was
128 successful. If not -- the error code is returned, which can be
129 converted to the error string with help of "APR::Error::strerror".
130 since: 2.0.00
132 For example poll a non-blocking socket up to 1 second when reading data
134 from the client:
135 use APR::Socket ();
137 use APR::Connection ();
138 use APR::Error ();
139 use APR::Const -compile => qw(SO_NONBLOCK POLLIN SUCCESS TIMEUP);
141 $sock->opt_set(APR::Const::SO_NONBLOCK => 1);
143 my $rc = $sock->poll($c->pool, 1_000_000, APR::Const::POLLIN);
145 if ($rc == APR::Const::SUCCESS) {
146 # Data is waiting on the socket to be read.
147 # $sock->recv(my $buf, BUFF_LEN)
148 }
149 elsif ($rc == APR::Const::TIMEUP) {
150 # One second elapsed and still there is no data waiting to be
151 # read. for example could try again.
152 }
153 else {
154 die "poll error: " . APR::Error::strerror($rc);
155 }
156 "recv"
158 Read incoming data from the socket
159 $len = $sock->recv($buffer, $wanted);
161 obj: $sock ( "APR::SockAddr object" object )
163 The socket to read from
164 arg1: $buffer ( SCALAR )
166 The buffer to fill. All previous data will be lost.
167 arg2: $wanted ( int )
169 How many bytes to attempt to read.
170 ret: $len ( number )
172 How many bytes were actually read.
173 $buffer gets populated with the string that is read. It will
175 contain an empty string if there was nothing to read.
176 excpt: "APR::Error"
178 If you get the '(11) Resource temporarily unavailable' error
179 (exception "APR::Const::EAGAIN") (or another equivalent, which
180 might be different on non-POSIX systems), then you didn't ensure
181 that the socket is in a blocking IO mode before using it. Note that
182 you should use "APR::Status::is_EAGAIN" to perform this check
183 (since different error codes may be returned for the same event on
184 different OSes). For example if the socket is set to the non-
185 blocking mode and there is no data right away, you may get this
186 exception thrown. So here is how to check for it and retry a few
187 times after short delays:
188 use APR::Status ();
190 $sock->opt_set(APR::Const::SO_NONBLOCK, 1);
191 # ....
192 my $tries = 0;
193 my $buffer;
194 RETRY: my $rlen = eval { $socket->recv($buffer, SIZE) };
195 if ($@)
196 die $@ unless ref $@ && APR::Status::is_EAGAIN($@);
197 if ($tries++ < 3) {
198 # sleep 250msec
199 select undef, undef, undef, 0.25;
200 goto RETRY;
201 }
202 else {
203 # do something else
204 }
205 }
206 warn "read $rlen bytes\n"
207 If timeout was set via "timeout_set|/C_timeout_set_", you may need
209 to catch the "APR::Const::TIMEUP" exception. For example:
210 use APR::Const -compile => qw(TIMEUP);
212 $sock->timeout_set(1_000_000); # 1 sec
213 my $buffer;
214 eval { $sock->recv($buffer, $wanted) };
215 if ($@ && $@ == APR::Const::TIMEUP) {
216 # timeout, do something, e.g.
217 }
218 If not handled -- you may get the error '70007: The timeout
220 specified has expired'.
221 Another error condition that may occur is the '(104) Connection
223 reset by peer' error, which is up to your application logic to
224 decide whether it's an error or not. This error usually happens
225 when the client aborts the connection.
226 use APR::Const -compile => qw(ECONNABORTED);
228 my $buffer;
229 eval { $sock->recv($buffer, $wanted) };
230 if ($@ == APR::Const::ECONNABORTED) {
231 # ignore it or deal with it
232 }
233 since: 2.0.00
235 Here is the quick prototype example, which doesn't handle any errors
237 (mod_perl will do that for you):
238 use APR::Socket ();
240 # set the socket to the blocking mode if it isn't already
242 use APR::Const -compile => qw(SO_NONBLOCK);
243 if ($sock->opt_get(APR::Const::SO_NONBLOCK)) {
244 $sock->opt_set(APR::Const::SO_NONBLOCK => 0);
245 }
246 # read from/write to the socket (w/o handling possible failures)
247 my $wanted = 1024;
248 while ($sock->recv(my $buffer, $wanted)) {
249 $sock->send($buffer);
250 }
251 If you want to handle errors by yourself, the loop may look like:
253 use APR::Const -compile => qw(ECONNABORTED);
255 # ...
256 while (1) {
257 my $buf;
258 my $len = eval { $sock->recv($buf, $wanted) };
259 if ($@) {
260 # handle the error, e.g. to ignore aborted connections but
261 # rethrow any other errors:
262 if ($@ == APR::Const::ECONNABORTED) {
263 # ignore
264 last;
265 }
266 else {
267 die $@; # retrow
268 }
269 }
270 if ($len) {
272 $sock->send($buffer);
273 }
274 else {
275 last;
276 }
277 }
278 "send"
280 Write data to the socket
281 $wlen = $sock->send($buf, $opt_len);
283 obj: $sock ( "APR::Socket object" )
285 The socket to write to
286 arg1: $buf ( scalar )
288 The data to send
289 opt arg2: $opt_len ( int )
291 There is no need to pass this argument, unless you want to send
292 less data than contained in $buf.
293 ret: $wlen ( integer )
295 How many bytes were sent
296 since: 2.0.00
298 For examples see the "recv" item.
300 "timeout_get"
302 Get socket timeout settings
303 $usecs = $sock->timeout_get();
305 obj: $sock ( "APR::Socket object" )
307 The socket to set up.
308 ret: $usecs ( number)
310 Currently set timeout in microseconds (and also the blocking IO
311 behavior). See ("APR::timeout_set") for possible values and their
312 meaning.
313 excpt: "APR::Error"
315 since: 2.0.00
316 "timeout_set"
318 Setup socket timeout.
319 $sock->timeout_set($usecs);
321 obj: $sock ( "APR::Socket object" )
323 The socket to set up.
324 arg1: $usecs ( number )
326 Value for the timeout in microseconds and also the blocking IO
327 behavior.
328 The possible values are:
330 t > 0
332 "send()" and "recv()" throw ("APR::Const::TIMEUP" exception) if
333 specified time elapses with no data sent or received.
334 Notice that the positive value is in micro seconds. So if you
336 want to set the timeout for 5 seconds, the value should be:
337 5_000_000.
338 This mode sets the socket into a non-blocking IO mode.
340 t == 0
342 "send()" and "recv()" calls never block.
343 t < 0
345 "send()" and "recv()" calls block.
346 Usually just -1 is used for this case, but any negative value
348 will do.
349 This mode sets the socket into a blocking IO mode.
351 ret: no return value
353 excpt: "APR::Error"
354 since: 2.0.00
355
357 "APR::Socket" also provides auto-generated Perl interface for a few
358 other methods which aren't tested at the moment and therefore their API
359 is a subject to change. These methods will be finalized later as a need
360 arises. If you want to rely on any of the following methods please
361 contact the the mod_perl development mailing list so we can help each
362 other take the steps necessary to shift the method to an officially
363 supported API.
364 "bind"
366 META: Autogenerated - needs to be reviewed/completed
367 Bind the socket to its associated port
369 $ret = $sock->bind($sa);
371 obj: $sock ( "APR::Socket object" )
373 The socket to bind
374 arg1: $sa ( "APR::SockAddr object" )
376 The socket address to bind to
377 ret: $ret ( integer )
379 since: subject to change
380 This may be where we will find out if there is any other process using
382 the selected port.
383 "close"
385 META: Autogenerated - needs to be reviewed/completed
386 Close a socket.
388 $ret = $sock->close();
390 obj: $sock ( "APR::Socket object" )
392 The socket to close
393 ret: $ret ( integer )
395 since: subject to change
396 "connect"
398 META: Autogenerated - needs to be reviewed/completed
399 Issue a connection request to a socket either on the same machine or a
401 different one.
402 $ret = $sock->connect($sa);
404 obj: $sock ( "APR::Socket object" )
406 The socket we wish to use for our side of the connection
407 arg1: $sa ( "APR::SockAddr object" )
409 The address of the machine we wish to connect to. If NULL, APR
410 assumes that the sockaddr_in in the apr_socket is completely filled
411 out.
412 ret: $ret ( integer )
414 since: subject to change
415 "listen"
417 META: Autogenerated - needs to be reviewed/completed
418 Listen to a bound socket for connections.
420 $ret = $sock->listen($backlog);
422 obj: $sock ( "APR::Socket object" )
424 The socket to listen on
425 arg1: $backlog ( integer )
427 The number of outstanding connections allowed in the sockets listen
428 queue. If this value is less than zero, the listen queue size is
429 set to zero.
430 ret: $ret ( integer )
432 since: subject to change
433 "recvfrom"
435 META: Autogenerated - needs to be reviewed/completed
436 $ret = $from->recvfrom($sock, $flags, $buf, $len);
438 obj: $from ( "APR::SockAddr object" )
440 The apr_sockaddr_t to fill in the recipient info
441 arg1: $sock ( "APR::SockAddr object" )
443 The socket to use
444 arg2: $flags ( integer )
446 The flags to use
447 arg3: $buf ( integer )
449 The buffer to use
450 arg4: $len ( string )
452 The length of the available buffer
453 ret: $ret ( integer )
455 since: subject to change
456 "sendto"
458 META: Autogenerated - needs to be reviewed/completed
459 $ret = $sock->sendto($where, $flags, $buf, $len);
461 obj: $sock ( "APR::Socket object" )
463 The socket to send from
464 arg1: $where ( "APR::Socket object" )
466 The apr_sockaddr_t describing where to send the data
467 arg2: $flags ( integer )
469 The flags to use
470 arg3: $buf ( scalar )
472 The data to send
473 arg4: $len ( string )
475 The length of the data to send
476 ret: $ret ( integer )
478 since: subject to change
479
481 mod_perl 2.0 documentation.
482
484 mod_perl 2.0 and its core modules are copyrighted under The Apache
485 Software License, Version 2.0.
486
488 The mod_perl development team and numerous contributors.
489perl v5.10.1 2008-04-17 docs::api::APR::Socket(3)