[Stackless] Documentation for Stackless

[Richard Tew]

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.

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.