On Tue, Dec 15, 2009 at 8:17 AM, Andrew Dalke <[email protected]> wrote: > I noticed you several times say not to use a bare exception. > The main one is library/stackless/stackless.html#slp-exc > >> We catch Exception explicitly, rather than catching any exception. The >> reason for this is to avoid catching exceptions we should not be catching >> like SystemExit or TaskletExit. > > > You should document if TaskletExit derives from Exception or BaseException.
Done. > I read text like: >> When called, the tasklet is blocked and moved to the end of the chain of >> runnable tasklets. > > > and remembered the early days of Python and JPython, when the documentation > was clarified for which aspects were part of the language (garbage > collection) or implementation (reference counting). > > I can see how other implementations of Stackless-type Pythons (PyPy?) might > use a priority system which puts tasklets some place other than the end. > > I assume the intent is to describe the current implementation of Stackless. Yes. This documentation is solely for Stackless Python. > stackless/stackless.html#stackless.run >> A non-zero value indicates that as each tasklet is given a chance to run, it >> should only be allowed to run as long as the number of interpreter >> instructions are below this value. > > > This should use the same terminology as sys.setcheckinterval(), > > The default is 100, meaning the check is performed every 100 > Python virtual instructions. > > That is, change "interpreter instructions" to "Python virtual instructions." Done. > I looked, but found no further explanation for what that means in the Python > documentation, so the link to the dis module is as good as any. Same conclusion I came to. > In stackless/debugging.html >> In an ideal world, Stackless Python might include modified versions of these >> modules. However, no-one has volunteered the time and effort to do the work >> required at this time. > > Might as well add a call for contributions, for those interesting in > volunteering. Otherwise it reads as a bit pessimistic. Done. > The "Overview" is a bit confusing. It has: > > stackless — The built-in extension module > • Tasklets — Lightweight threads > • Tasklets, main, current and more > • The tasklet class > • Channels — Communication between tasklets > • Channels and threads > • The channel class > • The scheduler — How tasklets are run > • Cooperative scheduling > • Pre-emptive scheduling > • Exceptions > • Debugging and Tracing — How Stackless differs > • settrace and tasklets > • Threads — Threads and Stackless > • A scheduler per thread > • Channels are thread-safe > • Pickling — Serialisation of running tasklets > • Functions > • Attributes > • Exceptions > > > which made me think there was a correspondence between levels and web pages. > But "stackless" the top-level and "Functions", "Attributes", and "Exceptions" > all go to the same HTML page, while "Pickling" goes to its own page. > > At first I thought there was duplicate information, since I had read the > entire "stackless" link before going through each item. > > I don't have a good solution for this. I'm only pointing out that I was > confused. I agree. However, mucking about with the way this lays out automatically was not something I had a good solution for either. > On the topic of "confused", there are two web pages with URLs ending in > "/stackless.html". That lent to my confusion. > stackless-python-2.6.4-docs-html/stackless.html > stackless-python-2.6.4-docs-html/library/stackless/stackless.html > > Could one of them be changed, perhaps the first to "stackless_python.html"? Done. > Again - very nicely done! Thanks. I have not updated the downloadable versions of the documentation, but the browseable online version is updated. For now this is still hosted on my site, as I am not sure how to add it to the Stackless web site except bunged in some inappropriate directory like the downloads are. http://www.disinterest.org/resource/stackless/2.6.4-docs-html/stackless-python.html Cheers, Richard. _______________________________________________ Stackless mailing list [email protected] http://www.stackless.com/mailman/listinfo/stackless
