[Stackless] Documentation for Stackless

Andrew Dalke dalke at dalkescientific.com
Mon Dec 14 20:17:10 CET 2009

On Dec 14, 2009, at 10:16 AM, Richard Tew wrote:
> I have spent a week and a bit writing documentation for Stackless.

Very nice!

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.

> 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.

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.

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!

				dalke at dalkescientific.com

More information about the Stackless mailing list