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

Comparing EV/EV.pm (file contents):
Revision 1.55 by root, Tue Nov 27 08:11:52 2007 UTC vs.
Revision 1.61 by root, Thu Dec 6 03:13:07 2007 UTC

… …
67package EV; 67package EV;
68 68
69use strict; 69use strict;
70 70
71BEGIN { 71BEGIN {
72 our $VERSION = '1.4'; 72 our $VERSION = '1.6';
73 use XSLoader; 73 use XSLoader;
74 XSLoader::load "EV", $VERSION; 74 XSLoader::load "EV", $VERSION;
75} 75}
76 76
77@EV::IO::ISA = 77@EV::IO::ISA =
78@EV::Timer::ISA = 78@EV::Timer::ISA =
79@EV::Periodic::ISA = 79@EV::Periodic::ISA =
80@EV::Signal::ISA = 80@EV::Signal::ISA =
81@EV::Child::ISA =
82@EV::Stat::ISA =
81@EV::Idle::ISA = 83@EV::Idle::ISA =
82@EV::Prepare::ISA = 84@EV::Prepare::ISA =
83@EV::Check::ISA = 85@EV::Check::ISA =
84@EV::Child::ISA =
85@EV::Embed::ISA = 86@EV::Embed::ISA =
86@EV::Stat::ISA = "EV::Watcher"; 87@EV::Fork::ISA =
88 "EV::Watcher";
87 89
88=head1 BASIC INTERFACE 90=head1 BASIC INTERFACE
89 91
90=over 4 92=over 4
91 93
… …
128When called with no arguments or an argument of EV::UNLOOP_ONE, makes the 130When called with no arguments or an argument of EV::UNLOOP_ONE, makes the
129innermost call to EV::loop return. 131innermost call to EV::loop return.
130 132
131When called with an argument of EV::UNLOOP_ALL, all calls to EV::loop will return as 133When called with an argument of EV::UNLOOP_ALL, all calls to EV::loop will return as
132fast as possible. 134fast as possible.
135
136=item $count = EV::loop_count
137
138Return the number of times the event loop has polled for new
139events. Sometiems useful as a generation counter.
133 140
134=item EV::once $fh_or_undef, $events, $timeout, $cb->($revents) 141=item EV::once $fh_or_undef, $events, $timeout, $cb->($revents)
135 142
136This function rolls together an I/O and a timer watcher for a single 143This function rolls together an I/O and a timer watcher for a single
137one-shot event without the need for managing a watcher object. 144one-shot event without the need for managing a watcher object.
… …
551watcher for all pids). 558watcher for all pids).
552 559
553=back 560=back
554 561
555 562
563=head3 STAT WATCHERS - did the file attributes just change?
564
565=over 4
566
567=item $w = EV::stat $path, $interval, $callback
568
569=item $w = EV::stat_ns $path, $interval, $callback
570
571Call the callback when a file status change has been detected on
572C<$path>. The C<$path> does not need to exist, changing from "path exists"
573to "path does not exist" is a status change like any other.
574
575The C<$interval> is a recommended polling interval for systems where
576OS-supported change notifications don't exist or are not supported. If
577you use C<0> then an unspecified default is used (which is highly
578recommended!), which is to be expected to be around five seconds usually.
579
580This watcher type is not meant for massive numbers of stat watchers,
581as even with OS-supported change notifications, this can be
582resource-intensive.
583
584The C<stat_ns> variant doesn't start (activate) the newly created watcher.
585
586=item ... = $w->stat
587
588This call is very similar to the perl C<stat> built-in: It stats (using
589C<lstat>) the path specified in the watcher and sets perls stat cache (as
590well as EV's idea of the current stat values) to the values found.
591
592In scalar context, a boolean is return indicating success or failure of
593the stat. In list context, the same 13-value list as with stat is returned
594(except that the blksize and blocks fields are not reliable).
595
596In the case of an error, errno is set to C<ENOENT> (regardless of the
597actual error value) and the C<nlink> value is forced to zero (if the stat
598was successful then nlink is guaranteed to be non-zero).
599
600See also the next two entries for more info.
601
602=item ... = $w->attr
603
604Just like C<< $w->stat >>, but without the initial stat'ing: this returns
605the values most recently detected by EV. See the next entry for more info.
606
607=item ... = $w->prev
608
609Just like C<< $w->stat >>, but without the initial stat'ing: this returns
610the previous set of values, before the change.
611
612That is, when the watcher callback is invoked, C<< $w->prev >> will be set
613to the values found I<before> a change was detected, while C<< $w->attr >>
614returns the values found leading to the change detection. The difference (if any)
615between C<prev> and C<attr> is what triggered the callback.
616
617If you did something to the filesystem object and do not want to trigger
618yet another change, you can call C<stat> to update EV's idea of what the
619current attributes are.
620
621=item $w->set ($path, $interval)
622
623Reconfigures the watcher, see the constructor above for details. Can be
624called at any time.
625
626=item $current_path = $w->path
627
628=item $old_path = $w->path ($new_path)
629
630Returns the previously set path and optionally set a new one.
631
632=item $current_interval = $w->interval
633
634=item $old_interval = $w->interval ($new_interval)
635
636Returns the previously set interval and optionally set a new one. Can be
637used to query the actual interval used.
638
639=back
640
641
556=head3 IDLE WATCHERS - when you've got nothing better to do... 642=head3 IDLE WATCHERS - when you've got nothing better to do...
557 643
558=over 4 644=over 4
559 645
560=item $w = EV::idle $callback 646=item $w = EV::idle $callback
… …
646 732
647The C<check_ns> variant doesn't start (activate) the newly created watcher. 733The C<check_ns> variant doesn't start (activate) the newly created watcher.
648 734
649=back 735=back
650 736
651=head3 STAT WATCHERS - did the file attributes just change?
652 737
653=over 4 738=head3 FORK WATCHERS - the audacity to resume the event loop after a fork
654 739
655=item $w = EV::stat $path, $interval, $callback 740Fork watchers are called when a C<fork ()> was detected. The invocation
741is done before the event loop blocks next and before C<check> watchers
742are being called, and only in the child after the fork.
656 743
657=item $w = EV::stat_ns $path, $interval, $callback 744=over 4
658 745
659Call the callback when a file status change has been detected on 746=item $w = EV::fork $callback
660C<$path>. The C<$path> does not need to exist, changing from "path exists"
661to "path does not exist" is a status change like any other.
662 747
663The C<$interval> is a recommended polling interval for systems where 748=item $w = EV::fork_ns $callback
664OS-supported change notifications don't exist or are not supported. If
665you use C<0> then an unspecified default is used (which is highly
666recommended!), which is to be expected to be around five seconds usually.
667 749
668This watcher type is not meant for massive numbers of stat watchers, 750Call the callback before the event loop is resumed in the child process
669as even with OS-supported change notifications, this can be 751after a fork.
670resource-intensive.
671 752
672The C<stat_ns> variant doesn't start (activate) the newly created watcher. 753The C<fork_ns> variant doesn't start (activate) the newly created watcher.
673 754
674=item $w->set ($path, $interval)
675
676Reconfigures the watcher, see the constructor above for details. Can be
677called at any time.
678
679=item $current_path = $w->path
680
681=item $old_path = $w->path ($new_path)
682
683Returns the previously set path and optionally set a new one.
684
685=item $current_interval = $w->interval
686
687=item $old_interval = $w->interval ($new_interval)
688
689Returns the previously set interval and optionally set a new one. Can be
690used to query the actual interval used.
691
692=back 755=back
693 756
757
758=head1 PERL SIGNALS
759
760While Perl signal handling (C<%SIG>) is not affected by EV, the behaviour
761with EV is as the same as any other C library: Perl-signals will only be
762handled when Perl runs, which means your signal handler might be invoked
763only the next time an event callback is invoked.
764
765The solution is to use EV signal watchers (see C<EV::signal>), which will
766ensure proper operations with regards to other event watchers.
767
768If you cannot do this for whatever reason, you can also force a watcher
769to be called on every event loop iteration by installing a C<EV::check>
770watcher:
771
772 my $async_check = EV::check sub { };
773
774This ensures that perl shortly gets into control for a short time, and
775also ensures slower overall operation.
694 776
695=head1 THREADS 777=head1 THREADS
696 778
697Threads are not supported by this module in any way. Perl pseudo-threads 779Threads are not supported by this module in any way. Perl pseudo-threads
698is evil stuff and must die. As soon as Perl gains real threads I will work 780is evil stuff and must die. As soon as Perl gains real threads I will work
… …
726 808
7271; 8091;
728 810
729=head1 SEE ALSO 811=head1 SEE ALSO
730 812
731L<EV::DNS>. 813L<EV::ADNS> (asynchronous dns), L<Glib::EV> (makes Glib/Gtk2 use EV as
814event loop), L<Coro::EV> (efficient coroutines with EV).
732 815
733=head1 AUTHOR 816=head1 AUTHOR
734 817
735 Marc Lehmann <schmorp@schmorp.de> 818 Marc Lehmann <schmorp@schmorp.de>
736 http://home.schmorp.de/ 819 http://home.schmorp.de/

Diff Legend

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