<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from EV/Watcher.rs. Do not edit. -->

```{index} single: EV::Watcher
```

# EV::Watcher

```{pperl-module-badges} EV::Watcher
```

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

```perl
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`](Watcher/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.

```{toctree}
:hidden:
:maxdepth: 1

Watcher/keepalive
```