view release on metacpan or  search on metacpan

EV.pm  view on Meta::CPAN

Returns the time the last event loop iteration has been started. This
is the time that (relative) timers are based on, and referring to it is
usually faster then calling EV::time.

=item EV::now_update

=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::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 EV::suspend

=item $loop->suspend

=item EV::resume

=item $loop->resume

These two functions suspend and resume a loop, for use when the loop is
not used for a while and timeouts should not be processed.

A typical use case would be an interactive program such as a game:  When
the user presses C<^Z> to suspend the game and resumes it an hour later it
would be best to handle timeouts as if no time had actually passed while
the program was suspended. This can be achieved by calling C<suspend>
in your C<SIGTSTP> handler, sending yourself a C<SIGSTOP> and calling
C<resume> directly afterwards to resume timer processing.

Effectively, all C<timer> watchers will be delayed by the time spend
between C<suspend> and C<resume>, and all C<periodic> watchers
will be rescheduled (that is, they will lose any events that would have
occured while suspended).

After calling C<suspend> you B<must not> call I<any> function on the given
loop other than C<resume>, and you B<must not> call C<resume>
without a previous call to C<suspend>.

Calling C<suspend>/C<resume> has the side effect of updating the event
loop time (see C<now_update>).

=item $backend = EV::backend

=item $backend = $loop->backend

Returns an integer describing the backend used by libev (EV::BACKEND_SELECT
or EV::BACKEND_EPOLL).

=item $active = EV::run [$flags]

=item $active = $loop->run ([$flags])

Begin checking for events and calling callbacks. It returns when a
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)
   EV::RUN_NOWAIT  do not block at all (fetch/handle events but do not wait)

=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::run return.

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.

=item $count = EV::iteration

=item $count = $loop->iteration

Return the number of times the event loop has polled for new
events. Sometimes useful as a generation counter.

=item EV::once $fh_or_undef, $events, $timeout, $cb->($revents)

=item $loop->once ($fh_or_undef, $events, $timeout, $cb->($revents))

This function rolls together an I/O and a timer watcher for a single
one-shot event without the need for managing a watcher object.

If C<$fh_or_undef> is a filehandle or file descriptor, then C<$events>
must be a bitset containing either C<EV::READ>, C<EV::WRITE> or C<EV::READ
| 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 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>).

EV::once doesn't return anything: the watchers stay active till either
of them triggers, then they will be stopped and freed, and the callback
invoked.

=item EV::feed_fd_event $fd, $revents

=item $loop->feed_fd_event ($fd, $revents)

Feed an event on a file descriptor into EV. EV will react to this call as
if the readyness notifications specified by C<$revents> (a combination of

EV.pm  view on Meta::CPAN

=item $w->stop

Stop a watcher if it is active. Also clear any pending events (events that
have been received but that didn't yet result in a callback invocation),
regardless of whether the watcher was active or not.

=item $bool = $w->is_active

Returns true if the watcher is active, false otherwise.

=item $current_data = $w->data

=item $old_data = $w->data ($new_data)

Queries a freely usable data scalar on the watcher and optionally changes
it. This is a way to associate custom data with a watcher:

   my $w = EV::timer 60, 0, sub {
      warn $_[0]->data;
   };
   $w->data ("print me!");

=item $current_cb = $w->cb

=item $old_cb = $w->cb ($new_cb)

Queries the callback on the watcher and optionally changes it. You can do
this at any time without the watcher restarting.

=item $current_priority = $w->priority

=item $old_priority = $w->priority ($new_priority)

Queries the priority on the watcher and optionally changes it. Pending
watchers with higher priority will be invoked first. The valid range of
priorities lies between EV::MAXPRI (default 2) and EV::MINPRI (default
-2). If the priority is outside this range it will automatically be
normalised to the nearest valid priority.

The default priority of any newly-created watcher is 0.

Note that the priority semantics have not yet been fleshed out and are
subject to almost certain change.

=item $w->invoke ($revents)

Call the callback *now* with the given event mask.

=item $w->feed_event ($revents)

Feed some events on this watcher into EV. EV will react to this call as if
the watcher had received the given C<$revents> mask.

=item $revents = $w->clear_pending

If the watcher is pending, this function clears its pending status and
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::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::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::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::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::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
event loop from running just because of that watcher.

   my $udp_socket = ...
   my $udp_watcher = EV::io $udp_socket, EV::READ, sub { ... };
   $udp_watcher->keepalive (0);

=item $loop = $w->loop

Return the loop that this watcher is attached to.

=back


=head1 WATCHER TYPES

Each of the following subsections describes a single watcher type.

=head3 I/O WATCHERS - is this file descriptor readable or writable?

=over 4

=item $w = EV::io $fileno_or_fh, $eventmask, $callback

=item $w = EV::io_ns $fileno_or_fh, $eventmask, $callback

=item $w = $loop->io ($fileno_or_fh, $eventmask, $callback)

=item $w = $loop->io_ns ($fileno_or_fh, $eventmask, $callback)

As long as the returned watcher object is alive, call the C<$callback>
when at least one of events specified in C<$eventmask> occurs.

The $eventmask can be one or more of these constants ORed together:

  EV::READ     wait until read() wouldn't block anymore
  EV::WRITE    wait until write() wouldn't block anymore

The C<io_ns> variant doesn't start (activate) the newly created watcher.

=item $w->set ($fileno_or_fh, $eventmask)

Reconfigures the watcher, see the constructor above for details. Can be
called at any time.

=item $current_fh = $w->fh

=item $old_fh = $w->fh ($new_fh)

Returns the previously set filehandle and optionally set a new one.

=item $current_eventmask = $w->events

=item $old_eventmask = $w->events ($new_eventmask)

Returns the previously set event mask and optionally set a new one.

=back


=head3 TIMER WATCHERS - relative and optionally repeating timeouts

=over 4

=item $w = EV::timer $after, $repeat, $callback

=item $w = EV::timer_ns $after, $repeat, $callback

=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 or
negative). If C<$repeat> is non-zero, the timer will be restarted (with
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,
look at EV::periodic, which can provide long-term stable timers.

The timer is based on a monotonic clock, that is, if somebody is sitting
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 = 0)

Reconfigures the watcher, see the constructor above for details. Can be called at