Joshua N Pritikin wrote: >1. Source event (a signal) >2. Event's counting of the signal >3. Target event, once something calls queue_pending >4. Target events are stored in a priority queue, possibly changing the >order >5. Event callbacks are invoked by one_event()
Ah, we have different definitions of "source event". The way I intended it, for event-based rather than condition-based watchers, was: 1. source event happens; target events are immediately generated 2. target events are stored in a priority queue 3. event callbacks are invoked and the complication for signal handlers is: 0. signal received; count incremented 1. queue_pending() runs, and treats the non-zero count as a source event; ... Thus, for signals, the "source event", defined as "the occurrence that generates target events", is a signal count being non-zero during the call to queue_pending(). >I removed it because I found/find your phrasing unacceptably vague -- >better to having nothing than a bunch of hedges. If you really want to >explain how it works then better be specific. Hmm. Since that section is describing the architecture, rather than all the specifics, a bunch of hedges seemed appropriate. My aim was to warn that there's non-obvious stuff so that the reader will be on notice to read the more specific documentation. There should be more detailed documentation for each watcher type, though some of these specifics are currently lacking. (That's future work. Btw, I think that the type-specific documentation would be better relegated to separate documents: the current document is rather cluttered with all the type-specific options. The tutorial separates them out better.) I think the distinction between watchers that watch for an event and those that watch for a condition is worth explaining in the general description. Perhaps we need more terminology, with "source conditions". The detection of a source condition happens at a certain point in the event loop -- when there are no events to process? -- and this detection is the source event (in my sense) for the watcher. >Can you put some specific example scripts together so I can include >them? The ones I've already posted should be clear enough to illustrate the tricky cases. >=item queue_pending() > >Examines asynchronous source events (timers & signals) and reifies >them as target events. C<queue_pending()> is called implicitly by >C<sweep()> and C<one_event()>. Mm. Perhaps add ", but is not called implicitly by anything else". Better to make that explicit. -zefram
