[ViewVC] Diff of: cvs/EV/EV.pm

Comparing EV/EV.pm (file contents):
Revision 1.136 by root, Thu Jan 19 17:55:23 2012 UTC vs.
Revision 1.155 by root, Sun May 12 21:58:31 2019 UTC

       my ($w, $revents) = @_;
       warn $w->path, " has changed somehow.\n";
    };
    # MAINLOOP
-   EV::run;                # loop until EV::unloop is called or all watchers stop
+   EV::run;                # loop until EV::break is called or all watchers stop
    EV::run EV::RUN_ONCE;   # block until at least one event could be handled
    EV::run EV::RUN_NOWAIT; # try to handle same events, but do not block
 =head1 BEFORE YOU START USING THIS MODULE
 package EV;
 use common::sense;
 BEGIN {
-   our $VERSION = '4.10';
+   our $VERSION = 4.25;
    use XSLoader;
+   local $^W = 0; # avoid spurious warning
    XSLoader::load "EV", $VERSION;
 }
 @EV::IO::ISA       =
 @EV::Timer::ISA    =
 =item $loop->now_update
 Establishes the current time by querying the kernel, updating the time
 returned by C<EV::now> in the progress. This is a costly operation and
-is usually done automatically within C<EV::loop>.
+is usually done automatically within C<EV::run>.
 This function is rarely useful, but when some event callback runs for a
 very long time without entering the event loop, updating libev's idea of
 the current time is a good idea.
 =item $backend = $loop->backend
 Returns an integer describing the backend used by libev (EV::BACKEND_SELECT
 or EV::BACKEND_EPOLL).
-=item EV::run [$flags]
+=item $active = EV::run [$flags]
-=item $loop->run ([$flags])
+=item $active = $loop->run ([$flags])
 Begin checking for events and calling callbacks. It returns when a
-callback calls EV::unloop.
+callback calls EV::break or the flags are nonzero (in which case the
+return value is true) or when there are no active watchers which reference
+the loop (keepalive is true), in which case the return value will be
+false. The return value can generally be interpreted as "if true, there is
+more work left to do".
 The $flags argument can be one of the following:
    0               as above
    EV::RUN_ONCE    block at most once (wait, but do not loop)
 =item EV::break [$how]
 =item $loop->break ([$how])
 When called with no arguments or an argument of EV::BREAK_ONE, makes the
-innermost call to EV::loop return.
+innermost call to EV::run return.
-When called with an argument of EV::BREAK_ALL, all calls to EV::loop will
+When called with an argument of EV::BREAK_ALL, all calls to EV::run will
 return as fast as possible.
 When called with an argument of EV::BREAK_CANCEL, any pending break will
 be cancelled.
 | EV::WRITE>, indicating the type of I/O event you want to wait for. If
 you do not want to wait for some I/O event, specify C<undef> for
 C<$fh_or_undef> and C<0> for C<$events>).
 If timeout is C<undef> or negative, then there will be no
-timeout. Otherwise a EV::timer with this value will be started.
+timeout. Otherwise an C<EV::timer> with this value will be started.
 When an error occurs or either the timeout or I/O watcher triggers, then
 the callback will be called with the received event set (in general
 you can expect it to be a combination of C<EV::ERROR>, C<EV::READ>,
 C<EV::WRITE> and C<EV::TIMER>).
 returns its C<$revents> bitset (as if its callback was invoked). If the
 watcher isn't pending it does nothing and returns C<0>.
 =item $previous_state = $w->keepalive ($bool)
-Normally, C<EV::loop> will return when there are no active watchers
+Normally, C<EV::run> will return when there are no active watchers
 (which is a "deadlock" because no progress can be made anymore). This is
 convenient because it allows you to start your watchers (and your jobs),
-call C<EV::loop> once and when it returns you know that all your jobs are
+call C<EV::run> once and when it returns you know that all your jobs are
 finished (or they forgot to register some watchers for their task :).
 Sometimes, however, this gets in your way, for example when the module
-that calls C<EV::loop> (usually the main program) is not the same module
+that calls C<EV::run> (usually the main program) is not the same module
 as a long-living watcher (for example a DNS client module written by
 somebody else even). Then you might want any outstanding requests to be
-handled, but you would not want to keep C<EV::loop> from returning just
+handled, but you would not want to keep C<EV::run> from returning just
 because you happen to have this long-running UDP port watcher.
 In this case you can clear the keepalive status, which means that even
-though your watcher is active, it won't keep C<EV::loop> from returning.
+though your watcher is active, it won't keep C<EV::run> from returning.
 The initial value for keepalive is true (enabled), and you can change it
 any time.
 Example: Register an I/O watcher for some UDP socket but do not keep the
 =item $w = $loop->timer ($after, $repeat, $callback)
 =item $w = $loop->timer_ns ($after, $repeat, $callback)
-Calls the callback after C<$after> seconds (which may be fractional). If
+Calls the callback after C<$after> seconds (which may be fractional or
-C<$repeat> is non-zero, the timer will be restarted (with the $repeat
+negative). If C<$repeat> is non-zero, the timer will be restarted (with
-value as $after) after the callback returns.
+the $repeat value as $after) after the callback returns.
 This means that the callback would be called roughly after C<$after>
 seconds, and then every C<$repeat> seconds. The timer does his best not
 to drift, but it will not invoke the timer more often then once per event
 loop iteration, and might drift in other cases. If that isn't acceptable,
 in front of the machine while the timer is running and changes the system
 clock, the timer will nevertheless run (roughly) the same time.
 The C<timer_ns> variant doesn't start (activate) the newly created watcher.
-=item $w->set ($after, $repeat)
+=item $w->set ($after, $repeat = 0)
 Reconfigures the watcher, see the constructor above for details. Can be called at
 any time.
 =item $w->again
+=item $w->again ($repeat)
 Similar to the C<start> method, but has special semantics for repeating timers:
 If the timer is active and non-repeating, it will be stopped.
 This behaviour is useful when you have a timeout for some IO
 operation. You create a timer object with the same value for C<$after> and
 C<$repeat>, and then, in the read/write watcher, run the C<again> method
 on the timeout.
+If called with a C<$repeat> argument, then it uses this a timer repeat
+value.
+=item $after = $w->remaining
+Calculates and returns the remaining time till the timer will fire.
 =back
 =head3 PERIODIC WATCHERS - to cron or not to cron?
 surpasses this time.
 =item * repeating interval timer ($interval > 0, $reschedule_cb = 0)
 In this mode the watcher will always be scheduled to time out at the
-next C<$at + N * $interval> time (for some integer N) and then repeat,
+next C<$at + N * $interval> time (for the lowest integer N) and then repeat,
-regardless of any time jumps.
+regardless of any time jumps. Note that, since C<N> can be negative, the
+first trigger can happen before C<$at>.
 This can be used to create timers that do not drift with respect to system
 time:
    my $hourly = EV::periodic 0, 3600, 0, sub { print "once/hour\n" };
 That doesn't mean there will always be 3600 seconds in between triggers,
-but only that the the clalback will be called when the system time shows a
+but only that the the callback will be called when the system time shows a
 full hour (UTC).
 Another way to think about it (for the mathematically inclined) is that
 EV::periodic will try to run the callback in this mode at the next
 possible time where C<$time = $at (mod $interval)>, regardless of any time
 time as second argument.
 I<This callback MUST NOT stop or destroy this or any other periodic
 watcher, ever, and MUST NOT call any event loop functions or methods>. If
 you need to stop it, return 1e30 and stop it afterwards. You may create
-and start a C<EV::prepare> watcher for this task.
+and start an C<EV::prepare> watcher for this task.
 It must return the next time to trigger, based on the passed time value
 (that is, the lowest time value larger than or equal to to the second
 argument). It will usually be called just before the callback will be
 triggered, but might be called at other times, too.
 This can be used to create very complex timers, such as a timer that
-triggers on each midnight, local time (actually 24 hours after the last
+triggers on each midnight, local time (actually one day after the last
-midnight, to keep the example simple. If you know a way to do it correctly
+midnight, to keep the example simple):
-in about the same space (without requiring elaborate modules), drop me a
-note :):
    my $daily = EV::periodic 0, 0, sub {
       my ($w, $now) = @_;
       use Time::Local ();
       my (undef, undef, undef, $d, $m, $y) = localtime $now;
-      86400 + Time::Local::timelocal 0, 0, 0, $d, $m, $y
+      Time::Local::timelocal_nocheck 0, 0, 0, $d + 1, $m, $y
    }, sub {
       print "it's midnight or likely shortly after, now\n";
    };
 =back
 =item $w = EV::async $callback
 =item $w = EV::async_ns $callback
+=item $w = $loop->async ($callback)
+=item $w = $loop->async_ns ($callback)
 =item $w->send
 =item $bool = $w->async_pending
 =back
+=head3 CLEANUP WATCHERS - how to clean up when the event loop goes away
+Cleanup watchers are not supported on the Perl level, they can only be
+used via XS currently.
 =head1 PERL SIGNALS
 While Perl signal handling (C<%SIG>) is not affected by EV, the behaviour

Diff Legend

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

Comparing EV/EV.pm (file contents): Revision 1.136 by root, Thu Jan 19 17:55:23 2012 UTC vs. Revision 1.155 by root, Sun May 12 21:58:31 2019 UTC

Diff Legend

Comparing EV/EV.pm (file contents):
Revision 1.136 by root, Thu Jan 19 17:55:23 2012 UTC vs.
Revision 1.155 by root, Sun May 12 21:58:31 2019 UTC