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

Comparing EV/EV.pm (file contents):
Revision 1.87 by root, Tue Apr 15 04:41:57 2008 UTC vs.
Revision 1.98 by root, Sat May 31 23:17:50 2008 UTC

… …
2 2
3EV - perl interface to libev, a high performance full-featured event loop 3EV - perl interface to libev, a high performance full-featured event loop
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use EV; 7 use EV;
8
9 # TIMERS
10
11 my $w = EV::timer 2, 0, sub {
12 warn "is called after 2s";
13 };
14
15 my $w = EV::timer 2, 2, sub {
16 warn "is called roughly every 2s (repeat = 2)";
17 };
18
19 undef $w; # destroy event watcher again
20
21 my $w = EV::periodic 0, 60, 0, sub {
22 warn "is called every minute, on the minute, exactly";
23 };
24
25 # IO
26
27 my $w = EV::io *STDIN, EV::READ, sub {
28 my ($w, $revents) = @_; # all callbacks receive the watcher and event mask
29 warn "stdin is readable, you entered: ", <STDIN>;
30 };
31
32 # SIGNALS
33
34 my $w = EV::signal 'QUIT', sub {
35 warn "sigquit received\n";
36 };
37
38 # CHILD/PID STATUS CHANGES
8 39
9 # TIMERS 40 my $w = EV::child 666, 0, sub {
41 my ($w, $revents) = @_;
42 my $status = $w->rstatus;
43 };
10 44
11 my $w = EV::timer 2, 0, sub {
12 warn "is called after 2s";
13 };
14
15 my $w = EV::timer 2, 2, sub {
16 warn "is called roughly every 2s (repeat = 2)";
17 };
18
19 undef $w; # destroy event watcher again
20
21 my $w = EV::periodic 0, 60, 0, sub {
22 warn "is called every minute, on the minute, exactly";
23 };
24
25 # IO
26
27 my $w = EV::io *STDIN, EV::READ, sub {
28 my ($w, $revents) = @_; # all callbacks receive the watcher and event mask
29 warn "stdin is readable, you entered: ", <STDIN>;
30 };
31
32 # SIGNALS
33
34 my $w = EV::signal 'QUIT', sub {
35 warn "sigquit received\n";
36 };
37
38 # CHILD/PID STATUS CHANGES
39
40 my $w = EV::child 666, 0, sub {
41 my ($w, $revents) = @_;
42 my $status = $w->rstatus;
43 };
44
45 # STAT CHANGES 45 # STAT CHANGES
46 my $w = EV::stat "/etc/passwd", 10, sub { 46 my $w = EV::stat "/etc/passwd", 10, sub {
47 my ($w, $revents) = @_; 47 my ($w, $revents) = @_;
48 warn $w->path, " has changed somehow.\n"; 48 warn $w->path, " has changed somehow.\n";
49 }; 49 };
50 50
51 # MAINLOOP 51 # MAINLOOP
52 EV::loop; # loop until EV::unloop is called or all watchers stop 52 EV::loop; # loop until EV::unloop is called or all watchers stop
53 EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled 53 EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled
54 EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block 54 EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block
55 55
56=head1 DESCRIPTION 56=head1 DESCRIPTION
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 libev 60below is comprehensive, one might also consult the documentation of libev
61itself (L<http://cvs.schmorp.de/libev/ev.html>) for more subtle details on 61itself (L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>) for more
62watcher semantics or some discussion on the available backends, or how to 62subtle details on watcher semantics or some discussion on the available
63force a specific backend with C<LIBEV_FLAGS>, or just about in any case 63backends, or how to force a specific backend with C<LIBEV_FLAGS>, or just
64because it has much more detailed information. 64about in any case because it has much more detailed information.
65
66This module is very fast and scalable. It is actually so fast that you
67can use it through the L<AnyEvent> module, stay portable to other event
68loops (if you don't rely on any watcher types not available through it)
69and still be faster than with any other event loop currently supported in
70Perl.
65 71
66=cut 72=cut
67 73
68package EV; 74package EV;
69 75
70use strict; 76use strict;
71 77
72BEGIN { 78BEGIN {
73 our $VERSION = '3.2'; 79 our $VERSION = '3.42';
74 use XSLoader; 80 use XSLoader;
75 XSLoader::load "EV", $VERSION; 81 XSLoader::load "EV", $VERSION;
76} 82}
77 83
78@EV::IO::ISA = 84@EV::IO::ISA =
… …
124 130
125=item $loop->loop_fork 131=item $loop->loop_fork
126 132
127Must be called after a fork in the child, before entering or continuing 133Must be called after a fork in the child, before entering or continuing
128the event loop. An alternative is to use C<EV::FLAG_FORKCHECK> which calls 134the event loop. An alternative is to use C<EV::FLAG_FORKCHECK> which calls
129this fucntion automatically, at some performance loss (refer to the libev 135this function automatically, at some performance loss (refer to the libev
130documentation). 136documentation).
131 137
138=item $loop->loop_verify
139
140Calls C<ev_verify> to make internal consistency checks (for debugging
141libev) and abort the program if any data structures wree found to be
142corrupted.
143
132=item $loop = EV::default_loop [$flags] 144=item $loop = EV::default_loop [$flags]
133 145
134Return the default loop (which is a singleton object). 146Return the default loop (which is a singleton object). Since this module
147already creates the default loop with default flags, specifying flags here
148will not have any effect unless you destroy the default loop.
135 149
136=back 150=back
137 151
138 152
139=head1 BASIC INTERFACE 153=head1 BASIC INTERFACE
… …
269 283
270A watcher is an object that gets created to record your interest in some 284A watcher is an object that gets created to record your interest in some
271event. For instance, if you want to wait for STDIN to become readable, you 285event. For instance, if you want to wait for STDIN to become readable, you
272would create an EV::io watcher for that: 286would create an EV::io watcher for that:
273 287
274 my $watcher = EV::io *STDIN, EV::READ, sub { 288 my $watcher = EV::io *STDIN, EV::READ, sub {
275 my ($watcher, $revents) = @_; 289 my ($watcher, $revents) = @_;
276 warn "yeah, STDIN should now be readable without blocking!\n" 290 warn "yeah, STDIN should now be readable without blocking!\n"
277 }; 291 };
278 292
279All watchers can be active (waiting for events) or inactive (paused). Only 293All watchers can be active (waiting for events) or inactive (paused). Only
280active watchers will have their callbacks invoked. All callbacks will be 294active watchers will have their callbacks invoked. All callbacks will be
281called with at least two arguments: the watcher and a bitmask of received 295called with at least two arguments: the watcher and a bitmask of received
282events. 296events.
… …
395Example: Register an I/O watcher for some UDP socket but do not keep the 409Example: Register an I/O watcher for some UDP socket but do not keep the
396event loop from running just because of that watcher. 410event loop from running just because of that watcher.
397 411
398 my $udp_socket = ... 412 my $udp_socket = ...
399 my $udp_watcher = EV::io $udp_socket, EV::READ, sub { ... }; 413 my $udp_watcher = EV::io $udp_socket, EV::READ, sub { ... };
400 $1000udp_watcher->keepalive (0); 414 $udp_watcher->keepalive (0);
401 415
402=item $loop = $w->loop 416=item $loop = $w->loop
403 417
404Return the loop that this watcher is attached to. 418Return the loop that this watcher is attached to.
405 419
… …
562time the periodic watcher gets scheduled, the reschedule callback 576time the periodic watcher gets scheduled, the reschedule callback
563($reschedule_cb) will be called with the watcher as first, and the current 577($reschedule_cb) will be called with the watcher as first, and the current
564time as second argument. 578time as second argument.
565 579
566I<This callback MUST NOT stop or destroy this or any other periodic 580I<This callback MUST NOT stop or destroy this or any other periodic
567watcher, ever>. If you need to stop it, return 1e30 and stop it 581watcher, ever, and MUST NOT call any event loop functions or methods>. If
568afterwards. 582you need to stop it, return 1e30 and stop it afterwards. You may create
583and start a C<EV::prepare> watcher for this task.
569 584
570It must return the next time to trigger, based on the passed time value 585It must return the next time to trigger, based on the passed time value
571(that is, the lowest time value larger than to the second argument). It 586(that is, the lowest time value larger than or equal to to the second
572will usually be called just before the callback will be triggered, but 587argument). It will usually be called just before the callback will be
573might be called at other times, too. 588triggered, but might be called at other times, too.
574 589
575This can be used to create very complex timers, such as a timer that 590This can be used to create very complex timers, such as a timer that
576triggers on each midnight, local time (actually 24 hours after the last 591triggers on each midnight, local time (actually 24 hours after the last
577midnight, to keep the example simple. If you know a way to do it correctly 592midnight, to keep the example simple. If you know a way to do it correctly
578in about the same space (without requiring elaborate modules), drop me a 593in about the same space (without requiring elaborate modules), drop me a
… …
936for more details. 951for more details.
937 952
938In short, this watcher is most useful on BSD systems without working 953In short, this watcher is most useful on BSD systems without working
939kqueue to still be able to handle a large number of sockets: 954kqueue to still be able to handle a large number of sockets:
940 955
941 my $socket_loop; 956 my $socket_loop;
942 957
943 # check wether we use SELECT or POLL _and_ KQUEUE is supported 958 # check wether we use SELECT or POLL _and_ KQUEUE is supported
944 if ( 959 if (
945 (EV::backend & (EV::BACKEND_POLL | EV::BACKEND_SELECT)) 960 (EV::backend & (EV::BACKEND_POLL | EV::BACKEND_SELECT))
946 && (EV::supported_backends & EV::embeddable_backends & EV::BACKEND_KQUEUE) 961 && (EV::supported_backends & EV::embeddable_backends & EV::BACKEND_KQUEUE)
947 ) { 962 ) {
948 # use kqueue for sockets 963 # use kqueue for sockets
949 $socket_loop = new EV::Loop EV::BACKEND_KQUEUE | EV::FLAG_NOENV; 964 $socket_loop = new EV::Loop EV::BACKEND_KQUEUE | EV::FLAG_NOENV;
950 } 965 }
951 966
952 # use the default loop otherwise 967 # use the default loop otherwise
953 $socket_loop ||= EV::default_loop; 968 $socket_loop ||= EV::default_loop;
954 969
955=over 4 970=over 4
956 971
957=item $w = EV::embed $otherloop, $callback 972=item $w = EV::embed $otherloop, $callback
958 973
… …
1049 1064
1050=head1 SEE ALSO 1065=head1 SEE ALSO
1051 1066
1052L<EV::ADNS> (asynchronous DNS), L<Glib::EV> (makes Glib/Gtk2 use EV as 1067L<EV::ADNS> (asynchronous DNS), L<Glib::EV> (makes Glib/Gtk2 use EV as
1053event loop), L<EV::Glib> (embed Glib into EV), L<Coro::EV> (efficient 1068event loop), L<EV::Glib> (embed Glib into EV), L<Coro::EV> (efficient
1054coroutines with EV), L<Net::SNMP::EV> (asynchronous SNMP). 1069coroutines with EV), L<Net::SNMP::EV> (asynchronous SNMP), L<AnyEvent> for
1070event-loop agnostic and portable event driven programming.
1055 1071
1056=head1 AUTHOR 1072=head1 AUTHOR
1057 1073
1058 Marc Lehmann <schmorp@schmorp.de> 1074 Marc Lehmann <schmorp@schmorp.de>
1059 http://home.schmorp.de/ 1075 http://home.schmorp.de/
1060 1076
1061=cut 1077=cut
1062 1078

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines