EV#

📦 max

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#

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 - 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 - A child process watcher, as EV::child makes: its callback runs when a child ends (or, traced, stops or continues).

  • EV::Embed - An embed watcher, as EV::embed makes: it lets running one loop also serve another loop’s I/O.

  • EV::IO - An I/O watcher, as EV::io makes: its callback runs when a file handle is readable or writable.

  • 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 - 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 - A signal watcher, as EV::signal makes: its callback runs when the process receives a signal.

  • 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 - A relative timer, as EV::timer makes: its callback runs after a number of seconds, and optionally again at a repeat interval.

  • 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#

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#

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

Also available as EV::io_ns.

timer#

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

Also available as EV::timer_ns.

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#

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.

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.