SliTaz Repositories

     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/perl-event/description.txt	Tue Aug 02 10:16:02 2022 +0100
     1.3 @@ -0,0 +1,46 @@
     1.4 +The Event module provides a central facility to watch for various types
     1.5 +of events and invokes a callback when these events occur.
     1.6 +The idea is to delay the handling of events so that they may be dispatched
     1.7 +in priority order when it is safe for callbacks to execute.
     1.8 +
     1.9 +Events (in the ordinary sense of the word) are detected by watchers, which
    1.10 +reify them as events (in the special Event module sense). For clarity, the
    1.11 +former type of events may be called "source events", and the latter
    1.12 +"target events".
    1.13 +Source events, such as signals arriving, happen whether or not they are
    1.14 +being watched. If a source event occurs which a watcher is actively watching
    1.15 +then the watcher generates a corresponding target event.
    1.16 +Target events are only created by watchers.
    1.17 +If several watchers are interested in the same source event then each will
    1.18 +generate their own target event. Hence, any particular source event may
    1.19 +result in zero, one, two, or any number of target events: the same as the
    1.20 +number of watchers which were actively watching for it.
    1.21 +
    1.22 +Target events are queued to be processed in priority order (priority being
    1.23 +determined by the creating watcher) and in FIFO order among events of the
    1.24 +same priority.
    1.25 +Queued ("pending") events can, in some cases, be cancelled before being
    1.26 +processed. A queued event is processed by being passed to the callback
    1.27 +function (or method on a particular object or class) which was specified
    1.28 +to the watcher.
    1.29 +
    1.30 +A watcher, once created, operates autonomously without the Event user
    1.31 +having to retain any reference to it. However, keeping a reference makes
    1.32 +it possible to modify most of the watcher's characteristics.
    1.33 +A watcher can be switched between active and inactive states.
    1.34 +When inactive, it does not generate target events.
    1.35 +
    1.36 +Some types of source event are not reified as target events immediately.
    1.37 +Signals received, for example, are counted initially. The counted signals
    1.38 +are reified at certain execution points. Hence, signal events may be
    1.39 +processed out of order, and if handled carelessly, on the wrong side of
    1.40 +a state change in event handling.
    1.41 +A useful way to view this is that occurrence of the source event is not
    1.42 +actually the arrival of the signal but is triggered by the counting of
    1.43 +the signal.
    1.44 +
    1.45 +Reification can be forced when necessary. The schedule on which some
    1.46 +other events are created is non-obvious. This is especially the case
    1.47 +with watchers that watch for a condition rather than an event.
    1.48 +In some cases, target events are generated on a schedule that depends
    1.49 +on the operation of the event loop.