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

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

# EV

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

A fast, full-featured event loop: call your code when a file handle is
readable or writable, a timer expires, a signal arrives, a child
process changes state or a file changes.

You create watchers - objects recording your interest in an event -
and then run the loop, which waits for events and calls each watcher's
callback. `EV::io`, `EV::timer`, `EV::periodic`, `EV::signal`,
`EV::child`, `EV::stat`, `EV::idle`, `EV::prepare`, `EV::check`,
`EV::fork`, `EV::embed` and `EV::async` create watchers on the default
loop; `EV::run` runs it. A program needing more than one loop makes
more with `EV::Loop->new`, which has the same functions as methods.


## Synopsis

```perl
use EV;

my $once  = EV::timer 2, 0, sub { warn "2 seconds passed\n" };
my $every = EV::timer 0, 3, sub { warn "now, then every 3 seconds\n" };
my $input = EV::io *STDIN, EV::READ, sub {
    my ($w, $revents) = @_;            # every callback gets these two
    warn "you typed: ", scalar <STDIN>;
};
my $quit  = EV::signal 'QUIT', sub { EV::break };

EV::run;    # until EV::break, or no active watcher is left
```

## Watchers

A watcher stays alive as long as the object its constructor returned
does: keep it in a variable, and `undef` it to stop and free the
watcher. Every callback is called with the watcher and a bitmask of
the events received (`EV::READ`, `EV::TIMER` and the like), so one
sub can serve several watchers.

Every constructor starts the watcher; its `_ns` twin (`EV::io_ns`,
`EV::timer_ns` ...) creates it stopped, for a later `start`. The
methods all watchers share - `start`, `stop`, `is_active`, `data`,
`cb`, `priority`, `keepalive` and more - are `EV::Watcher`'s; each
watcher class (`EV::IO`, `EV::Timer`, `EV::Periodic`, `EV::Signal`,
`EV::Child`, `EV::Stat`, `EV::Embed`, `EV::Async`) adds its own.
Changing a running watcher (`set`, `priority`, `fh` ...) stops and
restarts it, losing events pending for it. `EV::idle`, `EV::prepare`,
`EV::check` and `EV::fork` watchers have only the shared methods.

An exception thrown by a callback does not end the loop: EV calls
`$EV::DIED` with the error in `$@`, which by default warns
`EV: error in callback (ignoring): ...` and goes on.

## Priorities

A watcher's priority, from `EV::MINPRI` (-2) to `EV::MAXPRI` (2),
decides which of several pending watchers runs first; new watchers
have priority 0. An idle watcher runs only when nothing of its
priority or higher is pending.

## Constants

Called as functions (`EV::READ`), as EV exports nothing:

- Events: `EV::READ`, `EV::WRITE`, `EV::TIMER`, `EV::PERIODIC`,
  `EV::SIGNAL`, `EV::CHILD`, `EV::STAT`, `EV::IDLE`, `EV::PREPARE`,
  `EV::CHECK`, `EV::EMBED`, `EV::FORK`, `EV::CLEANUP`, `EV::ASYNC`,
  `EV::CUSTOM`, `EV::ERROR`, `EV::IO`, `EV::NONE`, `EV::UNDEF`.
- `EV::run` flags `EV::RUN_NOWAIT`, `EV::RUN_ONCE`; `EV::break` modes
  `EV::BREAK_ONE`, `EV::BREAK_ALL`, `EV::BREAK_CANCEL`.
- Backends `EV::BACKEND_SELECT`, `EV::BACKEND_POLL`,
  `EV::BACKEND_EPOLL`, `EV::BACKEND_KQUEUE`, `EV::BACKEND_DEVPOLL`,
  `EV::BACKEND_PORT`, `EV::BACKEND_ALL`, `EV::BACKEND_MASK`, and loop
  flags `EV::FLAG_AUTO`, `EV::FLAG_FORKCHECK`, `EV::FLAG_SIGNALFD`,
  `EV::FLAG_NOSIGMASK`, `EV::FLAG_NOENV`, `EV::FLAG_NOINOTIFY`.
- `EV::MINPRI`, `EV::MAXPRI`; `EV::VERSION_MAJOR`, `EV::VERSION_MINOR`
  (of libev).
