--- Event-1.00/lib/Event.pod 2004-05-14 16:20:47.000000000 +0100
+++ Event.pod 2004-11-28 16:42:22.000000000 +0000
@@ -21,6 +21,43 @@
to delay the handling of events so that they may be dispatched in
priority order when it is safe for callbacks to execute.
+Events (in the ordinary sense of the word) are detected by B<watchers>,
+which reify them as B<events> (in a specialised sense). For clarity,
+the former type of events may be called "source events", and the latter
+"target events". Source events, such as signals arriving, happen whether
+or not they are being watched. If a source event occurs that an active
+watcher is interested in, then the watcher generates a corresponding
+target event. Target events are only created by watchers. If several
+watchers are interested in the same source event, then they will each
+generate their own target event. So any particular source event may
+result in zero, one, two, or any number of target events: the same as
+the number of active watchers that were interested in it.
+
+Target events are queued to be processed in priority order (priority
+being determined by the creating watcher), and in FIFO order among events
+of the same priority. Queued ("pending") events can in some cases be
+cancelled before being processed. A queued event is processed by being
+passed to a callback function (or method on a particular object or class)
+that was specified to the watcher.
+
+A watcher, once created, operates autonomously, without the Event user
+having to retain any reference to it. However, keeping a reference
+makes it possible to modify most of the watcher's characteristics.
+A watcher can be switched between active and inactive states; when
+inactive it does not generate events.
+
+Some types of source event are not reified as target events immediately.
+Signals received, for example, are merely counted initially, and the
+counted signals are reified at certain points. This leads to signal
+events being processed out of order, and sometimes on the wrong side of a
+change in event handling. A useful way to view this is that the source
+event being reified is not actually the arrival of the signal but the
+processing of the counted signal. This processing can be forced when the
+order matters. A similar issue is the types of watcher that watch for
+a condition to be true, rather than for an instantaneous source event:
+they generate target events on a schedule that depends on the operation
+of the event loop.
+
=head1 PERL API
Events (the occurrence of such) are noticed and queued by 'event
@@ -68,7 +105,8 @@
=item 1
-Queue asyncronous events (signals, etc).
+Queue asyncronous events (signals, etc). That is, previously recorded
+events are reified.
=item 2
@@ -112,11 +150,24 @@
=item all_idle()
+Returns a list of all the idle watchers.
If the event queue is very busy, all the idle watchers will sit on the
idle queue waiting to run. However, be aware that if an idle watcher
has the C<max> attribute set then it will queue a normal event when
its C<max> wait time is exceeded.
+=item Event::_queue_pending()
+
+Examines asynchronous source events (signals) and reifies them as
+target events. Signals are handled according to the watchers that are
+active at the time that this is done, rather than at the time the signal
+is received. This is done automatically by one_event(), but is I<not>
+done automatically when the pending event list is examined (the C<pending>
+method on a watcher) or when signal watchers are started or modified.
+Call this function immediately before doing any of those operations
+if you need to distinguish between signals received before and after
+the operation.
+
=back
=head2 Event Watcher Constructors
@@ -152,8 +203,8 @@
All watchers support the following attributes: cb, cbtime, debug,
desc, prio, max_cb_tm, reentrant, and repeat. Watcher constructors
-accept the preceding and additionally: async and nice. All events
-support: hits, prio, and w. Moreover, watchers also offer extra
+accept the preceding and additionally: async and nice.
+Moreover, watchers also offer extra
attributes according to their specialty.
=head2 Shared Watcher Methods
@@ -166,10 +217,16 @@
Activate the watcher. Watchers refuse to C<start()> without
sufficient configuration information to generate events. Constructors
-always invoke C<start()> unless the C<parked=>1> option is requested.
+always invoke C<start()> unless the C<< parked=>1 >> option is requested.
You will need to set the parked option if you preallocate unconfigured
watchers.
+Note that this does not check for unreified asynchronous events.
+If you are starting a signal watcher, it may therefore see and
+act on signals that were actually received before it was started.
+Call C<Event::_queue_pending()> immediately before starting a signal
+watcher if you need to avoid this.
+
=item $watcher->again
This is the same as the C<start> except if a watcher has special
@@ -178,7 +235,8 @@
=item $watcher->now
-Cause the watcher to generate an event. The callback may or may not
+Cause the watcher to generate an event, even if it is stopped.
+The callback may or may not
run immediately depending upon the event's priority. If you must
unconditionally invoke the callback, consider something like
@@ -224,7 +282,8 @@
=item $watcher->is_suspended
-Reports whether the C<$watcher> is suspended.
+Reports whether the C<$watcher> is suspended. Suspension is a debugging
+feature; see the discussion of the "suspend" attribute below.
=item $watcher->pending
@@ -232,6 +291,10 @@
has any events pending in the event queue. In array context, returns
a list of all the watcher's pending events.
+Note that this does not check for unreified asynchronous events.
+Call C<Event::_queue_pending()> first if you need to be able to see
+signals received since the last operation of the event loop.
+
=back
=head2 Watcher Types
@@ -242,8 +305,8 @@
Extra attributes: min => $seconds, max => $seconds
-The callback is invoked only when no events are pending. If there is
-never a chance to idle, an event will be generated at least every
+Watches for the Event system to be idle, i.e., to have no events pending.
+If the system is never idle, an event will be generated at least every
C<max> seconds. While Event is idle, events will be generated not more
often than C<min> seconds.
@@ -257,16 +320,17 @@
Extra attributes: var => \$var, poll => 'rw'
Var watchers generate events when the given variable is read from or
-written to. C<poll> defaults to "w".
+written to, as specified by C<poll>. C<poll> defaults to "w".
As perl is a concise language, it is often difficult to
predict when a variable will be read. For this reason, variable
-watchers should poll for writes unless you know what you are doing.
+watchers should poll only for writes unless you know what you are doing.
=item timer
Extra attributes: at => $time, after => $sec, interval => $sec, hard => $bool
+Generates events at particular times.
The C<$time> and C<$sec> are in seconds. Fractional seconds may be used
if Time::HiRes is available. C<at> and C<after> are mutually exclusive.
@@ -283,8 +347,8 @@
use Time::Local;
my $TodaySeconds = int timelocal(0,0,0,(localtime)[3,4,5]);
-This calculation may seem a little heavy weight. If you don't care
-about daylight savings time then you can use this instead:
+This calculation may seem a little heavy weight. If you want to use
+UTC rather than local time then you can use this instead:
my $TodaySeconds = time - time % 86400;
@@ -292,7 +356,7 @@
already be in the past. If the C<hard> flag is set, the event will be
queued for execution relative to the last time the callback was
invoked. However, if C<hard> is false the new timeout will be
-calculated relative to the current time (this is the default).
+calculated relative to the current time. C<hard> defaults to false.
=item io
@@ -307,6 +371,8 @@
Note that it is your option whether to have multiple watchers per file
handle or to use a single watcher for all event conditions.
+If C<timeout> is set, events are also generated regularly if no actual
+I/O event occurs.
If C<timeout_cb> is set then timeouts use this alternate callback instead
of the main callback.
@@ -314,6 +380,12 @@
Extra attribute: signal => $str
+Generates events based on signal arrival. The events are not actually
+generated immediately when the signal arrives: signals received are
+counted, and reified by C<Event::_queue_pending()> or automatically by
+C<one_event>. Several signals of the same type may be merged into a
+single event; this is indicated by the "hits" attribute of the event.
+
=back
=head2 PRIORITY
@@ -372,7 +444,7 @@
By default, watcher constructors automatically invoke the C<start()>
method. If you don't want the watcher started then request
-C<parked=>1>.
+C<< parked=>1 >>.
=back
@@ -556,8 +628,9 @@
=item hits => $int
-A watcher increments C<hits> every time it registers an event.
Signals in quick succession can be clumped into a single event.
+The number of signals clumped together is indicated by this attribute.
+This is always 1 for event types that don't clump.
=item prio => $level
