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

Comparing EV/README (file contents):
Revision 1.26 by root, Wed May 21 23:40:08 2008 UTC vs.
Revision 1.29 by root, Sat Jul 12 22:19:22 2008 UTC

1NAME 1NAME
2 EV - perl interface to libev, a high performance full-featured event 2 EV - perl interface to libev, a high performance full-featured event
3 loop 3 loop
4 4
5SYNOPSIS 5SYNOPSIS
6 use EV; 6 use EV;
7
8 # TIMERS
9
10 my $w = EV::timer 2, 0, sub {
11 warn "is called after 2s";
12 };
13
14 my $w = EV::timer 2, 2, sub {
15 warn "is called roughly every 2s (repeat = 2)";
16 };
17
18 undef $w; # destroy event watcher again
19
20 my $w = EV::periodic 0, 60, 0, sub {
21 warn "is called every minute, on the minute, exactly";
22 };
23
24 # IO
25
26 my $w = EV::io *STDIN, EV::READ, sub {
27 my ($w, $revents) = @_; # all callbacks receive the watcher and event mask
28 warn "stdin is readable, you entered: ", <STDIN>;
29 };
30
31 # SIGNALS
32
33 my $w = EV::signal 'QUIT', sub {
34 warn "sigquit received\n";
35 };
36
37 # CHILD/PID STATUS CHANGES
7 38
8 # TIMERS 39 my $w = EV::child 666, 0, sub {
40 my ($w, $revents) = @_;
41 my $status = $w->rstatus;
42 };
9 43
10 my $w = EV::timer 2, 0, sub {
11 warn "is called after 2s";
12 };
13
14 my $w = EV::timer 2, 2, sub {
15 warn "is called roughly every 2s (repeat = 2)";
16 };
17
18 undef $w; # destroy event watcher again
19
20 my $w = EV::periodic 0, 60, 0, sub {
21 warn "is called every minute, on the minute, exactly";
22 };
23
24 # IO
25
26 my $w = EV::io *STDIN, EV::READ, sub {
27 my ($w, $revents) = @_; # all callbacks receive the watcher and event mask
28 warn "stdin is readable, you entered: ", <STDIN>;
29 };
30
31 # SIGNALS
32
33 my $w = EV::signal 'QUIT', sub {
34 warn "sigquit received\n";
35 };
36
37 # CHILD/PID STATUS CHANGES
38
39 my $w = EV::child 666, 0, sub {
40 my ($w, $revents) = @_;
41 my $status = $w->rstatus;
42 };
43
44 # STAT CHANGES 44 # STAT CHANGES
45 my $w = EV::stat "/etc/passwd", 10, sub { 45 my $w = EV::stat "/etc/passwd", 10, sub {
46 my ($w, $revents) = @_; 46 my ($w, $revents) = @_;
47 warn $w->path, " has changed somehow.\n"; 47 warn $w->path, " has changed somehow.\n";
48 }; 48 };
49 49
50 # MAINLOOP 50 # MAINLOOP
51 EV::loop; # loop until EV::unloop is called or all watchers stop 51 EV::loop; # loop until EV::unloop is called or all watchers stop
52 EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled 52 EV::loop EV::LOOP_ONESHOT; # block until at least one event could be handled
53 EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block 53 EV::loop EV::LOOP_NONBLOCK; # try to handle same events, but do not block
54 54
55DESCRIPTION 55DESCRIPTION
56 This module provides an interface to libev 56 This module provides an interface to libev
57 (<http://software.schmorp.de/pkg/libev.html>). While the documentation 57 (<http://software.schmorp.de/pkg/libev.html>). While the documentation
58 below is comprehensive, one might also consult the documentation of 58 below is comprehensive, one might also consult the documentation of
… …
81 default loop as this is fastest (perl-wise), best supported by other 81 default loop as this is fastest (perl-wise), best supported by other
82 modules (e.g. AnyEvent or Coro) and most portable event loop. 82 modules (e.g. AnyEvent or Coro) and most portable event loop.
83 83
84 For specific programs you can create additional event loops dynamically. 84 For specific programs you can create additional event loops dynamically.
85 85
86 If you want to take avdantage of kqueue (which often works properly for
87 sockets only) even though the default loop doesn't enable it, you can
88 *embed* a kqueue loop into the default loop: running the default loop
89 will then also service the kqueue loop to some extent. See the example
90 in the section about embed watchers for an example on how to achieve
91 that.
92
86 $loop = new EV::loop [$flags] 93 $loop = new EV::loop [$flags]
87 Create a new event loop as per the specified flags. Please refer to 94 Create a new event loop as per the specified flags. Please refer to
88 the "ev_loop_new ()" function description in the libev documentation 95 the "ev_loop_new ()" function description in the libev documentation
89 (<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#GLOBAL_FUNCTI 96 (<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#GLOBAL_FUNCTI
90 ONS>) for more info. 97 ONS>) for more info.
… …
96 loop is protected by this module. 103 loop is protected by this module.
97 104
98 $loop->loop_fork 105 $loop->loop_fork
99 Must be called after a fork in the child, before entering or 106 Must be called after a fork in the child, before entering or
100 continuing the event loop. An alternative is to use 107 continuing the event loop. An alternative is to use
101 "EV::FLAG_FORKCHECK" which calls this fucntion automatically, at 108 "EV::FLAG_FORKCHECK" which calls this function automatically, at
102 some performance loss (refer to the libev documentation). 109 some performance loss (refer to the libev documentation).
103 110
111 $loop->loop_verify
112 Calls "ev_verify" to make internal consistency checks (for debugging
113 libev) and abort the program if any data structures were found to be
114 corrupted.
115
104 $loop = EV::default_loop [$flags] 116 $loop = EV::default_loop [$flags]
105 Return the default loop (which is a singleton object). 117 Return the default loop (which is a singleton object). Since this
118 module already creates the default loop with default flags,
119 specifying flags here will not have any effect unless you destroy
120 the default loop first, which isn't supported. So in short: don't do
121 it, and if you break it, you get to keep the pieces.
106 122
107BASIC INTERFACE 123BASIC INTERFACE
108 $EV::DIED 124 $EV::DIED
109 Must contain a reference to a function that is called when a 125 Must contain a reference to a function that is called when a
110 callback throws an exception (with $@ containing the error). The 126 callback throws an exception (with $@ containing the error). The
… …
208WATCHER OBJECTS 224WATCHER OBJECTS
209 A watcher is an object that gets created to record your interest in some 225 A watcher is an object that gets created to record your interest in some
210 event. For instance, if you want to wait for STDIN to become readable, 226 event. For instance, if you want to wait for STDIN to become readable,
211 you would create an EV::io watcher for that: 227 you would create an EV::io watcher for that:
212 228
213 my $watcher = EV::io *STDIN, EV::READ, sub { 229 my $watcher = EV::io *STDIN, EV::READ, sub {
214 my ($watcher, $revents) = @_; 230 my ($watcher, $revents) = @_;
215 warn "yeah, STDIN should now be readable without blocking!\n" 231 warn "yeah, STDIN should now be readable without blocking!\n"
216 }; 232 };
217 233
218 All watchers can be active (waiting for events) or inactive (paused). 234 All watchers can be active (waiting for events) or inactive (paused).
219 Only active watchers will have their callbacks invoked. All callbacks 235 Only active watchers will have their callbacks invoked. All callbacks
220 will be called with at least two arguments: the watcher and a bitmask of 236 will be called with at least two arguments: the watcher and a bitmask of
221 received events. 237 received events.
… …
323 Example: Register an I/O watcher for some UDP socket but do not keep 339 Example: Register an I/O watcher for some UDP socket but do not keep
324 the event loop from running just because of that watcher. 340 the event loop from running just because of that watcher.
325 341
326 my $udp_socket = ... 342 my $udp_socket = ...
327 my $udp_watcher = EV::io $udp_socket, EV::READ, sub { ... }; 343 my $udp_watcher = EV::io $udp_socket, EV::READ, sub { ... };
328 $1000udp_watcher->keepalive (0); 344 $udp_watcher->keepalive (0);
329 345
330 $loop = $w->loop 346 $loop = $w->loop
331 Return the loop that this watcher is attached to. 347 Return the loop that this watcher is attached to.
332 348
333WATCHER TYPES 349WATCHER TYPES
… …
759 _when_one_backend_> for more details. 775 _when_one_backend_> for more details.
760 776
761 In short, this watcher is most useful on BSD systems without working 777 In short, this watcher is most useful on BSD systems without working
762 kqueue to still be able to handle a large number of sockets: 778 kqueue to still be able to handle a large number of sockets:
763 779
764 my $socket_loop; 780 my $socket_loop;
765 781
766 # check wether we use SELECT or POLL _and_ KQUEUE is supported 782 # check wether we use SELECT or POLL _and_ KQUEUE is supported
767 if ( 783 if (
768 (EV::backend & (EV::BACKEND_POLL | EV::BACKEND_SELECT)) 784 (EV::backend & (EV::BACKEND_POLL | EV::BACKEND_SELECT))
769 && (EV::supported_backends & EV::embeddable_backends & EV::BACKEND_KQUEUE) 785 && (EV::supported_backends & EV::embeddable_backends & EV::BACKEND_KQUEUE)
770 ) { 786 ) {
771 # use kqueue for sockets 787 # use kqueue for sockets
772 $socket_loop = new EV::Loop EV::BACKEND_KQUEUE | EV::FLAG_NOENV; 788 $socket_loop = new EV::Loop EV::BACKEND_KQUEUE | EV::FLAG_NOENV;
773 } 789 }
774 790
775 # use the default loop otherwise 791 # use the default loop otherwise
776 $socket_loop ||= EV::default_loop; 792 $socket_loop ||= EV::default_loop;
777 793
778 $w = EV::embed $otherloop, $callback 794 $w = EV::embed $otherloop[, $callback]
779 $w = EV::embed_ns $otherloop, $callback 795 $w = EV::embed_ns $otherloop[, $callback]
780 $w = $loop->embed ($otherloop, $callback) 796 $w = $loop->embed ($otherloop[, $callback])
781 $w = $loop->embed_ns ($otherloop, $callback) 797 $w = $loop->embed_ns ($otherloop[, $callback])
782 Call the callback when the embedded event loop ($otherloop) has any 798 Call the callback when the embedded event loop ($otherloop) has any
783 I/O activity. The $callback should alwas be specified as "undef" in 799 I/O activity. The $callback is optional: if it is missing, then the
784 this version of EV, which means the embedded event loop will be 800 embedded event loop will be managed automatically (which is
785 managed automatically. 801 recommended), otherwise you have to invoke "sweep" yourself.
786 802
787 The "embed_ns" variant doesn't start (activate) the newly created 803 The "embed_ns" variant doesn't start (activate) the newly created
788 watcher. 804 watcher.
789 805
790 ASYNC WATCHERS - how to wake up another event loop 806 ASYNC WATCHERS - how to wake up another event loop
… …
846 loop), EV::Glib (embed Glib into EV), Coro::EV (efficient coroutines 862 loop), EV::Glib (embed Glib into EV), Coro::EV (efficient coroutines
847 with EV), Net::SNMP::EV (asynchronous SNMP), AnyEvent for event-loop 863 with EV), Net::SNMP::EV (asynchronous SNMP), AnyEvent for event-loop
848 agnostic and portable event driven programming. 864 agnostic and portable event driven programming.
849 865
850AUTHOR 866AUTHOR
851 Marc Lehmann <schmorp@schmorp.de> 867 Marc Lehmann <schmorp@schmorp.de>
852 http://home.schmorp.de/ 868 http://home.schmorp.de/
853 869

Diff Legend

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