<div class="gmail_quote">On Thu, Jan 20, 2011 at 2:55 AM, Glyph Lefkowitz <span dir="ltr"><<a href="mailto:glyph@twistedmatrix.com">glyph@twistedmatrix.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div style="word-wrap:break-word"><div>(minor nitpick: I really like "event-based" or "event-driven", as you've said here: why does <<a href="http://docs.recursivedream.com/twisted/" target="_blank">http://docs.recursivedream.com/twisted/</a>> say "asynchronous"? I find that especially in documentation it's a lot easier to explain "event-driven", because you can enumerate what the events are, instead of explaining the etymology of "synchronicity"...)</div>
</div></blockquote><div><br></div><div>I was also surprised by the choice of "asynchronous". From wikipedia:</div><div><br></div><blockquote class="gmail_quote" style="margin-top: 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0.8ex; border-left-width: 1px; border-left-color: rgb(204, 204, 204); border-left-style: solid; padding-left: 1ex; ">
In programming, asynchronous events are those occurring independently of the main program flow. Asynchronous actions are actions executed in a non-blocking scheme, allowing the main program flow to continue processing.</blockquote>
</div><div class="gmail_quote"><div><br></div><div>My understanding is that this is the opposite of what twisted is. The reactor hands-off control and must wait until control is relinquished. It handles events when it checks for them, not necessarily when they happen. The reactor and application code blocks, possibly halting the entire application if it is not written cooperatively.</div>
<div><br></div><div>This was a major point of confusion for me when I started to use twisted. I see that if I had carefully read the first few sentences under "Reactor Basics" in <a href="http://twistedmatrix.com/documents/current/core/howto/reactor-basics.html">http://twistedmatrix.com/documents/current/core/howto/reactor-basics.html</a>, I might not have been so confused. But, this is one of about 50 links on the "core" documentation page, which is one of about 20 links on the main documentation page. I'm guessing that simply editing and reorganizing existing documentation would go a long way toward fixing the documentation problem.</div>
<div><br></div><div>Personally, I'd love to see documentation organization that mimics Python's, especially the Tutorial/Library Reference/Language Reference breakdown. Users tend to know the level of understanding they are looking for and Python's documentation reflects that.</div>
<div><br></div><div>Cheers,</div><div><br></div><div>Jason</div><div><br></div><div>-- </div></div>Jason Rennie<br>Research Scientist, ITA Software<br>617-714-2645<br><a href="http://www.itasoftware.com/">http://www.itasoftware.com/</a><br>
<br>