```{index} single: Event::Watcher ``` # Event::Watcher ```{pperl-module-badges} Event::Watcher ``` 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 - [`Event::Watcher::Tied`](Watcher/Tied) - The base class for watcher types written in Perl. ## 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. ```{toctree} :hidden: :maxdepth: 1 Watcher/Tied ```