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

Comparing EV/README (file contents):
Revision 1.27 by root, Mon May 26 05:37:18 2008 UTC vs.
Revision 1.28 by root, Tue Jul 8 18:56:48 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.
… …
101 "EV::FLAG_FORKCHECK" which calls this function 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
104 $loop->loop_verify 111 $loop->loop_verify
105 Calls "ev_verify" to make internal consistency checks (for debugging 112 Calls "ev_verify" to make internal consistency checks (for debugging
106 libev) and abort the program if any data structures wree found to be 113 libev) and abort the program if any data structures were found to be
107 corrupted. 114 corrupted.
108 115
109 $loop = EV::default_loop [$flags] 116 $loop = EV::default_loop [$flags]
110 Return the default loop (which is a singleton object). Since this 117 Return the default loop (which is a singleton object). Since this
111 module already creates the default loop with default flags, 118 module already creates the default loop with default flags,
112 specifying flags here will not have any effect unless you destroy 119 specifying flags here will not have any effect unless you destroy
113 the default loop. 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.
114 122
115BASIC INTERFACE 123BASIC INTERFACE
116 $EV::DIED 124 $EV::DIED
117 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
118 callback throws an exception (with $@ containing the error). The 126 callback throws an exception (with $@ containing the error). The
… …
216WATCHER OBJECTS 224WATCHER OBJECTS
217 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
218 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,
219 you would create an EV::io watcher for that: 227 you would create an EV::io watcher for that:
220 228
221 my $watcher = EV::io *STDIN, EV::READ, sub { 229 my $watcher = EV::io *STDIN, EV::READ, sub {
222 my ($watcher, $revents) = @_; 230 my ($watcher, $revents) = @_;
223 warn "yeah, STDIN should now be readable without blocking!\n" 231 warn "yeah, STDIN should now be readable without blocking!\n"
224 }; 232 };
225 233
226 All watchers can be active (waiting for events) or inactive (paused). 234 All watchers can be active (waiting for events) or inactive (paused).
227 Only active watchers will have their callbacks invoked. All callbacks 235 Only active watchers will have their callbacks invoked. All callbacks
228 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
229 received events. 237 received events.
… …
331 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
332 the event loop from running just because of that watcher. 340 the event loop from running just because of that watcher.
333 341
334 my $udp_socket = ... 342 my $udp_socket = ...
335 my $udp_watcher = EV::io $udp_socket, EV::READ, sub { ... }; 343 my $udp_watcher = EV::io $udp_socket, EV::READ, sub { ... };
336 $1000udp_watcher->keepalive (0); 344 $udp_watcher->keepalive (0);
337 345
338 $loop = $w->loop 346 $loop = $w->loop
339 Return the loop that this watcher is attached to. 347 Return the loop that this watcher is attached to.
340 348
341WATCHER TYPES 349WATCHER TYPES
… …
767 _when_one_backend_> for more details. 775 _when_one_backend_> for more details.
768 776
769 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
770 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:
771 779
772 my $socket_loop; 780 my $socket_loop;
773 781
774 # check wether we use SELECT or POLL _and_ KQUEUE is supported 782 # check wether we use SELECT or POLL _and_ KQUEUE is supported
775 if ( 783 if (
776 (EV::backend & (EV::BACKEND_POLL | EV::BACKEND_SELECT)) 784 (EV::backend & (EV::BACKEND_POLL | EV::BACKEND_SELECT))
777 && (EV::supported_backends & EV::embeddable_backends & EV::BACKEND_KQUEUE) 785 && (EV::supported_backends & EV::embeddable_backends & EV::BACKEND_KQUEUE)
778 ) { 786 ) {
779 # use kqueue for sockets 787 # use kqueue for sockets
780 $socket_loop = new EV::Loop EV::BACKEND_KQUEUE | EV::FLAG_NOENV; 788 $socket_loop = new EV::Loop EV::BACKEND_KQUEUE | EV::FLAG_NOENV;
781 } 789 }
782 790
783 # use the default loop otherwise 791 # use the default loop otherwise
784 $socket_loop ||= EV::default_loop; 792 $socket_loop ||= EV::default_loop;
785 793
786 $w = EV::embed $otherloop, $callback 794 $w = EV::embed $otherloop, $callback
787 $w = EV::embed_ns $otherloop, $callback 795 $w = EV::embed_ns $otherloop, $callback
788 $w = $loop->embed ($otherloop, $callback) 796 $w = $loop->embed ($otherloop, $callback)
789 $w = $loop->embed_ns ($otherloop, $callback) 797 $w = $loop->embed_ns ($otherloop, $callback)
… …
854 loop), EV::Glib (embed Glib into EV), Coro::EV (efficient coroutines 862 loop), EV::Glib (embed Glib into EV), Coro::EV (efficient coroutines
855 with EV), Net::SNMP::EV (asynchronous SNMP), AnyEvent for event-loop 863 with EV), Net::SNMP::EV (asynchronous SNMP), AnyEvent for event-loop
856 agnostic and portable event driven programming. 864 agnostic and portable event driven programming.
857 865
858AUTHOR 866AUTHOR
859 Marc Lehmann <schmorp@schmorp.de> 867 Marc Lehmann <schmorp@schmorp.de>
860 http://home.schmorp.de/ 868 http://home.schmorp.de/
861 869

Diff Legend

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