- The names of EV 3 kept for old programs: `EV::TIMEOUT`,
  `EV::LOOP_NONBLOCK`, `EV::LOOP_ONESHOT`, `EV::UNLOOP_CANCEL`,
  `EV::UNLOOP_ONE`, `EV::UNLOOP_ALL`, `EV::FLAG_NOSIGFD` (0).

`EV::CHECK` shares its name with Perl's `CHECK` blocks: write it
after `use EV`, where it is compiled as the constant.

## Backends

The default loop waits with epoll. select, poll, Linux AIO and
io_uring are there too, to choose with `EV::Loop->new` flags or the
`LIBEV_FLAGS` environment variable (the backend bits added together).
`EV::supported_backends` lists them. File status watchers use inotify
where it works.

## Signals and fork

Perl's own `%SIG` handlers run only when Perl runs, which in an event
loop may be late: use `EV::signal` watchers instead, or keep an
`EV::check` watcher (`my $c = EV::check sub {}`) so that Perl gets
control on every loop iteration.

After `fork`, the child's default loop is reset for it automatically
the next time it is used. Loops made with `EV::Loop->new` need
`$loop->loop_fork` in the child, or the flag `EV::FLAG_FORKCHECK`.

`$EV::API` holds the C function table EV gives modules such as
`Coro::EV` that drive the loop from compiled code.

## Differences from upstream

- `EV::signal` (and `EV::Loop->signal`, `$w->signal`) take the second
  names of signals, `IOT`, `CLD` and `POLL`, as the signals they name;
  upstream takes them for nonexistent signal numbers 65 to 67 and
  corrupts its memory. A number that is no signal is refused with
  `illegal signal number or name`. Covered by
  `t/81-xs-native/EV/310-signal-alias.t`.
- `EV::Periodic->reschedule_cb` keeps its callback and the watcher
  alive; upstream frees them early. See `EV::Periodic`.

Everything else behaves as with EV 4.37 and the libev 4.33 it bundles.
Covered by EV's own test suite, `t/81-xs-native/EV/100-upstream-00_load.t`
to `200-upstream-11_signal.t`.

## Modules

- [`EV::Async`](EV/Async) - An async watcher, as `EV::async` makes: anything may trigger it with `send`, and its callback then runs in its loop - the way compiled code or another loop wakes a loop that is waiting.
- [`EV::Child`](EV/Child) - A child process watcher, as `EV::child` makes: its callback runs when a child ends (or, traced, stops or continues).
- [`EV::Embed`](EV/Embed) - An embed watcher, as `EV::embed` makes: it lets running one loop also serve another loop's I/O.
- [`EV::IO`](EV/IO) - An I/O watcher, as `EV::io` makes: its callback runs when a file handle is readable or writable.
- [`EV::Loop`](EV/Loop) - An event loop of your own, beside the default one: `EV::Loop->new` makes one, and `EV::default_loop` returns the default loop as an `EV::Loop` too.
- [`EV::Periodic`](EV/Periodic) - A wall-clock timer, as `EV::periodic` makes: its callback runs at a given time, at every multiple of an interval, or whenever a reschedule sub says - see `EV::periodic` for the three modes.
- [`EV::Signal`](EV/Signal) - A signal watcher, as `EV::signal` makes: its callback runs when the process receives a signal.
- [`EV::Stat`](EV/Stat) - A file status watcher, as `EV::stat` makes: its callback runs when a path's status changes - created, deleted, written, its permissions or times changed.
- [`EV::Timer`](EV/Timer) - A relative timer, as `EV::timer` makes: its callback runs after a number of seconds, and optionally again at a repeat interval.
- [`EV::Watcher`](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.

## Functions

### Running the loop

#### `default_loop`

The default loop, as an `EV::Loop` object: the one the `EV::` functions and watchers use, and the only one that can watch signals and child processes. EV creates it when loaded, so the optional flags (`EV::FLAG_*`, `EV::BACKEND_*` bits) matter only to a call after `EV::default_destroy`, which creates it again. Undef when the loop cannot be created.

#### `default_destroy`

Destroy the default loop, with every watcher on it. Nothing may use it until `EV::default_loop` creates a new one; watcher objects made on the old one must not be used again. Rarely wanted: a program ending need not call it.

#### `iteration`

How many times the loop has waited for events - a generation counter. `EV::loop_count` is its old name.

Also available as `EV::loop_count`.

#### `depth`

How many `EV::run` calls are in progress: 0 outside the loop, 1 in a callback, more when a callback runs the loop itself. `EV::loop_depth` is its old name.

Also available as `EV::loop_depth`.

#### [`loop`](EV/loop)

Run the event loop: wait for events and call the watchers' callbacks.

Also available as `EV::run`.

#### `break`

Make `EV::run` return once the current callbacks are done: the innermost call with `EV::break` or `EV::break EV::BREAK_ONE`, all of them with `EV::BREAK_ALL`; `EV::BREAK_CANCEL` withdraws a break not yet acted on. `EV::unloop` is the old name.

Also available as `EV::unloop`.

### Watchers

#### [`io`](EV/io)

Watch a file handle: call the callback whenever it is readable or writable without blocking.

Also available as `EV::io_ns`.

#### [`timer`](EV/timer)

Call the callback after a number of seconds, and optionally again and again after that.

Also available as `EV::timer_ns`.

#### [`periodic`](EV/periodic)

Call the callback at wall-clock times: once at a given time, at every multiple of an interval, or whenever a sub of yours says.

Also available as `EV::periodic_ns`.

#### `signal`

Call the callback when a signal arrives: `my $w = EV::signal 'HUP', sub { ... }`. The signal is a name or number, as for `kill` and `%SIG`. EV takes the signal from Perl while the watcher is active, and gives it back when stopped; any number of watchers may watch one signal, but only one loop - starting one in a second loop croaks `unable to start signal watcher, signal N already registered in another loop`. A name or number that is no signal croaks `illegal signal number or name`. `EV::signal_ns` creates it stopped. The second names `IOT`, `CLD` and `POLL` work, as `ABRT`, `CHLD` and `IO`, which upstream does not do (covered by `t/81-xs-native/EV/310-signal-alias.t`).

Also available as `EV::signal_ns`.

#### `idle`

Call the callback whenever the loop has nothing more urgent to do: `my $w = EV::idle sub { ... }`. It runs when no watcher of its priority or higher is pending, and while it is active the loop does not block - it is called again and again until stopped. At priority `EV::MINPRI` it runs only when nothing else is pending. `EV::idle_ns` creates it stopped.

Also available as `EV::idle_ns`.

#### `prepare`

Call the callback just before the loop blocks to wait: `my $w = EV::prepare sub { ... }`. Watchers can still be created and changed in it - a prepare watcher can set up the I/O and timer watchers another event library needs, and an `EV::check` watcher clean them up. `EV::prepare_ns` creates it stopped.

Also available as `EV::prepare_ns`.

#### `check`

Call the callback just after the loop wakes up, before any other callback: `my $w = EV::check sub { ... }`. The partner of `EV::prepare`; an empty one also lets Perl's own `%SIG` handlers run on every iteration. `EV::check_ns` creates it stopped. Write the event constant `EV::CHECK` after `use EV`.

Also available as `EV::check_ns`.

#### `fork`

Call the callback in a child process after `fork`, before its event loop next blocks: `my $w = EV::fork sub { ... }`. `EV::fork_ns` creates it stopped.

Also available as `EV::fork_ns`.

#### `child`

Call the callback when a child process ends: `my $w = EV::child $pid, 0, sub { my ($w) = @_; my $status = $w->rstatus; ... }`. A `$pid` of 0 watches every child; a true `$trace` also reports a child stopping and continuing. EV reaps the child, so its exit status is `$w->rstatus` (as `$?` would be) and its pid `$w->rpid`. The watcher may be made after the child has already exited, as long as the loop has not run since. Only the default loop watches children. `EV::child_ns` creates it stopped.

Also available as `EV::child_ns`.

#### `stat`

Call the callback when a file's status changes - its size, times, permissions, or whether it exists: `my $w = EV::stat '/etc/passwd', 0, sub { ... }`. The path need not exist. Changes come from inotify where it works, else from polling every `$interval` seconds (0: about five seconds, recommended). The watcher's `attr` and `prev` give the status after and before the change. Not meant for thousands of files. `EV::stat_ns` creates it stopped.

Also available as `EV::stat_ns`.

#### `embed`

Embed another loop in the default loop: running the default loop then also handles the other loop's I/O. `my $w = EV::embed $other_loop`. Without a callback the embedded loop is serviced automatically (the recommended way); with one, the callback is called when the other loop has I/O pending and must call `$w->sweep`. Only I/O watchers of the embedded loop are served reliably, and only a loop using one of `EV::embeddable_backends` can be embedded - another croaks `passed loop is not embeddable via EV::embed`. `EV::embed_ns` creates it stopped.

Also available as `EV::embed_ns`.

#### `async`

Create a watcher another thread of control wakes the loop with: `my $w = EV::async sub { ... }`, triggered by `$w->send`. Of little use from Perl itself; compiled code (and `Coro`) uses it to wake a waiting loop. `EV::async_ns` creates it stopped. See `EV::Async`.

Also available as `EV::async_ns`.

#### [`once`](EV/once)

Wait once for a handle to become ready, a timeout, or the first of the two, without keeping a watcher object.

### Time

#### `sleep`

Block the whole process for a number of seconds, which may be fractional: `EV::sleep 0.25`. No watcher runs meanwhile.

#### `time`

The current time, in fractional seconds since the epoch, asked of the system now. `EV::now` is cheaper where the loop's time will do.

#### `now`

The time the current loop iteration began, in fractional seconds since the epoch: the time relative timers count from, and cheaper than `EV::time`.

#### `now_update`

Set the loop's idea of the time (`EV::now`) to the time now. The loop does this every iteration; a callback that runs for a long time before starting timers should do it first, or the timers start late.

#### `suspend`

Pause the loop's clock, for a program that stops for a while (a game put in the background with `^Z`): between `EV::suspend` and `EV::resume`, timers do not run down, and periodic watchers skip what they would have fired. After `EV::suspend` call nothing on the loop but `EV::resume`.

#### `resume`

Restart the loop's clock after `EV::suspend`; only after it.

### Events

#### `feed_signal`

Act as if a signal had arrived, whichever loop watches it: `EV::feed_signal 'USR1'`. The signal is a name or number, as for `kill`. For handing EV signals caught some other way.

#### `feed_fd_event`

Act as if a file descriptor had become ready: `EV::feed_fd_event $fd, EV::READ` makes the I/O watchers on `$fd` that wait for those events pending.

#### `feed_signal_event`

Act as if a signal had arrived at the default loop: `EV::feed_signal_event 'HUP'` makes its watchers of that signal pending. A name or number, as for `kill`; one that is no signal croaks `illegal signal number or name`.

#### `pending_count`

How many watchers have received events whose callbacks have not run yet.

#### `invoke_pending`

Call the callbacks of all pending watchers now.

### Backends and tuning

#### `supported_backends`

The backends this EV can use, as `EV::BACKEND_*` bits: select, poll, epoll, Linux AIO and io_uring.

#### `recommended_backends`

The backends recommended on this system, as `EV::BACKEND_*` bits.

#### `embeddable_backends`

The backends a loop can use and still be embedded in another with `EV::embed`, as `EV::BACKEND_*` bits.

#### `backend`

The backend the default loop waits with, one `EV::BACKEND_*` bit - `EV::BACKEND_EPOLL` unless chosen otherwise.

#### `loop_verify`

Check the loop's internal data for consistency, aborting the program if it is corrupt - for debugging. `EV::loop_verify` is its old name.

Also available as `EV::verify`.

#### `set_io_collect_interval`

Make the loop wait at least this many seconds between polls for I/O, collecting more events per wakeup - fewer, larger batches for a busy server, at the cost of latency. 0, the default, waits no longer than needed.

#### `set_timeout_collect_interval`

Let timers that expire within this many seconds of each other fire in one wakeup, trading timer precision for fewer wakeups. 0, the default, fires each on time.

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

EV/Async
EV/Child
EV/Embed
EV/IO
EV/Loop
EV/Periodic
EV/Signal
EV/Stat
EV/Timer
EV/Watcher
EV/loop
EV/io
EV/timer
EV/periodic
EV/once
```