[Stackless] Documentation for Stackless
richard.m.tew at gmail.com
Mon Dec 14 23:06:11 CET 2009
On Tue, Dec 15, 2009 at 8:17 AM, Andrew Dalke <dalke at dalkescientific.com> 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.
> 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.
>> 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."
> 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.
> 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.
> Could one of them be changed, perhaps the first to "stackless_python.html"?
> 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.
More information about the Stackless