EV::Watcher#

📦 max

The methods every EV watcher has: start and stop it, ask whether it is active or pending, change its callback, data and priority, and decide whether it keeps the loop running.

Every watcher class - EV::IO, EV::Timer, EV::Periodic, EV::Signal, EV::Child, EV::Stat, EV::Idle, EV::Prepare, EV::Check, EV::Fork, EV::Embed, EV::Async - inherits these. Each class also has these two, with the same meaning everywhere:

  • $w->start - start the watcher if it is not active; an active one is left as it is. Watchers start active, except those an _ns constructor made.

  • $w->stop - stop the watcher if it is active, and in any case drop the events received for it whose callback has not run yet.

A watcher is stopped and freed when its last reference goes. A callback is called with the watcher and the events it received; the watcher can be stopped, changed or dropped from inside its own callback.

Synopsis#

my $w = EV::timer 60, 0, sub { my ($w) = @_; warn $w->data };
$w->data('time is up');
$w->priority(1);                # before other pending watchers
$w->keepalive(0);               # EV::run may return while it waits
$w->stop;
$w->start if !$w->is_active;

Functions#

State#

is_active#

True while the watcher is active - started and not stopped.

is_pending#

True while the watcher has received events whose callback has not run yet.

keepalive#

Whether the active watcher keeps EV::run from returning, and with an argument set it; returns the setting before, 1 or 0.

loop#

The EV::Loop the watcher belongs to.

priority#

The watcher’s priority, from EV::MINPRI (-2) to EV::MAXPRI (2); with an argument, set a new one and return the old. Of the watchers pending at once, those of higher priority are called first. New watchers have priority 0; a value out of range is brought into it when the watcher starts. Setting it on an active watcher stops and restarts it, losing its pending events.

Callback and data#

cb#

The watcher’s callback, as a code reference; with an argument, set a new one and return the old. The watcher is not restarted: the change can be made at any time, even from inside the callback. Something that is no code reference croaks.

data#

A scalar of your own stored in the watcher, undef at first; with an argument, store a new one and return the old. The callback finds it as $_[0]->data.

Events#

invoke#

Call the watcher’s callback now, with the events given (default EV::NONE): $w->invoke(EV::TIMER).

clear_pending#

Drop the events the watcher received whose callback has not run, and return them as a bitmask - as if the callback had run; 0 when nothing was pending.

feed_event#

Act as if the watcher had received events: $w->feed_event(EV::READ) makes it pending, and its callback runs in the loop’s next round.