Stackless issue python#36: documentation updates

- Update the C-API docs to match stackless_api.h
- Add the Stackless C-API documentation to the TOC-tree.
- fix broken links to external locations
- Add Anselm Kruis to the list of maintainers.

https://bitbucket.org/stackless-dev/stackless/issues/36
(grafted from f5b236f83d72 and 1896b9fd070901be01e6fc466fc1f9fa520b9c1d)

Author: Anselm Kruis

Doc/c-api/stackless.rst

@@ -1,9 +1,9 @@
 .. highlightlang:: c
 
-.. comment: affected files: data\refcounts.dat
-.. comment: affected files: c-api\stackless.rst
-.. comment: to do: link c-api\stackless.rst in somewhere
-.. comment: to do: generate new docs
+|SLP| C-API
+===========
+
+|SLP| provides the following C functions.
 
 Tasklets
 --------
@@ -18,7 +18,7 @@ Tasklets
    exception is set, which is in contrast elsewhere in the function.
 
 .. c:function:: int PyTasklet_Setup(PyTaskletObject *task, PyObject *args, PyObject *kwds)
-  
+
   Binds a tasklet function to parameters, making it ready to run and inserts in
   into the runnables queue.  Returns ``0`` if successful or ``-1`` in the case of failure.
 
@@ -33,6 +33,19 @@ Tasklets
   the call soft switched, ``0`` if the call hard switched and -1 in the case of
   failure.
 
+.. c:function:: int PyTasklet_Switch(PyTaskletObject *task)
+
+  Forces *task* to run immediately. The previous tasklet is paused.
+  Returns ``0`` if successful, and ``-1`` in the
+  case of failure.
+
+.. c:function:: int PyTasklet_Switch_nr(PyTaskletObject *task)
+
+  Forces *task* to run immediately, soft switching if possible.
+  The previous tasklet is paused. Returns ``1`` if
+  the call soft switched, ``0`` if the call hard switched and -1 in the case of
+  failure.
+
 .. c:function:: int PyTasklet_Remove(PyTaskletObject *task)
 
   Removes *task* from the runnables queue.  Be careful! If this tasklet has a C
@@ -45,41 +58,35 @@ Tasklets
   Insert *task* into the runnables queue, if it isn't already there.   If it is
   blocked or dead, the function returns ``-1`` and a :exc:`RuntimeError` is raised.
 
-.. c:function:: PyObject *PyTasklet_Become(PyTaskletObject *self, PyObject *retval)
-
-  Use of this API function is undocumented and unrecommended.
-
-  .. deprecated:: 2.5
-     Proved problematic in production use and are pending removal.
-
-.. c:function:: PyObject* PyTasklet_Capture(PyTaskletObject *self, PyObject *retval)
-
-  Use of this API function is undocumented and unrecommended.
-
-  .. deprecated:: 2.5
-     Proved problematic in production use and are pending removal.
-
 .. c:function:: int PyTasklet_RaiseException(PyTaskletObject *self, PyObject *klass, PyObject *args)
 
   Raises an instance of the *klass* exception on the *self* tasklet.  *klass* must
   be a subclass of :exc:`Exception`.  Returns ``1`` if the call soft switched, ``0``
   if the call hard switched and ``-1`` in the case of failure.
 
   .. note:: Raising :exc:`TaskletExit` on a tasklet can be done to silently kill
-     it, see :c:func:`PyTasklet_Kill`.  
+     it, see :c:func:`PyTasklet_Kill`.
+
+.. c:function:: int PyTasklet_Throw(PyTaskletObject *self, int pending, PyObject *exc, PyObject *val, PyObject *tb)
+
+  Raises (*exc*, *val*, *tb*) on the *self* tasklet. This is the C equivalent to
+  method :py:meth:`tasklet.throw`. Returns ``1`` if the call soft switched, ``0``
+  if the call hard switched and ``-1`` in the case of failure.
 
 .. c:function:: int PyTasklet_Kill(PyTaskletObject *self)
-     
+
   Raises :exc:`TaskletExit` on tasklet *self*.  This should result in *task* being
-  silently killed. Returns ``1`` if the call soft switched, ``0`` if the call hard
+  silently killed. (This exception is ignored by tasklet_end and
+  does not invoke main as exception handler.)
+  Returns ``1`` if the call soft switched, ``0`` if the call hard
   switched and ``-1`` in the case of failure.
 
 .. c:function:: int PyTasklet_GetAtomic(PyTaskletObject *task)
 
   Returns ``1`` if *task* is atomic, otherwise ``0``.
 
 .. c:function:: int PyTasklet_SetAtomic(PyTaskletObject *task, int flag)
-  
+
   Returns ``1`` if *task* is currently atomic, otherwise ``0``.  Sets the
   atomic attribute to the logical value of *flag*.
 
@@ -129,7 +136,7 @@ Tasklets
 
   Returns ``1`` if *task* is alive (has an associated frame), otherwise
   ``0`` if it is dead.
-  
+
 .. c:function:: int PyTasklet_Paused(PyTaskletObject *task)
 
   Returns ``1`` if *task* is paused, otherwise ``0``.  A tasklet is paused if it is
@@ -151,7 +158,7 @@ Tasklets
 Channels
 --------
 
- .. c:function:: PyChannelObject* PyChannel_New(PyTypeObject *type)
+.. c:function:: PyChannelObject* PyChannel_New(PyTypeObject *type)
 
   Return a new channel object, or *NULL* in the case of failure.  *type* must be
   derived from :c:type:`PyChannel_Type` or be *NULL*, otherwise a :exc:`TypeError`
