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

Comparing EV/EV.pm (file contents):
Revision 1.112 by root, Sun Feb 15 01:44:40 2009 UTC vs.
Revision 1.125 by root, Thu Dec 31 06:59:47 2009 UTC

… …
76 76
77=cut 77=cut
78 78
79package EV; 79package EV;
80 80
81no warnings; 81use common::sense;
82use strict;
83 82
84BEGIN { 83BEGIN {
85 our $VERSION = '3.53'; 84 our $VERSION = '3.9';
86 use XSLoader; 85 use XSLoader;
87 XSLoader::load "EV", $VERSION; 86 XSLoader::load "EV", $VERSION;
88} 87}
89 88
90@EV::IO::ISA = 89@EV::IO::ISA =
… …
125will then also service the kqueue loop to some extent. See the example in 124will then also service the kqueue loop to some extent. See the example in
126the section about embed watchers for an example on how to achieve that. 125the section about embed watchers for an example on how to achieve that.
127 126
128=over 4 127=over 4
129 128
130=item $loop = new EV::loop [$flags] 129=item $loop = new EV::Loop [$flags]
131 130
132Create a new event loop as per the specified flags. Please refer to 131Create a new event loop as per the specified flags. Please refer to
133the C<ev_loop_new ()> function description in the libev documentation 132the C<ev_loop_new ()> function description in the libev documentation
134(L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#GLOBAL_FUNCTIONS>, 133(L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#GLOBAL_FUNCTIONS>,
135or locally-installed as F<EV::libev> manpage) for more info. 134or locally-installed as F<EV::libev> manpage) for more info.
… …
202 201
203Returns the time the last event loop iteration has been started. This 202Returns the time the last event loop iteration has been started. This
204is the time that (relative) timers are based on, and referring to it is 203is the time that (relative) timers are based on, and referring to it is
205usually faster then calling EV::time. 204usually faster then calling EV::time.
206 205
206=item EV::now_update
207
208=item $loop->now_update
209
210Establishes the current time by querying the kernel, updating the time
211returned by C<EV::now> in the progress. This is a costly operation and
212is usually done automatically within C<EV::loop>.
213
214This function is rarely useful, but when some event callback runs for a
215very long time without entering the event loop, updating libev's idea of
216the current time is a good idea.
217
218=item EV::suspend
219
220=item $loop->suspend
221
222=item EV::resume
223
224=item $loop->resume
225
226These two functions suspend and resume a loop, for use when the loop is
227not used for a while and timeouts should not be processed.
228
229A typical use case would be an interactive program such as a game: When
230the user presses C<^Z> to suspend the game and resumes it an hour later it
231would be best to handle timeouts as if no time had actually passed while
232the program was suspended. This can be achieved by calling C<suspend>
233in your C<SIGTSTP> handler, sending yourself a C<SIGSTOP> and calling
234C<resume> directly afterwards to resume timer processing.
235
236Effectively, all C<timer> watchers will be delayed by the time spend
237between C<suspend> and C<resume>, and all C<periodic> watchers
238will be rescheduled (that is, they will lose any events that would have
239occured while suspended).
240
241After calling C<suspend> you B<must not> call I<any> function on the given
242loop other than C<resume>, and you B<must not> call C<resume>
243without a previous call to C<suspend>.
244
245Calling C<suspend>/C<resume> has the side effect of updating the event
246loop time (see C<now_update>).
247
207=item $backend = EV::backend 248=item $backend = EV::backend
208 249
209=item $backend = $loop->backend 250=item $backend = $loop->backend
210 251
211Returns an integer describing the backend used by libev (EV::BACKEND_SELECT 252Returns an integer describing the backend used by libev (EV::BACKEND_SELECT
… …
289 330
290These advanced functions set the minimum block interval when polling for I/O events and the minimum 331These advanced functions set the minimum block interval when polling for I/O events and the minimum
291wait interval for timer events. See the libev documentation at 332wait interval for timer events. See the libev documentation at
292L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#FUNCTIONS_CONTROLLING_THE_EVENT_LOOP> 333L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod#FUNCTIONS_CONTROLLING_THE_EVENT_LOOP>
293(locally installed as F<EV::libev>) for a more detailed discussion. 334(locally installed as F<EV::libev>) for a more detailed discussion.
335
336=item $count = EV::pending_count
337
338=item $count = $loop->pending_count
339
340Returns the number of currently pending watchers.
341
342=item EV::invoke_pending
343
344=item $loop->invoke_pending
345
346Invoke all currently pending watchers.
294 347
295=back 348=back
296 349
297 350
298=head1 WATCHER OBJECTS 351=head1 WATCHER OBJECTS
… …
403 456
404=item $previous_state = $w->keepalive ($bool) 457=item $previous_state = $w->keepalive ($bool)
405 458
406Normally, C<EV::loop> will return when there are no active watchers 459Normally, C<EV::loop> will return when there are no active watchers
407(which is a "deadlock" because no progress can be made anymore). This is 460(which is a "deadlock" because no progress can be made anymore). This is
408convinient because it allows you to start your watchers (and your jobs), 461convenient because it allows you to start your watchers (and your jobs),
409call C<EV::loop> once and when it returns you know that all your jobs are 462call C<EV::loop> once and when it returns you know that all your jobs are
410finished (or they forgot to register some watchers for their task :). 463finished (or they forgot to register some watchers for their task :).
411 464
412Sometimes, however, this gets in your way, for example when the module 465Sometimes, however, this gets in your way, for example when the module
413that calls C<EV::loop> (usually the main program) is not the same module 466that calls C<EV::loop> (usually the main program) is not the same module
… …
645 698
646=item $w = EV::signal $signal, $callback 699=item $w = EV::signal $signal, $callback
647 700
648=item $w = EV::signal_ns $signal, $callback 701=item $w = EV::signal_ns $signal, $callback
649 702
703=item $w = $loop->signal ($signal, $callback)
704
705=item $w = $loop->signal_ns ($signal, $callback)
706
650Call the callback when $signal is received (the signal can be specified by 707Call the callback when $signal is received (the signal can be specified by
651number or by name, just as with C<kill> or C<%SIG>). 708number or by name, just as with C<kill> or C<%SIG>).
709
710Only one event loop can grab a given signal - attempting to grab the same
711signal from two EV loops will crash the program immediately or cause data
712corruption.
652 713
653EV will grab the signal for the process (the kernel only allows one 714EV will grab the signal for the process (the kernel only allows one
654component to receive a signal at a time) when you start a signal watcher, 715component to receive a signal at a time) when you start a signal watcher,
655and removes it again when you stop it. Perl does the same when you 716and removes it again when you stop it. Perl does the same when you
656add/remove callbacks to C<%SIG>, so watch out. 717add/remove callbacks to C<%SIG>, so watch out.
… …
1002 1063
1003=back 1064=back
1004 1065
1005=head3 ASYNC WATCHERS - how to wake up another event loop 1066=head3 ASYNC WATCHERS - how to wake up another event loop
1006 1067
1007Async watchers are provided by EV, but have little use in perl directly, as perl 1068Async watchers are provided by EV, but have little use in perl directly,
1008neither supports threads nor direct access to signal handlers or other 1069as perl neither supports threads running in parallel nor direct access to
1009contexts where they could be of value. 1070signal handlers or other contexts where they could be of value.
1010 1071
1011It is, however, possible to use them from the XS level. 1072It is, however, possible to use them from the XS level.
1012 1073
1013Please see the libev documentation for further details. 1074Please see the libev documentation for further details.
1014 1075
… …
1042 my $async_check = EV::check sub { }; 1103 my $async_check = EV::check sub { };
1043 1104
1044This ensures that perl gets into control for a short time to handle any 1105This ensures that perl gets into control for a short time to handle any
1045pending signals, and also ensures (slightly) slower overall operation. 1106pending signals, and also ensures (slightly) slower overall operation.
1046 1107
1047=head1 THREADS 1108=head1 ITHREADS
1048 1109
1049Threads are not supported by this module in any way. Perl pseudo-threads 1110Ithreads are not supported by this module in any way. Perl pseudo-threads
1050is evil stuff and must die. As soon as Perl gains real threads I will work 1111is evil stuff and must die. Real threads as provided by Coro are fully
1051on thread support for it. 1112supported (and enhanced support is available via L<Coro::EV>).
1052 1113
1053=head1 FORK 1114=head1 FORK
1054 1115
1055Most of the "improved" event delivering mechanisms of modern operating 1116Most of the "improved" event delivering mechanisms of modern operating
1056systems have quite a few problems with fork(2) (to put it bluntly: it is 1117systems have quite a few problems with fork(2) (to put it bluntly: it is

Diff Legend

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