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

Comparing EV/EV.pm (file contents):
Revision 1.44 by root, Thu Nov 22 04:52:23 2007 UTC vs.
Revision 1.50 by root, Sat Nov 24 08:42:38 2007 UTC

… …
62 our $VERSION = '1.2'; 62 our $VERSION = '1.2';
63 use XSLoader; 63 use XSLoader;
64 XSLoader::load "EV", $VERSION; 64 XSLoader::load "EV", $VERSION;
65} 65}
66 66
67@EV::Io::ISA = 67@EV::IO::ISA =
68@EV::Timer::ISA = 68@EV::Timer::ISA =
69@EV::Periodic::ISA = 69@EV::Periodic::ISA =
70@EV::Signal::ISA = 70@EV::Signal::ISA =
71@EV::Idle::ISA = 71@EV::Idle::ISA =
72@EV::Prepare::ISA = 72@EV::Prepare::ISA =
… …
117innermost call to EV::loop return. 117innermost call to EV::loop return.
118 118
119When called with an argument of EV::UNLOOP_ALL, all calls to EV::loop will return as 119When called with an argument of EV::UNLOOP_ALL, all calls to EV::loop will return as
120fast as possible. 120fast as possible.
121 121
122=item EV::once $fh_or_undef, $events, $timeout, $cb->($revents)
123
124This function rolls together an I/O and a timer watcher for a single
125one-shot event without the need for managing a watcher object.
126
127If C<$fh_or_undef> is a filehandle or file descriptor, then C<$events>
128must be a bitset containing either C<EV::READ>, C<EV::WRITE> or C<EV::READ
129| EV::WRITE>, indicating the type of I/O event you want to wait for. If
130you do not want to wait for some I/O event, specify C<undef> for
131C<$fh_or_undef> and C<0> for C<$events>).
132
133If timeout is C<undef> or negative, then there will be no
134timeout. Otherwise a EV::timer with this value will be started.
135
136When an error occurs or either the timeout or I/O watcher triggers, then
137the callback will be called with the received event set (in general
138you can expect it to be a combination of C<EV:ERROR>, C<EV::READ>,
139C<EV::WRITE> and C<EV::TIMEOUT>).
140
141EV::once doesn't return anything: the watchers stay active till either
142of them triggers, then they will be stopped and freed, and the callback
143invoked.
144
122=back 145=back
123 146
124=head2 WATCHER 147=head2 WATCHER
125 148
126A watcher is an object that gets created to record your interest in some 149A watcher is an object that gets created to record your interest in some
… …
210watchers with higher priority will be invoked first. The valid range of 233watchers with higher priority will be invoked first. The valid range of
211priorities lies between EV::MAXPRI (default 2) and EV::MINPRI (default 234priorities lies between EV::MAXPRI (default 2) and EV::MINPRI (default
212-2). If the priority is outside this range it will automatically be 235-2). If the priority is outside this range it will automatically be
213normalised to the nearest valid priority. 236normalised to the nearest valid priority.
214 237
215The default priority of any newly-created weatcher is 0. 238The default priority of any newly-created watcher is 0.
239
240Note that the priority semantics have not yet been fleshed out and are
241subject to almost certain change.
216 242
217=item $w->trigger ($revents) 243=item $w->trigger ($revents)
218 244
219Call the callback *now* with the given event mask. 245Call the callback *now* with the given event mask.
220 246
247=item $previous_state = $w->keepalive ($bool)
248
249Normally, C<EV::loop> will return when there are no active watchers
250(which is a "deadlock" because no progress can be made anymore). This is
251convinient because it allows you to start your watchers (and your jobs),
252call C<EV::loop> once and when it returns you know that all your jobs are
253finished (or they forgot to register some watchers for their task :).
254
255Sometimes, however, this gets in your way, for example when you the module
256that calls C<EV::loop> (usually the main program) is not the same module
257as a long-living watcher (for example a DNS client module written by
258somebody else even). Then you might want any outstanding requests to be
259handled, but you would not want to keep C<EV::loop> from returning just
260because you happen to have this long-running UDP port watcher.
261
262In this case you can clear the keepalive status, which means that even
263though your watcher is active, it won't keep C<EV::loop> from returning.
264
265The initial value for keepalive is true (enabled), and you cna change it
266any time.
267
268Example: Register an IO watcher for some UDP socket but do not keep the
269event loop from running just because of that watcher.
270
271 my $udp_socket = ...
272 my $udp_watcher = EV::io $udp_socket, EV::READ, sub { ... };
273 $udp_watcher->keepalive (0);
221 274
222=item $w = EV::io $fileno_or_fh, $eventmask, $callback 275=item $w = EV::io $fileno_or_fh, $eventmask, $callback
223 276
224=item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback 277=item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback
225 278
… …
493 # do nothing unless active 546 # do nothing unless active
494 $dispatcher->{_event_queue_h} 547 $dispatcher->{_event_queue_h}
495 or return; 548 or return;
496 549
497 # make the dispatcher handle any outstanding stuff 550 # make the dispatcher handle any outstanding stuff
551 ... not shown
498 552
499 # create an IO watcher for each and every socket 553 # create an IO watcher for each and every socket
500 @snmp_watcher = ( 554 @snmp_watcher = (
501 (map { EV::io $_, EV::READ, sub { } } 555 (map { EV::io $_, EV::READ, sub { } }
502 keys %{ $dispatcher->{_descriptors} }), 556 keys %{ $dispatcher->{_descriptors} }),
557
558 EV::timer +($event->[Net::SNMP::Dispatcher::_ACTIVE]
559 ? $event->[Net::SNMP::Dispatcher::_TIME] - EV::now : 0),
560 0, sub { },
503 ); 561 );
504
505 # if there are any timeouts, also create a timer
506 push @snmp_watcher, EV::timer $event->[Net::SNMP::Dispatcher::_TIME] - EV::now, 0, sub { }
507 if $event->[Net::SNMP::Dispatcher::_ACTIVE];
508 }; 562 };
509 563
510The callbacks are irrelevant, the only purpose of those watchers is 564The callbacks are irrelevant (and are not even being called), the
511to wake up the process as soon as one of those events occurs (socket 565only purpose of those watchers is to wake up the process as soon as
512readable, or timer timed out). The corresponding EV::check watcher will then 566one of those events occurs (socket readable, or timer timed out). The
513clean up: 567corresponding EV::check watcher will then clean up:
514 568
515 our $snmp_check = EV::check sub { 569 our $snmp_check = EV::check sub {
516 # destroy all watchers 570 # destroy all watchers
517 @snmp_watcher = (); 571 @snmp_watcher = ();
518 572
519 # make the dispatcher handle any new stuff 573 # make the dispatcher handle any new stuff
574 ... not shown
520 }; 575 };
521 576
522The callbacks of the created watchers will not be called as the watchers 577The callbacks of the created watchers will not be called as the watchers
523are destroyed before this cna happen (remember EV::check gets called 578are destroyed before this cna happen (remember EV::check gets called
524first). 579first).
… …
527 582
528=back 583=back
529 584
530=head1 THREADS 585=head1 THREADS
531 586
532Threads are not supported by this in any way. Perl pseudo-threads is evil 587Threads are not supported by this module in any way. Perl pseudo-threads
533stuff and must die. 588is evil stuff and must die. As soon as Perl gains real threads I will work
589on thread support for it.
590
591=head1 FORK
592
593Most of the "improved" event delivering mechanisms of modern operating
594systems have quite a few problems with fork(2) (to put it bluntly: it is
595not supported and usually destructive). Libev makes it possible to work
596around this by having a function that recreates the kernel state after
597fork in the child.
598
599On non-win32 platforms, this module requires the pthread_atfork
600functionality to do this automatically for you. This function is quite
601buggy on most BSDs, though, so YMMV. The overhead for this is quite
602negligible, because everything the function currently does is set a flag
603that is checked only when the event loop gets used the next time, so when
604you do fork but not use EV, the overhead is minimal.
605
606On win32, there is no notion of fork so all this doesn't apply, of course.
534 607
535=cut 608=cut
536 609
537our $DIED = sub { 610our $DIED = sub {
538 warn "EV: error in callback (ignoring): $@"; 611 warn "EV: error in callback (ignoring): $@";

Diff Legend

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