ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/EV/EV.pm
(Generate patch)

Comparing EV/EV.pm (file contents):
Revision 1.104 by root, Thu Oct 2 12:26:25 2008 UTC vs.
Revision 1.109 by root, Wed Nov 19 10:33:32 2008 UTC

57 57
58This module provides an interface to libev 58This module provides an interface to libev
59(L<http://software.schmorp.de/pkg/libev.html>). While the documentation 59(L<http://software.schmorp.de/pkg/libev.html>). While the documentation
60below is comprehensive, one might also consult the documentation of 60below is comprehensive, one might also consult the documentation of
61libev itself (L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod> or 61libev itself (L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod> or
62F<perldoc EV::c_doc>) for more subtle details on watcher semantics or some 62F<perldoc EV::libev>) for more subtle details on watcher semantics or some
63discussion on the available backends, or how to force a specific backend 63discussion on the available backends, or how to force a specific backend
64with C<LIBEV_FLAGS>, or just about in any case because it has much more 64with C<LIBEV_FLAGS>, or just about in any case because it has much more
65detailed information. 65detailed information.
66 66
67This module is very fast and scalable. It is actually so fast that you 67This module is very fast and scalable. It is actually so fast that you
68can use it through the L<AnyEvent> module, stay portable to other event 68can use it through the L<AnyEvent> module, stay portable to other event
69loops (if you don't rely on any watcher types not available through it) 69loops (if you don't rely on any watcher types not available through it)
70and still be faster than with any other event loop currently supported in 70and still be faster than with any other event loop currently supported in
71Perl. 71Perl.
72 72
73=head2 MODULE EXPORTS
74
75This module does not export any symbols.
76
73=cut 77=cut
74 78
75package EV; 79package EV;
76 80
77no warnings; 81no warnings;
78use strict; 82use strict;
79 83
80BEGIN { 84BEGIN {
81 our $VERSION = '3.44'; 85 our $VERSION = '3.49';
82 use XSLoader; 86 use XSLoader;
83 XSLoader::load "EV", $VERSION; 87 XSLoader::load "EV", $VERSION;
84} 88}
85 89
86@EV::IO::ISA = 90@EV::IO::ISA =
113default loop as this is fastest (perl-wise), best supported by other 117default loop as this is fastest (perl-wise), best supported by other
114modules (e.g. AnyEvent or Coro) and most portable event loop. 118modules (e.g. AnyEvent or Coro) and most portable event loop.
115 119
116For specific programs you can create additional event loops dynamically. 120For specific programs you can create additional event loops dynamically.
117 121
118If you want to take avdantage of kqueue (which often works properly for 122If you want to take advantage of kqueue (which often works properly for
119sockets only) even though the default loop doesn't enable it, you can 123sockets only) even though the default loop doesn't enable it, you can
120I<embed> a kqueue loop into the default loop: running the default loop 124I<embed> a kqueue loop into the default loop: running the default loop
121will then also service the kqueue loop to some extent. See the example in 125will then also service the kqueue loop to some extent. See the example in
122the section about embed watchers for an example on how to achieve that. 126the section about embed watchers for an example on how to achieve that.
123 127
126=item $loop = new EV::loop [$flags] 130=item $loop = new EV::loop [$flags]
127 131
128Create a new event loop as per the specified flags. Please refer to 132Create a new event loop as per the specified flags. Please refer to
129the C<ev_loop_new ()> function description in the libev documentation 133the C<ev_loop_new ()> function description in the libev documentation
130(L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#GLOBAL_FUNCTIONS>, 134(L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#GLOBAL_FUNCTIONS>,
131or locally-installed as F<EV::c_doc> manpage) for more info. 135or locally-installed as F<EV::libev> manpage) for more info.
132 136
133The loop will automatically be destroyed when it is no longer referenced 137The loop will automatically be destroyed when it is no longer referenced
134by any watcher and the loop object goes out of scope. 138by any watcher and the loop object goes out of scope.
135 139
136If you are not embedding the loop, then Using C<EV::FLAG_FORKCHECK> 140If you are not embedding the loop, then Using C<EV::FLAG_FORKCHECK>
195=item $time = EV::now 199=item $time = EV::now
196 200
197=item $time = $loop->now 201=item $time = $loop->now
198 202
199Returns the time the last event loop iteration has been started. This 203Returns the time the last event loop iteration has been started. This
200is the time that (relative) timers are based on, and refering to it is 204is the time that (relative) timers are based on, and referring to it is
201usually faster then calling EV::time. 205usually faster then calling EV::time.
202 206
203=item $backend = EV::backend 207=item $backend = EV::backend
204 208
205=item $backend = $loop->backend 209=item $backend = $loop->backend
206 210
207Returns an integer describing the backend used by libev (EV::METHOD_SELECT 211Returns an integer describing the backend used by libev (EV::BACKEND_SELECT
208or EV::METHOD_EPOLL). 212or EV::BACKEND_EPOLL).
209 213
210=item EV::loop [$flags] 214=item EV::loop [$flags]
211 215
212=item $loop->loop ([$flags]) 216=item $loop->loop ([$flags])
213 217
233=item $count = EV::loop_count 237=item $count = EV::loop_count
234 238
235=item $count = $loop->loop_count 239=item $count = $loop->loop_count
236 240
237Return the number of times the event loop has polled for new 241Return the number of times the event loop has polled for new
238events. Sometiems useful as a generation counter. 242events. Sometimes useful as a generation counter.
239 243
240=item EV::once $fh_or_undef, $events, $timeout, $cb->($revents) 244=item EV::once $fh_or_undef, $events, $timeout, $cb->($revents)
241 245
242=item $loop->once ($fh_or_undef, $events, $timeout, $cb->($revents)) 246=item $loop->once ($fh_or_undef, $events, $timeout, $cb->($revents))
243 247
284=item $loop->set_timeout_collect_interval ($time) 288=item $loop->set_timeout_collect_interval ($time)
285 289
286These advanced functions set the minimum block interval when polling for I/O events and the minimum 290These advanced functions set the minimum block interval when polling for I/O events and the minimum
287wait interval for timer events. See the libev documentation at 291wait interval for timer events. See the libev documentation at
288L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#FUNCTIONS_CONTROLLING_THE_EVENT_LOOP> 292L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#FUNCTIONS_CONTROLLING_THE_EVENT_LOOP>
289(locally installed as F<EV::c_doc>) for a more detailed discussion. 293(locally installed as F<EV::libev>) for a more detailed discussion.
290 294
291=back 295=back
292 296
293 297
294=head1 WATCHER OBJECTS 298=head1 WATCHER OBJECTS
307called with at least two arguments: the watcher and a bitmask of received 311called with at least two arguments: the watcher and a bitmask of received
308events. 312events.
309 313
310Each watcher type has its associated bit in revents, so you can use the 314Each watcher type has its associated bit in revents, so you can use the
311same callback for multiple watchers. The event mask is named after the 315same callback for multiple watchers. The event mask is named after the
312type, i..e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE, 316type, i.e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE,
313EV::periodic sets EV::PERIODIC and so on, with the exception of I/O events 317EV::periodic sets EV::PERIODIC and so on, with the exception of I/O events
314(which can set both EV::READ and EV::WRITE bits), and EV::timer (which 318(which can set both EV::READ and EV::WRITE bits), and EV::timer (which
315uses EV::TIMEOUT). 319uses EV::TIMEOUT).
316 320
317In the rare case where one wants to create a watcher but not start it at 321In the rare case where one wants to create a watcher but not start it at
413because you happen to have this long-running UDP port watcher. 417because you happen to have this long-running UDP port watcher.
414 418
415In this case you can clear the keepalive status, which means that even 419In this case you can clear the keepalive status, which means that even
416though your watcher is active, it won't keep C<EV::loop> from returning. 420though your watcher is active, it won't keep C<EV::loop> from returning.
417 421
418The initial value for keepalive is true (enabled), and you cna change it 422The initial value for keepalive is true (enabled), and you can change it
419any time. 423any time.
420 424
421Example: Register an I/O watcher for some UDP socket but do not keep the 425Example: Register an I/O watcher for some UDP socket but do not keep the
422event loop from running just because of that watcher. 426event loop from running just because of that watcher.
423 427
917 # make the dispatcher handle any new stuff 921 # make the dispatcher handle any new stuff
918 ... not shown 922 ... not shown
919 }; 923 };
920 924
921The callbacks of the created watchers will not be called as the watchers 925The callbacks of the created watchers will not be called as the watchers
922are destroyed before this cna happen (remember EV::check gets called 926are destroyed before this can happen (remember EV::check gets called
923first). 927first).
924 928
925The C<check_ns> variant doesn't start (activate) the newly created watcher. 929The C<check_ns> variant doesn't start (activate) the newly created watcher.
926 930
927=back 931=back
958loop, other types of watchers might be handled in a delayed or incorrect 962loop, other types of watchers might be handled in a delayed or incorrect
959fashion and must not be used). 963fashion and must not be used).
960 964
961See the libev documentation at 965See the libev documentation at
962L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#code_ev_embed_code_when_one_backend_> 966L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#code_ev_embed_code_when_one_backend_>
963(locally installed as F<EV::c_doc>) for more details. 967(locally installed as F<EV::libev>) for more details.
964 968
965In short, this watcher is most useful on BSD systems without working 969In short, this watcher is most useful on BSD systems without working
966kqueue to still be able to handle a large number of sockets: 970kqueue to still be able to handle a large number of sockets:
967 971
968 my $socket_loop; 972 my $socket_loop;

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines