Event::Watcher#

📦 max

The base class of every watcher: the methods and attributes all watcher types share. A watcher is made by its type’s constructor (Event->timer(...), Event::io->new(...), …; see Event), lives on without a reference being kept to it, and is switched between active and inactive with start and stop. When the condition it watches occurs, an active watcher queues an event at its priority, and the loop passes that event to its callback.

Every attribute is a method: called with no argument it returns the value, called with one it sets the value and returns it. Constructors take the same attributes as name => value pairs.

Methods written in Perl#

Event::Watcher (from Event/Watcher.pm) also has:

  • $w->attributes - the names of the watcher’s attributes, its own type’s followed by those of its base classes.

  • $w->configure - with no arguments, a list of name => value pairs of all attributes; with pairs, sets them.

  • $w->data / $w->data($anything) - one slot for the user’s own data.

  • $w->private / $w->private($anything) - like data, but each calling package has its own slot; meant for the implementers of watcher types and subclasses.

  • Event::Watcher->register - called by a watcher type’s module to make Event->TYPE(...) construct it.

  • $w->init(\%attributes) - the common half of every constructor: sets the priority (from the type’s $DefaultPriority and the nice, async and prio attributes), every attribute the watcher has a method for, a desc naming the caller’s file and line if none was given, and starts the watcher unless parked is true.

Constants#

Exported on request (use Event::Watcher qw(R W E T)):

  • R (1), W (2), E (4), T (8) - the read, write, exception and timeout bits of poll and got.

  • ACTIVE (1), SUSPEND (4) - bits of Event::Watcher::Tied’s flags.

Modules#

Functions#

Activity#

again#

Like start, except for watchers that repeat in a special way: a repeating timer computes its next expiry from interval.

start#

Activate the watcher; an active watcher does nothing. A watcher that lacks what it needs to generate events refuses with “Event: can’t start ‘DESC’ REASON” - for instance a watcher without a callback (“without callback”), or a repeating timer without interval. Constructors call start unless given parked => 1.

suspend#

$w->suspend(1) suspends the watcher, $w->suspend(0) lifts the suspension. A suspended watcher generates no events and its queued events are cancelled, but it stays active; suspension is a debugging aid. Called without an argument it suspends, warns “Ambiguous use of suspend” and returns true.

resume#

Deprecated: the same as suspend(0), with a warning saying so.

stop#

Deactivate the watcher. A running callback completes; queued events are cancelled. start or again activates it again.

cancel#

Stop the watcher and destroy it. A running callback completes; queued events are cancelled. A cancelled watcher answers its read-only methods (prio, desc, …) but can no longer be started.

now#

Generate an event now, even if the watcher is stopped (but not if it is suspended). The event is queued at the watcher’s priority like any other, so the callback runs when the loop reaches it. Dies if the watcher has no callback.

State#

pending#

The watcher’s events waiting in the queue. In list context, the events themselves; in scalar context, true if there is any.

is_running#

0 when the callback is not running, otherwise how many times it has been entered - more than 1 when a reentrant callback runs loop or sweep itself.

is_active#

True if the watcher is started. Suspension does not change it.

is_suspended#

True if the watcher is suspended (see suspend).

is_cancelled#

True if the watcher is cancelled.

Attributes#

use_keys#

Deprecated; does nothing but warn “use_keys is deprecated”.

cb#

The callback: a code reference, or [$class_or_object, $method_name] to call a method. It is called with the event as its only argument. Anything else dies “Callback must be a code ref or [$object, $method_name]”; a method that does not exist yet only warns. Setting undef removes the callback and stops the watcher.

cbtime#

When the callback was last called, in the units of Event::time. Read-only: setting it dies.

desc#

A name for the watcher, used in diagnostics. Constructors set it to ?? FILE:LINE of their caller when none is given.

debug#

Debugging for this watcher. Stored and returned, but without effect: its per-watcher diagnostics exist only when Event is built with debugging, which a standard build of the module, like this one, is not.

prio#

The priority its events are queued at, -1 (highest) to 6 (lowest); see Event.

reentrant#

Whether the callback may be entered again while it runs, which happens when it calls loop or sweep. True by default; when false the watcher is suspended during such nested calls. It cannot be turned off while the callback is already entered more than once.

repeat#

Whether the watcher stays active after an event; when false it stops after one. The default depends on the type: io, signal, var, group and generic watchers repeat; timers and idle watchers repeat when given interval, or min or max.

max_cb_tm#

The most seconds a callback may run, an integer, 1 by default. It takes effect only with the statistics Event::Stats installs; otherwise it is recorded and not enforced. A value Perl does not hold as an integer - the string "5", the number 2.5 - sets 0.