Test of sphinx docs with sam's tutorial.

docs/Makefile

+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Shrapnel.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Shrapnel.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/Shrapnel"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Shrapnel"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."

docs/conf.py

+# -*- coding: utf-8 -*-
+#
+# Shrapnel documentation build configuration file, created by
+# sphinx-quickstart on Fri Apr 13 18:44:49 2012.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Shrapnel'
+copyright = u'2012, Sam Rushing'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '1.0.2'
+# The full version, including alpha/beta/rc tags.
+release = '1.0.2'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'sphinxdoc'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Shrapneldoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'Shrapnel.tex', u'Shrapnel Documentation',
+   u'Sam Rushing', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'shrapnel', u'Shrapnel Documentation',
+     [u'Sam Rushing'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output ------------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('index', 'Shrapnel', u'Shrapnel Documentation',
+   u'Sam Rushing', 'Shrapnel', 'One line description of project.',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'

docs/index.rst

+.. Shrapnel documentation master file, created by
+   sphinx-quickstart on Fri Apr 13 18:44:49 2012.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to Shrapnel's documentation!
+====================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 1
+
+   tutorial
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

docs/shrapnel.svg

+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="1052.3622"
+   height="744.09448"
+   id="svg2"
+   version="1.1"
+   inkscape:version="0.48.1 r9760"
+   sodipodi:docname="shrike.svg">
+  <defs
+     id="defs4">
+    <inkscape:perspective
+       sodipodi:type="inkscape:persp3d"
+       inkscape:vp_x="2.6642081 : 450.19734 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_z="1047.9219 : 410.23422 : 1"
+       inkscape:persp3d-origin="526.18109 : 248.03149 : 1"
+       id="perspective3001" />
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="1.187804"
+     inkscape:cx="526.18109"
+     inkscape:cy="372.04724"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     inkscape:window-width="1618"
+     inkscape:window-height="1252"
+     inkscape:window-x="103"
+     inkscape:window-y="110"
+     inkscape:window-maximized="0" />
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(0,-308.2677)">
+    <rect
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect3913"
+       width="41.102364"
+       height="47.480316"
+       x="17.716541"
+       y="473.38577" />
+    <rect
+       style="fill:#b3b3b3;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.14044118;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect3911"
+       width="41.10236"
+       height="52.440941"
+       x="17.007874"
+       y="691.6535" />
+    <rect
+       style="fill:#b3b3b3;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.22939622;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect3017"
+       width="160.49298"
+       height="541.52734"
+       x="69.828453"
+       y="402.52829"
+       ry="0" />
+    <rect
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.22939622;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect3029"
+       width="149.5751"
+       height="169.22731"
+       x="75.287399"
+       y="409.07901" />
+    <rect
+       style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.22939622;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect3031"
+       width="137.56543"
+       height="39.304409"
+       x="81.292229"
+       y="416.72153" />
+    <rect
+       y="462.00809"
+       x="81.292229"
+       height="39.304409"
+       width="137.56543"
+       id="rect3035"
+       style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.22939622;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.84482175;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect3039"
+       width="137.56543"
+       height="18.560415"
+       x="81.292229"
+       y="506.77145" />
+    <rect
+       y="529.69904"
+       x="80.200439"
+       height="39.304409"
+       width="139.74901"
+       id="rect3043"
+       style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.23911488;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       ry="0"
+       y="405.80365"
+       x="287.49896"
+       height="541.52734"
+       width="160.49298"
+       id="rect3813"
+       style="fill:#b3b3b3;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.22939622;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       y="411.2626"
+       x="292.95792"
+       height="148.48332"
+       width="149.5751"
+       id="rect3815"
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.15158355;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       y="417.81335"
+       x="298.96277"
+       height="19.652199"
+       width="137.56543"
+       id="rect3817"
+       style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.86931431;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.22939622;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect3819"
+       width="137.56543"
+       height="39.304409"
+       x="298.96277"
+       y="443.44769" />
+    <rect
+       y="488.21106"
+       x="298.96277"
+       height="57.864822"
+       width="137.56543"
+       id="rect3821"
+       style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.4916898;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.22939622;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect3845"
+       width="149.5751"
+       height="169.22731"
+       x="632.32953"
+       y="329.88934" />
+    <rect
+       style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.22939622;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect3847"
+       width="137.56543"
+       height="39.304409"
+       x="638.33441"
+       y="337.53186" />
+    <rect
+       y="382.81845"
+       x="638.33441"
+       height="39.304409"
+       width="137.56543"
+       id="rect3849"
+       style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.22939622;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.84482175;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect3851"
+       width="137.56543"
+       height="18.560415"
+       x="638.33441"
+       y="427.58176" />
+    <rect
+       y="450.50937"
+       x="637.24261"
+       height="39.304409"
+       width="139.74901"
+       id="rect3853"
+       style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.23911488;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       y="469.14532"
+       x="805.21356"
+       height="61.140198"
+       width="149.5751"
+       id="rect3855"
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.73895848;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       y="476.78784"
+       x="811.21838"
+       height="25.111151"
+       width="137.56543"
+       id="rect3857"
+       style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.98266286;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.67957491;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect3859"
+       width="137.56543"
+       height="12.0097"
+       x="812.31018"
+       y="507.8811" />
+    <rect
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.02145195;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect3865"
+       width="149.5751"
+       height="116.82144"
+       x="825.68091"
+       y="584.77936" />
+    <rect
+       style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.00379777;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect3867"
+       width="137.56543"
+       height="26.202938"
+       x="831.68573"
+       y="592.42194" />
+    <rect
+       y="623.5152"
+       x="831.68573"
+       height="53.497658"
+       width="137.56543"
+       id="rect3869"
+       style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.43429542;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.61469811;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect3871"
+       width="137.56543"
+       height="9.8261023"
+       x="831.68573"
+       y="682.47186" />
+    <text
+       xml:space="preserve"
+       style="font-size:49.1758461px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+       x="149.66675"
+       y="640.53827"
+       id="text3875"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         x="149.66675"
+         y="640.53827"
+         id="tspan3898"
+         style="text-align:center;text-anchor:middle">main</tspan><tspan
+         sodipodi:role="line"
+         x="149.66675"
+         y="702.00806"
+         style="text-align:center;text-anchor:middle"
+         id="tspan4014">stack</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:49.1758461px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+       x="366.40079"
+       y="642.7218"
+       id="text3879"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan3881"
+         x="366.40079"
+         y="642.7218">coro</tspan><tspan
+         sodipodi:role="line"
+         x="366.40079"
+         y="704.19159"
+         id="tspan3902">stack</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:24.58792305px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+       x="672.9906"
+       y="365.34204"
+       id="text3906"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan3908"
+         x="672.9906"
+         y="365.34204">coro#0</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:24.58792305px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+       x="846.93707"
+       y="497.5014"
+       id="text3910"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan3912"
+         x="846.93707"
+         y="497.5014">coro#1</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:24.58792305px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+       x="866.41394"
+       y="613.68134"
+       id="text3914"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan3916"
+         x="866.41394"
+         y="613.68134">coro#2</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:19.67033958px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+       x="260.99069"
+       y="972.79584"
+       id="text3918"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan3920"
+         x="260.99069"
+         y="972.79584">swap() switches between running on the main</tspan><tspan
+         sodipodi:role="line"
+         x="260.99069"
+         y="997.38379"
+         id="tspan3922">stack and the coro stack.</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:17.21154594px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+       x="234.41489"
+       y="634.64331"
+       id="text3924"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan3926"
+         x="234.41489"
+         y="634.64331">swap()</tspan></text>
+    <path
+       id="path3930"
+       d="m 276.09164,651.43827 -6.15489,-4.89396 c -0.007,1.44704 -0.009,1.81022 -0.0131,2.53459 l -24.37018,0 c -0.004,-0.72445 -0.007,-1.08979 -0.0131,-2.5375 l -6.1549,4.89687 6.1549,4.89396 c 0.005,-1.54238 0.009,-1.97524 0.0131,-2.69227 l 24.37018,0 c 0.004,0.71703 0.009,1.14989 0.0131,2.69227 l 6.15489,-4.89396 z"
+       style="fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:0.10477623;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1"
+       inkscape:connector-curvature="0" />
+    <text
+       xml:space="preserve"
+       style="font-size:24.58792305px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+       x="102.32178"
+       y="490.02835"
+       id="text3932"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan3934"
+         x="102.32178"
+         y="490.02835">scheduler</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:39.34067917px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+       x="573.12317"
+       y="567.94855"
+       id="text3940"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan3942"
+         x="573.12317"
+         y="567.94855">stack slice copies</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:24.58792305px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+       x="605.67572"
+       y="602.10406"
+       id="text3944"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan3946"
+         x="605.67572"
+         y="602.10406">(potentially millions)</tspan></text>
+    <text
+       sodipodi:linespacing="125%"
+       id="text3952"
+       y="471.25784"
+       x="333.23474"
+       style="font-size:24.58792305px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+       xml:space="preserve"><tspan
+         y="471.25784"
+         x="333.23474"
+         id="tspan3954"
+         sodipodi:role="line">coro#n</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+       x="654.14832"
+       y="162.34866"
+       id="text3956"
+       sodipodi:linespacing="125%"
+       transform="translate(0,308.2677)"><tspan
+         sodipodi:role="line"
+         id="tspan3958"
+         x="654.14832"
+         y="162.34866" /></text>
+    <rect
+       y="814.81781"
+       x="516.99066"
+       height="169.22731"
+       width="149.5751"
+       id="rect3968"
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.22939622;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       y="822.46033"
+       x="522.99554"
+       height="39.304409"
+       width="137.56543"
+       id="rect3970"
+       style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.22939622;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.22939622;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect3972"
+       width="137.56543"
+       height="39.304409"
+       x="522.99554"
+       y="867.74695" />
+    <rect
+       y="912.51025"
+       x="522.99554"
+       height="18.560415"
+       width="137.56543"
+       id="rect3974"
+       style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.84482175;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:1.23911488;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect3976"
+       width="139.74901"
+       height="39.304409"
+       x="521.90375"
+       y="935.43787" />
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+       x="672.66986"
+       y="844.98657"
+       id="text3982"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan3984"
+         x="672.66986"
+         y="844.98657">PyObject_Call (func=0x1002d8dd0, arg=0x1002eaec0, kw=0x0)</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+       x="672.66986"
+       y="890.27319"
+       id="text3986"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan3988"
+         x="672.66986"
+         y="890.27319">PyEval_CallObjectWithKeywords (func=0x1002d8dd0, ...)</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+       x="672.66986"
+       y="924.66156"
+       id="text3990"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan3992"
+         x="672.66986"
+         y="924.66156">PyEval_EvalFrameEx (f=0x10031f070, ...)</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+       x="672.66986"
+       y="957.96118"
+       id="text3994"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan3996"
+         x="672.66986"
+         y="957.96118">PyEval_EvalCodeEx (co=0x10040a7b0, ...)</tspan><tspan
+         sodipodi:role="line"
+         x="672.66986"
+         y="972.96118"
+         id="tspan3998" /></text>
+    <text
+       xml:space="preserve"
+       style="font-size:32px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+       x="517.28607"
+       y="800.63715"
+       id="text4000"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan4002"
+         x="517.28607"
+         y="800.63715">stack frame</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+       x="109.74291"
+       y="926.07874"
+       id="text4004"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan4006"
+         x="109.74291"
+         y="926.07874">4MB</tspan></text>
+    <text
+       sodipodi:linespacing="125%"
+       id="text4008"
+       y="926.07874"
+       x="327.41342"
+       style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+       xml:space="preserve"><tspan
+         y="926.07874"
+         x="327.41342"
+         id="tspan4010"
+         sodipodi:role="line">4MB</tspan></text>
+    <g
+       id="g4067"
+       transform="matrix(0.92221294,-0.38668242,0.38668242,0.92221294,-113.90628,266.46282)">
+      <path
+         inkscape:connector-curvature="0"
+         style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.20497175;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+         d="m 471.24729,456.37726 31.18686,10.23254 -6.99407,-7.32144 90.71753,0 0,-6.33834 -90.57701,0 6.85355,-7.52256 -31.18686,10.9498 z"
+         id="path4026" />
+      <text
+         sodipodi:linespacing="125%"
+         id="text4032"
+         y="444.51779"
+         x="511.86896"
+         style="font-size:20px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+         xml:space="preserve"><tspan
+           y="444.51779"
+           x="511.86896"
+           id="tspan4034"
+           sodipodi:role="line">resume</tspan></text>
+    </g>
+    <g
+       id="g3951">
+      <path
+         id="path4030"
+         d="m 604.83658,382.91221 -24.7521,21.55594 3.59606,-9.46514 -83.57577,35.28118 -2.46506,-5.83935 83.44631,-35.22653 -9.23962,-4.26491 32.99018,-2.04119 z"
+         style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.20497175;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+         inkscape:connector-curvature="0" />
+      <text
+         transform="matrix(0.9212747,-0.38891248,0.38891248,0.9212747,0,0)"
+         sodipodi:linespacing="125%"
+         id="text4036"
+         y="576.13635"
+         x="317.1749"
+         style="font-size:20px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+         xml:space="preserve"><tspan
+           y="576.13635"
+           x="317.1749"
+           id="tspan4038"
+           sodipodi:role="line">yield</tspan></text>
+    </g>
+    <g
+       id="g4048">
+      <flowRoot
+         style="fill:black;stroke:none;stroke-opacity:1;stroke-width:1px;stroke-linejoin:miter;stroke-linecap:butt;fill-opacity:1;font-family:Times New Roman;font-style:normal;font-weight:normal;font-size:12px;line-height:125%;letter-spacing:0px;word-spacing:0px;-inkscape-font-specification:Times New Roman"
+         id="flowRoot4040"
+         xml:space="preserve"><flowRegion
+           id="flowRegion4042"><rect
+             y="103.41638"
+             x="467.24881"
+             height="78.295746"
+             width="123.75779"
+             id="rect4044" /></flowRegion><flowPara
+           id="flowPara4046" /></flowRoot>    </g>
+    <flowRoot
+       xml:space="preserve"
+       id="flowRoot4054"
+       style="fill:black;stroke:none;stroke-opacity:1;stroke-width:1px;stroke-linejoin:miter;stroke-linecap:butt;fill-opacity:1;font-family:Times New Roman;font-style:normal;font-weight:normal;font-size:12px;line-height:125%;letter-spacing:0px;word-spacing:0px;-inkscape-font-specification:Times New Roman"><flowRegion
+         id="flowRegion4056"><rect
+           id="rect4058"
+           width="140.59558"
+           height="90.082199"
+           x="460.5137"
+           y="93.313705" /></flowRegion><flowPara
+         id="flowPara4060" /></flowRoot>    <rect
+       y="665.60077"
+       x="698.55554"
+       height="12.273481"
+       width="15.714643"
+       id="rect4072"
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.10731567;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.16018762;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect4074"
+       width="23.456882"
+       height="18.320341"
+       x="738.12439"
+       y="651.28864" />
+    <rect
+       y="720.32361"
+       x="701.9231"
+       height="22.529789"
+       width="28.846548"
+       id="rect4076"
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.1969938;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.13074268;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect4078"
+       width="19.145149"
+       height="14.952783"
+       x="733.073"
+       y="695.06689" />
+    <rect
+       y="691.69934"
+       x="772.64178"
+       height="10.958413"
+       width="14.030864"
+       id="rect4080"
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.0958171;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.29129282;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect4082"
+       width="42.655113"
+       height="33.314583"
+       x="766.7486"
+       y="722.84924" />
+    <rect
+       y="720.26825"
+       x="832.41602"
+       height="43.835133"
+       width="56.125347"
+       id="rect4084"
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.38328138;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       y="646.2373"
+       x="716.23523"
+       height="7.1422563"
+       width="9.1447563"
+       id="rect4086"
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.06244976;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       y="626.03192"
+       x="739.80817"
+       height="5.8271875"
+       width="7.4609771"
+       id="rect4088"
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.05095119;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.05095119;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect4090"
+       width="7.4609771"
+       height="5.8271875"
+       x="711.1839"
+       y="628.55762" />
+    <rect
+       y="633.60895"
+       x="695.18799"
+       height="3.3015182"
+       width="4.2271767"
+       id="rect4092"
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.02886749;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       y="732.11011"
+       x="854.30518"
+       height="59.572937"
+       width="76.275627"
+       id="rect4094"
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.52088809;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       y="736.00745"
+       x="857.36731"
+       height="13.362153"
+       width="70.151306"
+       id="rect4096"
+       style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.51188534;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.73141706;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect4098"
+       width="70.151306"
+       height="27.281059"
+       x="857.36731"
+       y="751.8634" />
+    <rect
+       y="781.92828"
+       x="857.36731"
+       height="5.010808"
+       width="70.151306"
+       id="rect4100"
+       style="fill:#ff6600;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.31346449;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <text
+       sodipodi:linespacing="125%"
+       id="text4102"
+       y="746.84863"
+       x="875.0769"
+       style="font-size:12.53857899px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+       xml:space="preserve"><tspan
+         y="746.84863"
+         x="875.0769"
+         id="tspan4104"
+         sodipodi:role="line">coro#3</tspan></text>
+    <rect
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.04877656;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect4106"
+       width="7.1425371"
+       height="5.5784788"
+       x="679.19208"
+       y="653.81433" />
+    <rect
+       y="641.9082"
+       x="681.87097"
+       height="3.486217"
+       width="4.4636602"
+       id="rect4108"
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.03048244;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.02031904;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect4110"
+       width="2.9753954"
+       height="2.3238494"
+       x="682.46625"
+       y="629.4068" />
+    <rect
+       y="625.23969"
+       x="687.52637"
+       height="2.3238494"
+       width="2.9753954"
+       id="rect4112"
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.02031904;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.02031904;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect4114"
+       width="2.9753954"
+       height="2.3238494"
+       x="698.53955"
+       y="625.83496" />
+    <rect
+       y="621.07251"
+       x="695.56305"
+       height="2.3238494"
+       width="2.9753954"
+       id="rect4116"
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.02031904;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <rect
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.02031904;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       id="rect4118"
+       width="2.9753954"
+       height="2.3238494"
+       x="714.91052"
+       y="618.09601" />
+    <rect
+       y="616.01245"
+       x="701.81378"
+       height="2.3238494"
+       width="2.9753954"
+       id="rect4120"
+       style="fill:#aa0000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.02031904;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+       x="36.372467"
+       y="486.14166"
+       id="text3125"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan3127"
+         x="36.372467"
+         y="486.14166">Used</tspan><tspan
+         sodipodi:role="line"
+         x="36.372467"
+         y="501.14166"
+         id="tspan3129">Stack</tspan><tspan
+         sodipodi:role="line"
+         x="36.372467"
+         y="516.14166"
+         id="tspan3131">Area</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+       x="36.735748"
+       y="706.5354"
+       id="text3133"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan3135"
+         x="36.735748"
+         y="706.5354">Unused</tspan><tspan
+         sodipodi:role="line"
+         x="36.735748"
+         y="721.5354"
+         id="tspan3137">Stack</tspan><tspan
+         sodipodi:role="line"
+         x="36.735748"
+         y="736.53546"
+         id="tspan3139">Area</tspan><tspan
+         sodipodi:role="line"
+         x="36.735748"
+         y="751.53546"
+         id="tspan3141" /></text>
+    <text
+       sodipodi:linespacing="125%"
+       id="text3938"
+       y="396"
+       x="109.33276"
+       style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+       xml:space="preserve"><tspan
+         y="396"
+         x="109.33276"
+         id="tspan3940"
+         sodipodi:role="line">0MB</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:14px;font-style:normal;font-weight:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+       x="569.5769"
+       y="-32.028229"
+       id="text3942"
+       sodipodi:linespacing="125%"
+       transform="matrix(0,1,-1,0,0,0)"><tspan
+         sodipodi:role="line"
+         id="tspan3944"
+         x="569.5769"
+         y="-32.028229">Stack Growth</tspan></text>
+    <path
+       id="path3949"
+       d="m 34.496003,649.45247 -6.4113,-9.75108 4.61419,2.14152 0.15907,-28.63263 4.00522,-0.0572 -0.15883,28.58826 4.76555,-2.23095 -6.9739,9.94202 z"
+       style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:#000000;stroke-width:0.09153501;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       inkscape:connector-curvature="0" />
+    <text
+       xml:space="preserve"
+       style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Times New Roman;-inkscape-font-specification:Times New Roman"
+       x="327.0033"
+       y="395.29135"
+       id="text3957"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan3959"
+         x="327.0033"
+         y="395.29135">0MB</tspan></text>
+  </g>
+</svg>

docs/tutorial.rst

+=============================
+Getting Started with Shrapnel
+=============================
+
+:Date: $Date: 2012/03/30 $
+:Author: Sam Rushing
+
+.. contents::
+   :depth: 2
+   :backlinks: top
+.. section-numbering::
+
+Shrapnel/Coro is a highly scalable cooperative threading facility for CPython.
+
+Intro
+=====
+
+Shrapnel is a library for high-performance concurrency.  It uses
+coroutines to implement user threads on top of either kqueue (FreeBSD,
+OS X) or /dev/epoll (linux), and is written mostly in Pyrex/Cython,
+supporting both 32-bit and 64-bit platforms.  It is the culmination of
+about 8 years of work at IronPort Systems, a provider of high-speed
+mail appliances.  It was open-sourced by Cisco Systems in late 2011.
+
+Features
+--------
+
+ * Lightweight threads, event-driven scheduler.
+ * Underneath: non-blocking operations on descriptors, like sockets and pipes.
+ * On top, synchronous API for straight-line, simple code.
+ * Highly scalable - tens or hundreds of thousands of connections/threads.
+ * Thread synchronization primitives, like mutexes, semaphores, etc...
+ * Wait on kqueue events like file/directory changes, signals, processes, etc... [kqueue only]
+ * DNS stub resolver (full-fledged resolver may be forthcoming)
+ * HTTP server and client
+ * RPC system
+ * Support for TLS via tlslite (openssl interface may be forthcoming)
+ * other protocols/codecs: ldap, asn1, ftp, mysql, postgres, AMQP_.
+ * `MIT License`_.
+ 
+.. _MIT License: http://www.opensource.org/licenses/mit-license.html
+.. _AMQP: https://github.com/samrushing/amqp-shrapnel
+
+The Name
+--------
+
+`Shrapnel` is the name of the implementation.  The python package that
+it implements is ``coro``.  It's actually the third implementation of
+the coro package written at IronPort - previous versions were written
+in C using a painful type of continuation-passing style, and relied on
+variants of Stackless Python.
+
+
+Installing
+----------
+
+Requirements:
+
+ * Cython (>=0.12.1)
+ * distribute (>=0.6.16)
+
+Install with ``pip install`` *or*
+alternatively download shrapnel from
+https://github.com/ironport/shrapnel and do the usual ``python
+setup.py build; python setup.py install`` procedure.
+
+
+Basics
+======
+
+Event Loop
+----------
+
+Everything runs in the event loop.  So the last thing your ``__main__`` script will do is always::
+
+  coro.event_loop()
+
+Calling this function starts the scheduler, which enters a loop continually running threads that are ready to run, feeding new waitable events to the operating system, and waiting for events to be triggered.  When an event is triggered, the thread waiting on that event is awakened.
+
+Interaction
+-----------
+
+Because everything runs in the event loop, you can't interact with the normal python prompt.  But you can interact via the 'backdoor'.  The backdoor interface is crucial to development with shrapnel.  It allows you to open one or more telnet sessions into the system and interact with a python prompt there.  So a common pattern in __main__ is this:
+
+.. sourcecode:: python
+
+    if __name__ == '__main__':
+        import coro
+        import coro.backdoor
+        coro.spawn (coro.backdoor.serve, unix_path='/tmp/xx.bd')
+        coro.event_loop()
+
+
+.. sidebar:: Note!
+
+    Use the full path.  You can't cd into /tmp and ``"$telnet xx.bd"``.
+
+Once this is running, open another terminal window and::
+
+    $ telnet /tmp/xx.bd
+
+
+Go ahead and run ``shrapnel/docs/tutorial/t0.py`` now, we'll use it in the following demonstration::
+
+  $ cd shrapnel/docs/tutorial/
+  $ python t0.py
+  1: Sat Mar 31 16:28:44 2012 Backdoor started on unix socket /tmp/xx.bd
+
+In another window::
+
+  $ telnet /tmp/xx.bd 
+  Trying /tmp/xx.bd...
+  Connected to (null).
+  Escape character is '^]'.
+  Python 2.7.2 (default, Mar 10 2012, 12:30:07) 
+  [GCC 4.2.1 Compatible Clang 3.1 (trunk 149115)]
+  Copyright (c) 2001-2011 Python Software Foundation.
+  All Rights Reserved. [etc]
+  >>> 
+
+
+Output
+------
+
+Note the behavior of I/O to sys.stdout/stderr when using the back door::
+
+    >>> print "Howdy"
+    Howdy
+
+and::
+
+    >>> sys.stdout.write ("Hello\n")
+    Hello
+    >>> 
+
+i.e, they print to the terminal, not the main console.
+
+To send debugging output to the *console*, use ``coro.write_stderr()`` and ``coro.print_stderr()``.
+
+From the back door you can poke around in the internals of the system while it's running::
+
+    >>> coro.event_map
+    {<kevent_key filter=-1 ident=4>: <kevent_target status=1 index=0 target=<coro #1 name='<function serve at 0x1007e1de8>' dead=0 started=1 scheduled=0 at     0x1005c1500> flags=0>, ...}
+    >>> 
+    >>> 
+    >>> coro.where_all()
+    {1: ('<function serve at 0x1007e1de8>', <coro #1 name='<function serve at 0x1007e1de8>' dead=0 started=1 scheduled=0 at 0x1005c1500>, '[coro/backdoor.py     serve|224]'), ...}
+    >>> 
+    >>> 
+
+
+
+Sleeping
+--------
+
+The sleep_relative() function allow you to put a thread to sleep for a time::
+
+    >>> coro.sleep_relative (5)
+    [5 second pause]
+    >>>
+
+Starting a New Thread
+---------------------
+
+Start a new thread with ``coro.spawn()``::
+
+    >>> def thing():
+    ...   for x in range (10):
+    ...     coro.write_stderr ('%d\n' % (x,))
+    ...     coro.sleep_relative (1)
+    ... 
+    >>> coro.spawn (thing)
+    <coro #5 name='<function thing at 0x10152af50>' dead=0 started=0 scheduled=1 at 0x1005f97b0>
+    >>> 
+
+In the main window you should see a new digit printed every second.
+
+``coro.spawn()`` takes a callable object, args, and keyword args:
+
+.. sourcecode:: python
+
+    coro.spawn (fun0, arg0, arg1, kwd0=val0, kwd1=val1)
+
+
+Starting A *Lot* of New Threads
+-------------------------------
+
+Start up 1000 threads::
+
+    >>> import random
+    >>> def thing():
+    ...   t = random.randrange (0, 15)
+    ...   coro.sleep_relative (t)
+    ...   coro.write_stderr ('*')
+    ... 
+    >>> for x in range (1000):
+    ...   coro.spawn (thing)
+    ... 
+    >>> 
+
+Over the next 15 seconds you should see groups of ``'*'`` characters sent to the main window.
+
+Servers and Clients
+===================
+
+Echo Server
+-----------
+
+Creating a server is easy (see `docs/tutorial/t1.py`_):
+
+.. sourcecode:: python
+
+    import coro
+    import coro.backdoor
+    
+    def session (conn, addr):
+        while 1:
+            block = conn.recv (1000)
+            if not block:
+                break
+            else:
+                conn.send (block)
+    
+    def serve (port=9000):
+        s = coro.tcp_sock()
+        s.bind (('', port))
+        s.listen (50)
+        while 1:
+            conn, addr = s.accept()
+            coro.spawn (session, conn, addr)
+    
+    if __name__ == '__main__':
+        coro.spawn (coro.backdoor.serve, unix_path='/tmp/xx.bd')
+        coro.spawn (serve)
+        coro.event_loop()
+
+.. _docs/tutorial/t1.py: tutorial/t1.py
+
+You can telnet into that server::
+
+    $ telnet localhost 9000
+    Trying 127.0.0.1...
+    Connected to localhost.
+    Escape character is '^]'.
+    asdf
+    asdf
+    asdf
+    asdf
+    asdf
+
+[Hit ``Ctrl-], c, <return>`` to close the connection]
+
+Timeouts
+--------
+
+One of the nicer features of shrapnel is ``with_timeout()``.  Use
+``with_timeout()`` around any function call:
+
+.. sourcecode:: python
+
+    result = thing.db.query ("SELECT * FROM CANDYBIN;")
+
+with a 30-second timeout becomes:
+
+.. sourcecode:: python
+
+    result = coro.with_timeout (30, thing.db.query, "SELECT * FROM CANDYBIN;")
+
+If the function hasn't returned within 30 seconds, it will raise
+``coro.TimeoutError``:
+
+.. sourcecode:: python
+
+    try:
+       r = coro.with_timeout (30, function, arg0, arg1, ...)
+    except coro.TimeoutError:
+       coro.write_stderr ("Hey, that took too long!\n")
+
+Multiple layers of timeouts work as expected.
+
+.. note::
+
+    Try editing the echo server from above, adding a timeout to the
+    ``conn.recv (1000)`` call.  Make it so that it exits the loop and
+    closes the connection if nothing is typed within 10 seconds.
+
+
+Exiting The Event Loop
+----------------------
+
+You can tell the system to exit::
+
+    >>> coro.set_exit()
+    >>> Connection closed by foreign host.
+
+.. note::
+
+    Try editing the echo server from above, so that it'll exit the
+    event loop when it receives the string ``quit``.
+
+Echo Client
+-----------
+
+It's difficult to really beat on that server with your own fingers (and telnet).
+How about a client that'll exercise it a little (see `docs/tutorial/t2.py`_):
+
+.. sourcecode:: python
+
+    import coro
+    
+    def client (ip='127.0.0.1', port=9000):
+        s = coro.tcp_sock()
+        s.connect ((ip, port))
+        for i in range (10):
+            s.send ('howdy there\r\n')
+            assert (s.recv_exact (13) == 'howdy there\r\n')
+        coro.write_stderr ('.')
+        s.close()
+    
+    if __name__ == '__main__':
+        for i in range (100):
+            coro.spawn (client)
+        coro.event_loop()
+
+.. _docs/tutorial/t2.py: tutorial/t2.py
+
+Hit Ctrl-C to exit.
+
+You should just see a hundred dots in the main window.  You might get connection reset errors if the listen() parameter in the server wasn't high enough.  If so, you could put some calls to sleep_relative() in there to stagger the creation of the clients.
+
+
+Proxy Server
+------------
+
+This is a handy little server that lets you 'spy' on protocols.  It's
+very handy when implementing protocols. See `docs/tutorial/proxy.py`_.
+
+.. _docs/tutorial/proxy.py: tutorial/proxy.py
+
+.. sourcecode:: python
+
+    import coro
+    W = coro.write_stderr
+    
+    class session:
+        counter = 0
+        def __init__ (self, conn, addr, saddr):
+            self.conn = conn
+            self.addr = addr
+            self.saddr = saddr
+            self.id = session.counter
+            session.counter += 1
+            self.proxy = coro.tcp_sock()
+            self.proxy.connect (saddr)
+            coro.spawn (self.feed, self.conn, self.proxy, '<==')
+            coro.spawn (self.feed, self.proxy, self.conn, '==>')
+    
+        def feed (self, c0, c1, dir):
+            try:
+                while 1:
+                    block = c0.recv (1000)
+                    W ('%s %d %r\n' % (dir, self.id, block))
+                    if not block:
+                        break
+                    else:
+                        c1.send (block)
+            finally:
+                c0.close()
+    
+    def serve (saddr):
+        ip, port = saddr
+        s = coro.tcp_sock()
+        s.bind (('0.0.0.0', port + 9000))
+        s.listen (5)
+        while 1:
+            conn, caddr = s.accept()
+            coro.spawn (session, conn, caddr, saddr)
+                    
+    if __name__ == '__main__':
+        import sys
+        if len (sys.argv) < 3:
+            print 'Usage: %s <server-host> <server-port>' % sys.argv[0]
+        else:
+            coro.spawn (serve, (sys.argv[1], int (sys.argv[2])))
+            coro.event_loop()
+
+
+Let's say you want to spy on an HTTP connection::
+
+    $ python proxy.py 72.52.84.226 80
+
+The proxy works by adding 9000 to the port number you're connecting to.
+
+Try this link: http://localhost:9080/tutorial_hello.html
+
+Profiler
+========
+
+Shrapnel comes with an efficient and comprehensive profiler that
+accounts for the resources used by each thread. On most platforms it
+uses the RDTSC instruction to gather accurate timings with low
+overhead.  It profiles both Python and Cython code:
+
+.. sourcecode:: python
+
+    import coro.profiler
+    #coro.event_loop()
+    coro.profiler.go (coro.event_loop)
+
+By default it collects data from the ``rusage()`` facility and RDTSC,
+see the documentation for details.
+
+When the function you are profiling has exited, it will dump a binary
+file containing the results (default: ``/tmp/coro_profile.bin``),
+which you can post-process using the ``coro.print_profile`` module::
+
+    $ python coro/print_profile.py /tmp/coro_profile.bin  > /tmp/p0.html
+
+Pull that up in your browser, you'll find aggregate and non-aggregate tables, along with a call graph.
+
+Non-Aggregate Timings
+
++------+--------------------+---------------+-------------------+---------------------+-------------------+------------------+---------------+---------+---------+--------+--------+-------------------------------------+
+|calls |        ticks       |ticks/call     |   utime           |      utime/call     |  stime            | stime/call       | minflt        |  majflt | oublock | msgsnd | msgrcv |         Function                    |
++======+====================+===============+===================+=====================+===================+==================+===============+=========+=========+========+========+=====================================+
+|0     | 29552069532        | 29552069532   |0.022320           |    0.02232          | 0.031529          |        0.031529  |      0        |     0   |    0    |   0    |   0    |     <wait>                          |
++------+--------------------+---------------+-------------------+---------------------+-------------------+------------------+---------------+---------+---------+--------+--------+-------------------------------------+
+|4540  |299809652 (15.86%)  |       66037   |0.118307 (16.70%)  |     0.000026        | 0.013881 (10.17%) |      0.000003    |    2 (4.88%)  |     0   |    0    |   0    |   0    |   python/worms.py:move:141          |
++------+--------------------+---------------+-------------------+---------------------+-------------------+------------------+---------------+---------+---------+--------+--------+-------------------------------------+
+|0     | 227071913 (12.01%) |   227071913   |0.093381 (13.18%)  |      0.093381       |  0.010697 (7.84%) |        0.010697  |     3 (7.32%) |     0   |    0    |   0    |   0    |    <main>                           |
++------+--------------------+---------------+-------------------+---------------------+-------------------+------------------+---------------+---------+---------+--------+--------+-------------------------------------+
+|4783  |192461416 (10.18%)  |    40238      |0.072527 (10.24%)  |     0.000015        | 0.012591 (9.22%)  |      0.000003    |    1 (2.44%)  |     0   |    0    |   0    |   0    |   python2.7/random.py:randrange:173 |
++------+--------------------+---------------+-------------------+---------------------+-------------------+------------------+---------------+---------+---------+--------+--------+-------------------------------------+
+|2420  | 171570517 (9.08%)  |     70896     |0.069622 (9.83%)   |      0.000029       |  0.006048 (4.43%) |        0.000002  |     1 (2.44%) |     0   |    0    |   0    |   0    |    python/worms.py:draw:185         |
++------+--------------------+---------------+-------------------+---------------------+-------------------+------------------+---------------+---------+---------+--------+--------+-------------------------------------+
+
+From the call graph section::
+  
+  __builtin__:dict.has_key -- ticks=15234 utime=6e-06 stime=1e-06
+           3/3          (100.0%) coro/__init__.py:spawn:337
+                3           __builtin__:dict.has_key
+  __builtin__:file.write -- ticks=263623 utime=4.1e-05 stime=7.5e-05
+           7/7          (100.0%) python/worms.py:status:230
+                7           __builtin__:file.write
+  __builtin__:len -- ticks=28508261 utime=0.010467 stime=0.002547
+          14/4884       (00.3%) python/worms.py:status:230
+         330/4884       (06.8%) python2.7/random.py:choice:272
+        4540/4884       (93.0%) python/worms.py:move:141
+             4884           __builtin__:len
+  [...]
+
+
+Example of the full `profiler output`_.  Note: each graph may be [re]sorted by clicking on a column header.
+
+.. _profiler output: sample_profile.html
+
+
+The Killer Demo
+===============
+
+See `docs/tutorial/worms.py`_ for a fun demo.  Run the script from
+one terminal, and telnet into it from another terminal with a nice
+large window (your terminal needs to support ANSI escape codes).  
+
+Each worm is its own thread, and each socket client has a separate
+view into the shared 'arena'.  This demo can easily handle hundreds of
+separate worms (though things tend to get crowded)::
+
+  +=========================================================================+
+  |                                                              **********d|
+  |               9                                                         |
+  |               9                                                         |
+  |               9                                                         |
+  |               9                                                         |
+  |               9                                                         |
+  |               9                                                         |
+  |               9                                                         |
+  |               9                                                         |
+  |               9                                                         |
+  |               9                                                         |
+  |               9                                                         |
+  |                                                                         |
+  |                                                                         |
+  |                                 b                         a             |
+  |                                 b                         a             |
+  |                                 b                         a             |
+  |                                 b                         a      1      |
+  |          eeeeee                 b                         a      1      |
+  |               e                 b                         a      1      |
+  |               e                 b                         a1111111      |
+  |               e                 b                         a1            |
+  |               e                 b                         a             |
+  |               e                 b                         a             |
+  |                                 b                         a             |
+  |                                                                f        |
+  |                                                                f        |
+  |                                                                f        |
+  |                                                                f        |
+  |                                                                f        |
+  |                                                                ffffff   |
+  +=========================================================================+
+   keys: [q]uit [r]edraw [n]ew [c]ull [l]engthen [h]offa
+
+.. _docs/tutorial/worms.py: tutorial/worms.py
+
+Here's the code controlling each worm's movement:
+
+.. sourcecode:: python
+
+    def go (self):
+        try:
+            while not self.exit:
+                coro.sleep_relative (self.speed / 10000.0)
+                if random.randrange (0,20) == 10:
+                    if not self.turn():
+                        return
+                else:
+                    nx, ny = self.update()
+                    while self.arena[(nx,ny)] != ' ':
+                        if not self.turn():
+                            return
+                        nx, ny = self.update()
+                    self.move ((nx, ny))                        
+        finally:
+            self.arena.worms.remove (self)
+
+
+To come: a separate tutorial on hardening servers against attack.  I
+think this would be a great example to work with.
+
+
+Details
+=======
+
+Exceptions
+----------
+
+What happens when there's an unhandled exception in a thread?::
+
+    >>> def thing():
+    ...   return 1/0
+    ... 
+    >>> coro.spawn (thing)
+    <coro #205 name='<function thing at 0x1007e6758>' dead=0 started=0 scheduled=1 at 0x1005cf040>
+    >>> 
+
+You should see something like this in the main window::
+
+    205: Sat Mar 31 17:29:06 2012 thread 205 (<function thing at 0x1007e6758>): error 
+    '(\'<coro.backdoor.backdoor instance at 0x1007decf8> thing|2\', 
+    "<type \'exceptions.ZeroDivisionError\'>", \'integer division or modulo by zero\', 
+    \'[_coro.pyx coro._coro._wrap1 (coro/_coro.c:8821)|800] [<coro.backdoor.backdoor instance at 0x1007decf8> thing|2]\')'
+
+The default exception handler for a thread prints a timestamp, some info about the thread that crashed, and a compact, one-line traceback.
+
+You can replace the default handler with ``coro.set_exception_notifier()``.
+
+
+Latency Warnings
+----------------
+
+It's important that no thread monopolizes the CPU for too long.  This
+can happen if you inadvertently call a blocking system function (e.g.,
+filesystem I/O).  To assist you in finding bugs that do this, the
+scheduler will print out a warning like this::
+
+  Wed Apr  4 00:29:01 2012 High Latency: (5.449s) for <coro #4 name='bad thread' at 0x1003ceaa0>
+
+Any thread that holds the CPU for more than 0.2s will trigger the
+warning.  You can change the trigger value with ``coro.set_latency_warning()``.
+
+SimultaneousError
+-----------------
+
+If two threads try to perform the same I/O operation (technically,
+wait on the same kevent), this will trigger a ``SimultaneousError``::
+
+  >>> coro.x.recv (100)
+  Traceback (most recent call last):
+    File "/usr/local/lib/python2.7/site-packages/coro/backdoor.py", line 144, in parse
+      result = eval (co, env)
+    File "<coro.backdoor.backdoor instance at 0x100624ef0>", line 1, in <module>
+    File "socket.pyx", line 580, in coro._coro.sock.recv (coro/_coro.c:20208)
+    File "socket.pyx", line 1113, in coro._coro.sock._wait_for_read (coro/_coro.c:23549)
+    File "poller.pyx", line 326, in coro._coro.queue_poller._wait_for_read (coro/_coro.c:15292)
+    File "poller.pyx", line 318, in coro._coro.queue_poller._wait_for_with_eof (coro/_coro.c:15204)
+    File "poller.pyx", line 342, in coro._coro.queue_poller._wait_for (coro/_coro.c:15516)
+    File "poller.pyx", line 304, in coro._coro.queue_poller.set_wait_for (coro/_coro.c:15056)
+  SimultaneousError: <SimultaneousError co=<coro #6 name='backdoor session' dead=0 started=1 scheduled=0 at 0x1003ceaa0> other=<coro #5 name='backdoor session' dead=0 started=1 scheduled=0 at 0x1003d0080> event=<kevent_key filter=-1 ident=0>>
+  >>> 
+
+You can easily avoid this problem by isolating particular events to
+their own thread.  For example, you can have one thread that *reads*
+from a socket, while another *writes* to it.  You can combine
+identical events from multiple threads by using one of the
+synchronization primitives.  A common idiom uses a ``coro.fifo``:
+
+.. sourcecode:: python
+
+    def writer (self):
+        while not self.exit:
+            data = self.fifo.pop()
+            if data is None:
+                break
+            else:
+                self.conn.send (data)
+
+In this example we use a sentinel (``None``) to force the fifo to wake
+up and exit the loop.  This is similar to a generator's use of ``StopIteration``.
+
+
+Things To Avoid
+---------------
+
+Blocking calls.  Slow file I/O.  Not closing descriptors.  *Threads*. etc.
+
+
+How it Works
+------------
+
+Shrapnel works by using two (or more) C stacks.  The first stack (the
+default one from libc) runs the scheduler, which is responsible for
+switching out coro threads, managing the timed-events queue, and
+calling kevent (or hitting /dev/epoll).  The second stack is where
+coro threads run.  When it's time for a thread to run, its stack
+contents are copied from the heap onto the second stack, and a small
+amount of assembly code (similar to the ``ucontext`` facility)
+resumes it.  When a thread yields, the portion of the stack used by
+that thread is evacuated into the heap.
+
+.. image:: shrapnel.svg
+
+This design allows Shrapnel to work with a completely stock CPython.
+It has been used continuously with Python 2.3 to 2.7, and can usually
+be linked as a shared library against the platform's OEM install of
+Python.
+
+
+Credits
+=======
+
+[Get a comprehensive list of everyone that's contributed to shrapnel,
+maybe with home page links?]
+
+..
+   Local Variables:
+   compile-command: "rst2html.py  --embed-stylesheet --stylesheet-path=style.css  tutorial.rst tutorial.html"
+   End: