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

Comparing EV/EV.pm (file contents):
Revision 1.115 by root, Tue Apr 28 00:50:56 2009 UTC vs.
Revision 1.126 by root, Tue Mar 16 17:11:48 2010 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.6'; 84 our $VERSION = '4.00';
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 =
… …
300timeout. Otherwise a EV::timer with this value will be started. 299timeout. Otherwise a EV::timer with this value will be started.
301 300
302When an error occurs or either the timeout or I/O watcher triggers, then 301When an error occurs or either the timeout or I/O watcher triggers, then
303the callback will be called with the received event set (in general 302the callback will be called with the received event set (in general
304you can expect it to be a combination of C<EV::ERROR>, C<EV::READ>, 303you can expect it to be a combination of C<EV::ERROR>, C<EV::READ>,
305C<EV::WRITE> and C<EV::TIMEOUT>). 304C<EV::WRITE> and C<EV::TIMER>).
306 305
307EV::once doesn't return anything: the watchers stay active till either 306EV::once doesn't return anything: the watchers stay active till either
308of them triggers, then they will be stopped and freed, and the callback 307of them triggers, then they will be stopped and freed, and the callback
309invoked. 308invoked.
310 309
… …
332These 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
333wait interval for timer events. See the libev documentation at 332wait interval for timer events. See the libev documentation at
334L<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>
335(locally installed as F<EV::libev>) for a more detailed discussion. 334(locally installed as F<EV::libev>) for a more detailed discussion.
336 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.
347
337=back 348=back
338 349
339 350
340=head1 WATCHER OBJECTS 351=head1 WATCHER OBJECTS
341 352
… …
355 366
356Each watcher type has its associated bit in revents, so you can use the 367Each watcher type has its associated bit in revents, so you can use the
357same callback for multiple watchers. The event mask is named after the 368same callback for multiple watchers. The event mask is named after the
358type, i.e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE, 369type, i.e. EV::child sets EV::CHILD, EV::prepare sets EV::PREPARE,
359EV::periodic sets EV::PERIODIC and so on, with the exception of I/O events 370EV::periodic sets EV::PERIODIC and so on, with the exception of I/O events
360(which can set both EV::READ and EV::WRITE bits), and EV::timer (which 371(which can set both EV::READ and EV::WRITE bits).
361uses EV::TIMEOUT).
362 372
363In the rare case where one wants to create a watcher but not start it at 373In the rare case where one wants to create a watcher but not start it at
364the same time, each constructor has a variant with a trailing C<_ns> in 374the same time, each constructor has a variant with a trailing C<_ns> in
365its name, e.g. EV::io has a non-starting variant EV::io_ns and so on. 375its name, e.g. EV::io has a non-starting variant EV::io_ns and so on.
366 376
… …
445 455
446=item $previous_state = $w->keepalive ($bool) 456=item $previous_state = $w->keepalive ($bool)
447 457
448Normally, C<EV::loop> will return when there are no active watchers 458Normally, C<EV::loop> will return when there are no active watchers
449(which is a "deadlock" because no progress can be made anymore). This is 459(which is a "deadlock" because no progress can be made anymore). This is
450convinient because it allows you to start your watchers (and your jobs), 460convenient because it allows you to start your watchers (and your jobs),
451call C<EV::loop> once and when it returns you know that all your jobs are 461call C<EV::loop> once and when it returns you know that all your jobs are
452finished (or they forgot to register some watchers for their task :). 462finished (or they forgot to register some watchers for their task :).
453 463
454Sometimes, however, this gets in your way, for example when the module 464Sometimes, however, this gets in your way, for example when the module
455that calls C<EV::loop> (usually the main program) is not the same module 465that calls C<EV::loop> (usually the main program) is not the same module
… …
687 697
688=item $w = EV::signal $signal, $callback 698=item $w = EV::signal $signal, $callback
689 699
690=item $w = EV::signal_ns $signal, $callback 700=item $w = EV::signal_ns $signal, $callback
691 701
702=item $w = $loop->signal ($signal, $callback)
703
704=item $w = $loop->signal_ns ($signal, $callback)
705
692Call the callback when $signal is received (the signal can be specified by 706Call the callback when $signal is received (the signal can be specified by
693number or by name, just as with C<kill> or C<%SIG>). 707number or by name, just as with C<kill> or C<%SIG>).
708
709Only one event loop can grab a given signal - attempting to grab the same
710signal from two EV loops will crash the program immediately or cause data
711corruption.
694 712
695EV will grab the signal for the process (the kernel only allows one 713EV will grab the signal for the process (the kernel only allows one
696component to receive a signal at a time) when you start a signal watcher, 714component to receive a signal at a time) when you start a signal watcher,
697and removes it again when you stop it. Perl does the same when you 715and removes it again when you stop it. Perl does the same when you
698add/remove callbacks to C<%SIG>, so watch out. 716add/remove callbacks to C<%SIG>, so watch out.
… …
1044 1062
1045=back 1063=back
1046 1064
1047=head3 ASYNC WATCHERS - how to wake up another event loop 1065=head3 ASYNC WATCHERS - how to wake up another event loop
1048 1066
1049Async watchers are provided by EV, but have little use in perl directly, as perl 1067Async watchers are provided by EV, but have little use in perl directly,
1050neither supports threads nor direct access to signal handlers or other 1068as perl neither supports threads running in parallel nor direct access to
1051contexts where they could be of value. 1069signal handlers or other contexts where they could be of value.
1052 1070
1053It is, however, possible to use them from the XS level. 1071It is, however, possible to use them from the XS level.
1054 1072
1055Please see the libev documentation for further details. 1073Please see the libev documentation for further details.
1056 1074
… …
1084 my $async_check = EV::check sub { }; 1102 my $async_check = EV::check sub { };
1085 1103
1086This ensures that perl gets into control for a short time to handle any 1104This ensures that perl gets into control for a short time to handle any
1087pending signals, and also ensures (slightly) slower overall operation. 1105pending signals, and also ensures (slightly) slower overall operation.
1088 1106
1089=head1 THREADS 1107=head1 ITHREADS
1090 1108
1091Threads are not supported by this module in any way. Perl pseudo-threads 1109Ithreads are not supported by this module in any way. Perl pseudo-threads
1092is evil stuff and must die. As soon as Perl gains real threads I will work 1110is evil stuff and must die. Real threads as provided by Coro are fully
1093on thread support for it. 1111supported (and enhanced support is available via L<Coro::EV>).
1094 1112
1095=head1 FORK 1113=head1 FORK
1096 1114
1097Most of the "improved" event delivering mechanisms of modern operating 1115Most of the "improved" event delivering mechanisms of modern operating
1098systems have quite a few problems with fork(2) (to put it bluntly: it is 1116systems have quite a few problems with fork(2) (to put it bluntly: it is

Diff Legend

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