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

Comparing EV/README (file contents):
Revision 1.36 by root, Thu Oct 21 02:46:59 2010 UTC vs.
Revision 1.41 by root, Fri Mar 1 11:20:07 2013 UTC

… …
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::run; # 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::run EV::RUN_ONCE; # 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::run EV::RUN_NOWAIT; # try to handle same events, but do not block
54 54
55BEFORE YOU START USING THIS MODULE 55BEFORE YOU START USING THIS MODULE
56 If you only need timer, I/O, signal, child and idle watchers and not the 56 If you only need timer, I/O, signal, child and idle watchers and not the
57 advanced functionality of this module, consider using AnyEvent instead, 57 advanced functionality of this module, consider using AnyEvent instead,
58 specifically the simplified API described in AE. 58 specifically the simplified API described in AE.
… …
75 can use it through the AnyEvent module, stay portable to other event 75 can use it through the AnyEvent module, stay portable to other event
76 loops (if you don't rely on any watcher types not available through it) 76 loops (if you don't rely on any watcher types not available through it)
77 and still be faster than with any other event loop currently supported 77 and still be faster than with any other event loop currently supported
78 in Perl. 78 in Perl.
79 79
80 PORTING FROM EV 3.X to 4.X
81 EV version 4 introduces a number of incompatible changes summarised
82 here. According to the depreciation strategy used by libev, there is a
83 compatibility layer in place so programs should continue to run
84 unchanged (the XS interface lacks this layer, so programs using that one
85 need to be updated).
86
87 This compatibility layer will be switched off in some future release.
88
89 All changes relevant to Perl are renames of symbols, functions and
90 methods:
91
92 EV::loop => EV::run
93 EV::LOOP_NONBLOCK => EV::RUN_NOWAIT
94 EV::LOOP_ONESHOT => EV::RUN_ONCE
95
96 EV::unloop => EV::break
97 EV::UNLOOP_CANCEL => EV::BREAK_CANCEL
98 EV::UNLOOP_ONE => EV::BREAK_ONE
99 EV::UNLOOP_ALL => EV::BREAK_ALL
100
101 EV::TIMEOUT => EV::TIMER
102
103 EV::loop_count => EV::iteration
104 EV::loop_depth => EV::depth
105 EV::loop_verify => EV::verify
106
107 The loop object methods corresponding to the functions above have been
108 similarly renamed.
109
80 MODULE EXPORTS 110 MODULE EXPORTS
81 This module does not export any symbols. 111 This module does not export any symbols.
82 112
83EVENT LOOPS 113EVENT LOOPS
84 EV supports multiple event loops: There is a single "default event loop" 114 EV supports multiple event loops: There is a single "default event loop"
… …
121 Must be called after a fork in the child, before entering or 151 Must be called after a fork in the child, before entering or
122 continuing the event loop. An alternative is to use 152 continuing the event loop. An alternative is to use
123 "EV::FLAG_FORKCHECK" which calls this function automatically, at 153 "EV::FLAG_FORKCHECK" which calls this function automatically, at
124 some performance loss (refer to the libev documentation). 154 some performance loss (refer to the libev documentation).
125 155
126 $loop->loop_verify 156 $loop->verify
127 Calls "ev_verify" to make internal consistency checks (for debugging 157 Calls "ev_verify" to make internal consistency checks (for debugging
128 libev) and abort the program if any data structures were found to be 158 libev) and abort the program if any data structures were found to be
129 corrupted. 159 corrupted.
130 160
131 $loop = EV::default_loop [$flags] 161 $loop = EV::default_loop [$flags]
… …
203 $backend = EV::backend 233 $backend = EV::backend
204 $backend = $loop->backend 234 $backend = $loop->backend
205 Returns an integer describing the backend used by libev 235 Returns an integer describing the backend used by libev
206 (EV::BACKEND_SELECT or EV::BACKEND_EPOLL). 236 (EV::BACKEND_SELECT or EV::BACKEND_EPOLL).
207 237
208 EV::loop [$flags] 238 $active = EV::run [$flags]
209 $loop->loop ([$flags]) 239 $active = $loop->run ([$flags])
210 Begin checking for events and calling callbacks. It returns when a 240 Begin checking for events and calling callbacks. It returns when a
211 callback calls EV::unloop. 241 callback calls EV::unloop or the flasg are nonzero (in which case
242 the return value is true) or when there are no active watchers which
243 reference the loop (keepalive is true), in which case the return
244 value will be false. The returnv alue can generally be interpreted
245 as "if true, there is more work left to do".
212 246
213 The $flags argument can be one of the following: 247 The $flags argument can be one of the following:
214 248
215 0 as above 249 0 as above
216 EV::LOOP_ONESHOT block at most once (wait, but do not loop) 250 EV::RUN_ONCE block at most once (wait, but do not loop)
217 EV::LOOP_NONBLOCK do not block at all (fetch/handle events but do not wait) 251 EV::RUN_NOWAIT do not block at all (fetch/handle events but do not wait)
218 252
219 EV::unloop [$how] 253 EV::break [$how]
220 $loop->unloop ([$how]) 254 $loop->break ([$how])
221 When called with no arguments or an argument of EV::UNLOOP_ONE, 255 When called with no arguments or an argument of EV::BREAK_ONE, makes
222 makes the innermost call to EV::loop return. 256 the innermost call to EV::loop return.
223 257
224 When called with an argument of EV::UNLOOP_ALL, all calls to 258 When called with an argument of EV::BREAK_ALL, all calls to EV::loop
225 EV::loop will return as fast as possible. 259 will return as fast as possible.
226 260
227 $count = EV::loop_count 261 When called with an argument of EV::BREAK_CANCEL, any pending break
228 $count = $loop->loop_count 262 will be cancelled.
263
264 $count = EV::iteration
265 $count = $loop->iteration
229 Return the number of times the event loop has polled for new events. 266 Return the number of times the event loop has polled for new events.
230 Sometimes useful as a generation counter. 267 Sometimes useful as a generation counter.
231 268
232 EV::once $fh_or_undef, $events, $timeout, $cb->($revents) 269 EV::once $fh_or_undef, $events, $timeout, $cb->($revents)
233 $loop->once ($fh_or_undef, $events, $timeout, $cb->($revents)) 270 $loop->once ($fh_or_undef, $events, $timeout, $cb->($revents))
… …
250 287
251 EV::once doesn't return anything: the watchers stay active till 288 EV::once doesn't return anything: the watchers stay active till
252 either of them triggers, then they will be stopped and freed, and 289 either of them triggers, then they will be stopped and freed, and
253 the callback invoked. 290 the callback invoked.
254 291
255 EV::feed_fd_event ($fd, $revents) 292 EV::feed_fd_event $fd, $revents
256 $loop->feed_fd_event ($fd, $revents) 293 $loop->feed_fd_event ($fd, $revents)
257 Feed an event on a file descriptor into EV. EV will react to this 294 Feed an event on a file descriptor into EV. EV will react to this
258 call as if the readyness notifications specified by $revents (a 295 call as if the readyness notifications specified by $revents (a
259 combination of "EV::READ" and "EV::WRITE") happened on the file 296 combination of "EV::READ" and "EV::WRITE") happened on the file
260 descriptor $fd. 297 descriptor $fd.
261 298
262 EV::feed_signal_event ($signal) 299 EV::feed_signal_event $signal
263 Feed a signal event into EV. EV will react to this call as if the 300 Feed a signal event into the default loop. EV will react to this
264 signal specified by $signal had occured. 301 call as if the signal specified by $signal had occured.
302
303 EV::feed_signal $signal
304 Feed a signal event into EV - unlike "EV::feed_signal_event", this
305 works regardless of which loop has registered the signal, and is
306 mainly useful fro custom signal implementations.
265 307
266 EV::set_io_collect_interval $time 308 EV::set_io_collect_interval $time
267 $loop->set_io_collect_interval ($time) 309 $loop->set_io_collect_interval ($time)
268 EV::set_timeout_collect_interval $time 310 EV::set_timeout_collect_interval $time
269 $loop->set_timeout_collect_interval ($time) 311 $loop->set_timeout_collect_interval ($time)
… …
766 $w = $loop->check_ns ($callback) 808 $w = $loop->check_ns ($callback)
767 Call the callback just after the process wakes up again (after it 809 Call the callback just after the process wakes up again (after it
768 has gathered events), but before any other callbacks have been 810 has gathered events), but before any other callbacks have been
769 invoked. 811 invoked.
770 812
771 This is used to integrate other event-based software into the EV 813 This can be used to integrate other event-based software into the EV
772 mainloop: You register a prepare callback and in there, you create 814 mainloop: You register a prepare callback and in there, you create
773 io and timer watchers as required by the other software. Here is a 815 io and timer watchers as required by the other software. Here is a
774 real-world example of integrating Net::SNMP (with some details left 816 real-world example of integrating Net::SNMP (with some details left
775 out): 817 out):
776 818
… …
812 watchers are destroyed before this can happen (remember EV::check 854 watchers are destroyed before this can happen (remember EV::check
813 gets called first). 855 gets called first).
814 856
815 The "check_ns" variant doesn't start (activate) the newly created 857 The "check_ns" variant doesn't start (activate) the newly created
816 watcher. 858 watcher.
859
860 EV::CHECK constant issues
861 Like all other watcher types, there is a bitmask constant for use in
862 $revents and other places. The "EV::CHECK" is special as it has the
863 same name as the "CHECK" sub called by Perl. This doesn't cause big
864 issues on newer perls (beginning with 5.8.9), but it means thatthe
865 constant must be *inlined*, i.e. runtime calls will not work. That
866 means that as long as you always "use EV" and then "EV::CHECK" you
867 are on the safe side.
817 868
818 FORK WATCHERS - the audacity to resume the event loop after a fork 869 FORK WATCHERS - the audacity to resume the event loop after a fork
819 Fork watchers are called when a "fork ()" was detected. The invocation 870 Fork watchers are called when a "fork ()" was detected. The invocation
820 is done before the event loop blocks next and before "check" watchers 871 is done before the event loop blocks next and before "check" watchers
821 are being called, and only in the child after the fork. 872 are being called, and only in the child after the fork.
… …
878 929
879 Please see the libev documentation for further details. 930 Please see the libev documentation for further details.
880 931
881 $w = EV::async $callback 932 $w = EV::async $callback
882 $w = EV::async_ns $callback 933 $w = EV::async_ns $callback
934 $w = $loop->async ($callback)
935 $w = $loop->async_ns ($callback)
883 $w->send 936 $w->send
884 $bool = $w->async_pending 937 $bool = $w->async_pending
938
939 CLEANUP WATCHERS - how to clean up when the event loop goes away
940 Cleanup watchers are not supported on the Perl level, they can only be
941 used via XS currently.
885 942
886PERL SIGNALS 943PERL SIGNALS
887 While Perl signal handling (%SIG) is not affected by EV, the behaviour 944 While Perl signal handling (%SIG) is not affected by EV, the behaviour
888 with EV is as the same as any other C library: Perl-signals will only be 945 with EV is as the same as any other C library: Perl-signals will only be
889 handled when Perl runs, which means your signal handler might be invoked 946 handled when Perl runs, which means your signal handler might be invoked
… …
923 980
924 On win32, there is no notion of fork so all this doesn't apply, of 981 On win32, there is no notion of fork so all this doesn't apply, of
925 course. 982 course.
926 983
927SEE ALSO 984SEE ALSO
928 EV::ADNS (asynchronous DNS), Glib::EV (makes Glib/Gtk2 use EV as event 985 EV::MakeMaker - MakeMaker interface to XS API, EV::ADNS (asynchronous
929 loop), EV::Glib (embed Glib into EV), Coro::EV (efficient coroutines 986 DNS), Glib::EV (makes Glib/Gtk2 use EV as event loop), EV::Glib (embed
930 with EV), Net::SNMP::EV (asynchronous SNMP), AnyEvent for event-loop 987 Glib into EV), Coro::EV (efficient thread integration), Net::SNMP::EV
931 agnostic and portable event driven programming. 988 (asynchronous SNMP), AnyEvent for event-loop agnostic and portable event
989 driven programming.
932 990
933AUTHOR 991AUTHOR
934 Marc Lehmann <schmorp@schmorp.de> 992 Marc Lehmann <schmorp@schmorp.de>
935 http://home.schmorp.de/ 993 http://home.schmorp.de/
936 994

Diff Legend

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