wok annotate perl-event/description.txt @ rev 25037

Up glza (0.11.4)
author Pascal Bellard <pascal.bellard@slitaz.org>
date Sat May 21 21:38:29 2022 +0000 (2022-05-21)
parents
children
rev   line source
Hans-G?nter@24202 1 The Event module provides a central facility to watch for various types
Hans-G?nter@24202 2 of events and invokes a callback when these events occur.
Hans-G?nter@24202 3 The idea is to delay the handling of events so that they may be dispatched
Hans-G?nter@24202 4 in priority order when it is safe for callbacks to execute.
Hans-G?nter@24202 5
Hans-G?nter@24202 6 Events (in the ordinary sense of the word) are detected by watchers, which
Hans-G?nter@24202 7 reify them as events (in the special Event module sense). For clarity, the
Hans-G?nter@24202 8 former type of events may be called "source events", and the latter
Hans-G?nter@24202 9 "target events".
Hans-G?nter@24202 10 Source events, such as signals arriving, happen whether or not they are
Hans-G?nter@24202 11 being watched. If a source event occurs which a watcher is actively watching
Hans-G?nter@24202 12 then the watcher generates a corresponding target event.
Hans-G?nter@24202 13 Target events are only created by watchers.
Hans-G?nter@24202 14 If several watchers are interested in the same source event then each will
Hans-G?nter@24202 15 generate their own target event. Hence, any particular source event may
Hans-G?nter@24202 16 result in zero, one, two, or any number of target events: the same as the
Hans-G?nter@24202 17 number of watchers which were actively watching for it.
Hans-G?nter@24202 18
Hans-G?nter@24202 19 Target events are queued to be processed in priority order (priority being
Hans-G?nter@24202 20 determined by the creating watcher) and in FIFO order among events of the
Hans-G?nter@24202 21 same priority.
Hans-G?nter@24202 22 Queued ("pending") events can, in some cases, be cancelled before being
Hans-G?nter@24202 23 processed. A queued event is processed by being passed to the callback
Hans-G?nter@24202 24 function (or method on a particular object or class) which was specified
Hans-G?nter@24202 25 to the watcher.
Hans-G?nter@24202 26
Hans-G?nter@24202 27 A watcher, once created, operates autonomously without the Event user
Hans-G?nter@24202 28 having to retain any reference to it. However, keeping a reference makes
Hans-G?nter@24202 29 it possible to modify most of the watcher's characteristics.
Hans-G?nter@24202 30 A watcher can be switched between active and inactive states.
Hans-G?nter@24202 31 When inactive, it does not generate target events.
Hans-G?nter@24202 32
Hans-G?nter@24202 33 Some types of source event are not reified as target events immediately.
Hans-G?nter@24202 34 Signals received, for example, are counted initially. The counted signals
Hans-G?nter@24202 35 are reified at certain execution points. Hence, signal events may be
Hans-G?nter@24202 36 processed out of order, and if handled carelessly, on the wrong side of
Hans-G?nter@24202 37 a state change in event handling.
Hans-G?nter@24202 38 A useful way to view this is that occurrence of the source event is not
Hans-G?nter@24202 39 actually the arrival of the signal but is triggered by the counting of
Hans-G?nter@24202 40 the signal.
Hans-G?nter@24202 41
Hans-G?nter@24202 42 Reification can be forced when necessary. The schedule on which some
Hans-G?nter@24202 43 other events are created is non-obvious. This is especially the case
Hans-G?nter@24202 44 with watchers that watch for a condition rather than an event.
Hans-G?nter@24202 45 In some cases, target events are generated on a schedule that depends
Hans-G?nter@24202 46 on the operation of the event loop.