@@ -184,6 +191,11 @@ Channels
   Returns ``0`` if successful or ``-1`` in the case of failure.  An instance of the
   exception type *klass* is raised on the first tasklet blocked on channel *self*.
 
+.. c:function:: int PyChannel_SendThrow(PyChannelObject *self, PyObject *exc, PyObject *val, PyObject *tb)
+
+  Returns ``0`` if successful or ``-1`` in the case of failure.
+  (*exc*, *val*, *tb*) is raised on the first tasklet blocked on channel *self*.
+
 .. c:function:: PyObject *PyChannel_GetQueue(PyChannelObject *self)
 
   Returns the first tasklet in the channel *self*'s queue, or *NULL* in the case
@@ -255,6 +267,23 @@ stackless module
 
   Get the currently running tasklet, that is, "yourself".
 
+.. c:function:: long PyStackless_GetCurrentId()
+
+  Get a unique integer ID for the current tasklet
+
+  Threadsafe.
+
+  This is useful for benchmarking code that
+  needs to get some sort of a stack identifier and must
+  not worry about the GIL being present and so on.
+
+  .. note::
+
+     1. the "main" tasklet on each thread will have the same id,
+        even if a proper tasklet has not been initialized.
+
+     2. IDs may get recycled for new tasklets.
+
 .. c:function:: PyObject *PyStackless_RunWatchdog(long timeout)
 
   Runs the scheduler until there are no tasklets remaining within it, or until
@@ -274,28 +303,28 @@ stackless module
   Wraps :c:func:`PyStackless_RunWatchdog`, but allows its behaviour to be
   customised by the value of *flags* which may contain any of the following
   bits:
-  
+
   ``Py_WATCHDOG_THREADBLOCK``
      Allows a thread to block if it runs out of tasklets.  Ideally
      it will be awakened by other threads using channels which its
      blocked tasklets are waiting on.
-  
+
   ``Py_WATCHDOG_SOFT``
      Instead of interrupting a tasklet, we wait until the
      next tasklet scheduling moment to return.  Always returns
      *Py_None*, as everything is in order.
-  
+
   ``Py_WATCHDOG_IGNORE_NESTING``
      Allows interrupts at all levels, effectively acting as
      though the *ignore_nesting* attribute were set on all
      tasklets.
-  
+
   ``Py_WATCHDOG_TIMEOUT``
      Interprets *timeout* as a fixed run time, rather than a
      per-tasklet run limit.  The function will then attempt to
      interrupt execution once this many total opcodes have
      been executed since the call was made.
-     
+
 debugging and monitoring functions
 ----------------------------------
 

Doc/stackless-python.rst

@@ -32,6 +32,7 @@ through the :mod:`stackless` module.
    :maxdepth: 3
 
    library/stackless/stackless.rst
+   c-api/stackless.rst
 
 .. I'd really like the "What you need to know", "External resources" and
 .. "History" sections to appear in the table of contents.. but this does
@@ -58,7 +59,7 @@ and writing, socket operations, interprocess communication and more), although
 asynchronous versions of IO functionality.
 
 Some third-party modules are available that replace standard library
-functionality with Stackless-compatible versions.  The advantage of this 
+functionality with Stackless-compatible versions.  The advantage of this
 approach is that other modules which use that standard functionality,
 also work with Stackless when the replacement is installed.  The
 `Stackless socket
@@ -94,11 +95,12 @@ documentation <library/stackless/debugging>`.
 External resources
 ==================
 
-There are a range of resources available outside of this document:
+There are a range of resources available outside of this document. However most of them are
+nowadays quite dated:
 
  * The Stackless `mailing list <http://www.stackless.com/mailman/listinfo/stackless>`_.
- * The Stackless `examples project <http://code.google.com/p/stacklessexamples>`_.
- * Grant Olson's tutorial: `Introduction to Concurrent Programming with Stackless Python <http://www.grant-olson.net/python/intro-to-stackless-python>`_.
+ * The Stackless `examples project <https://bitbucket.org/stackless-dev/stacklessexamples>`_.
+ * Grant Olson's tutorial: `Introduction to Concurrent Programming with Stackless Python <http://www.grant-olson.net/projects/introduction-to-stackless-python.html>`_.
 
 History
 =======
@@ -154,14 +156,15 @@ Richard Tew to PyCon where `they sprinted
 <http://zope.stackless.com/Members/rmtew/News%20Archive/pycon2006/news_item_view>`_
 with the aid of Christian Tismer.  The result was an up to date release of |SLP|.
 From this point in time, maintaining and releasing |SLP|
-has been undertaken by Richard and Kristján.
+has been undertaken by Richard and Kristján. A few years later Anselm Kruis
+joined the team.
 
 .. [#PSFTRADEMARK]
-   "Python" and the Python logos are trademarks or registered trademarks of the 
+   "Python" and the Python logos are trademarks or registered trademarks of the
    *Python Software Foundation*, used by |SLP| with permission from the Foundation.
    See http://www.python.org/psf/trademarks/ for details.
 
 .. [#CPY]
-   With the term "|CPY|" we refer to the reference implementation of the |PPL| 
+   With the term "|CPY|" we refer to the reference implementation of the |PPL|
    that is released by the *Python Software Foundation* on http://www.python.org.