EV
view release on metacpan or search on metacpan
EV::sleep $seconds
Block the process for the given number of (fractional) seconds.
$time = EV::time
Returns the current time in (fractional) seconds since the epoch.
$time = EV::now
$time = $loop->now
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.
EV::now_update
$loop->now_update
Establishes the current time by querying the kernel, updating the
time returned by "EV::now" in the progress. This is a costly
operation and is usually done automatically within "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.
EV::suspend
$loop->suspend
EV::resume
$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 "^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 "suspend" in your "SIGTSTP" handler, sending
yourself a "SIGSTOP" and calling "resume" directly afterwards to
resume timer processing.
Effectively, all "timer" watchers will be delayed by the time spend
between "suspend" and "resume", and all "periodic" watchers will be
rescheduled (that is, they will lose any events that would have
occured while suspended).
After calling "suspend" you must not call *any* function on the
given loop other than "resume", and you must not call "resume"
without a previous call to "suspend".
Calling "suspend"/"resume" has the side effect of updating the event
loop time (see "now_update").
$backend = EV::backend
$backend = $loop->backend
Returns an integer describing the backend used by libev
(EV::BACKEND_SELECT or EV::BACKEND_EPOLL).
$active = EV::run [$flags]
$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)
EV::break [$how]
$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.
$count = EV::iteration
$count = $loop->iteration
Return the number of times the event loop has polled for new events.
Sometimes useful as a generation counter.
EV::once $fh_or_undef, $events, $timeout, $cb->($revents)
$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 $fh_or_undef is a filehandle or file descriptor, then $events
must be a bitset containing either "EV::READ", "EV::WRITE" or
"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
"undef" for $fh_or_undef and 0 for $events).
If timeout is "undef" or negative, then there will be no timeout.
Otherwise an "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 "EV::ERROR",
"EV::READ", "EV::WRITE" and "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.
EV::feed_fd_event $fd, $revents
$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 $revents (a
combination of "EV::READ" and "EV::WRITE") happened on the file
descriptor $fd.
EV::feed_signal_event $signal
Feed a signal event into the default loop. EV will react to this
call as if the signal specified by $signal had occured.
EV::feed_signal $signal
which means pending events get lost.
COMMON WATCHER METHODS
This section lists methods common to all watchers.
$w->start
Starts a watcher if it isn't active already. Does nothing to an
already active watcher. By default, all watchers start out in the
active state (see the description of the "_ns" variants if you need
stopped watchers).
$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.
$bool = $w->is_active
Returns true if the watcher is active, false otherwise.
$current_data = $w->data
$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!");
$current_cb = $w->cb
$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.
$current_priority = $w->priority
$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.
$w->invoke ($revents)
Call the callback *now* with the given event mask.
$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 $revents mask.
$revents = $w->clear_pending
If the watcher is pending, this function clears its pending status
and returns its $revents bitset (as if its callback was invoked). If
the watcher isn't pending it does nothing and returns 0.
$previous_state = $w->keepalive ($bool)
Normally, "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 "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 "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
"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 "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);
$loop = $w->loop
Return the loop that this watcher is attached to.
WATCHER TYPES
Each of the following subsections describes a single watcher type.
I/O WATCHERS - is this file descriptor readable or writable?
$w = EV::io $fileno_or_fh, $eventmask, $callback
$w = EV::io_ns $fileno_or_fh, $eventmask, $callback
$w = $loop->io ($fileno_or_fh, $eventmask, $callback)
$w = $loop->io_ns ($fileno_or_fh, $eventmask, $callback)
As long as the returned watcher object is alive, call the $callback
when at least one of events specified in $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 "io_ns" variant doesn't start (activate) the newly created
watcher.
$w->set ($fileno_or_fh, $eventmask)
Reconfigures the watcher, see the constructor above for details. Can
be called at any time.
$current_fh = $w->fh
$old_fh = $w->fh ($new_fh)
Returns the previously set filehandle and optionally set a new one.
$current_eventmask = $w->events
$old_eventmask = $w->events ($new_eventmask)
Returns the previously set event mask and optionally set a new one.
TIMER WATCHERS - relative and optionally repeating timeouts
$w = EV::timer $after, $repeat, $callback
$w = EV::timer_ns $after, $repeat, $callback
$w = $loop->timer ($after, $repeat, $callback)
$w = $loop->timer_ns ($after, $repeat, $callback)
Calls the callback after $after seconds (which may be fractional or
negative). If $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 $after
seconds, and then every $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 "timer_ns" variant doesn't start (activate) the newly created
watcher.
$w->set ($after, $repeat = 0)
Reconfigures the watcher, see the constructor above for details. Can
be called at any time.
$w->again
$w->again ($repeat)
Similar to the "start" method, but has special semantics for
repeating timers:
If the timer is active and non-repeating, it will be stopped.
If the timer is active and repeating, reset the timeout to occur
$repeat seconds after now.
( run in 0.921 second using v1.01-cache-2.11-cpan-39bf76dae61 )