doc/runrst

hgweb: use separate repo instances per thread

Before this change, multiple threads/requests could share a
localrepository instance. This meant that all of localrepository needed
to be thread safe. Many bugs have been reported telling us that
localrepository isn't actually thread safe.

While making localrepository thread safe is a noble cause, it is a lot
of work. And there is little gain from doing so. Due to Python's GIL,
only 1 thread may be processing Python code at a time. The benefits
to multi-threaded servers are marginal.

Thread safety would be a lot of work for little gain. So, we're not
going to even attempt it.

This patch establishes a pool of repos in hgweb. When a request arrives,
we obtain the most recently used repository from the pool or create a
new one if none is available. When the request has finished, we put that
repo back in the pool.

We start with a pool size of 1. For servers using a single thread, the
pool will only ever be of size 1. For multi-threaded servers, the pool
size will grow to the max number of simultaneous requests the server
processes.

No logic for pruning the pool has been implemented. We assume server
operators either limit the number of threads to something they can
handle or restart the Mercurial process after a certain amount of
requests or time has passed.

#!/usr/bin/env python
#
# runrst - register custom roles and run correct writer
#
# Copyright 2010 Matt Mackall <[e-mail]> and others
#
# This software may be used and distributed according to the terms of the
# GNU General Public License version 2 or any later version.

"""usage: %s WRITER args...

where WRITER is the name of a Docutils writer such as 'html' or 'manpage'
"""

import sys
try:
    from docutils.parsers.rst import roles
    from docutils.core import publish_cmdline
    from docutils import nodes, utils
except ImportError:
    sys.stderr.write("abort: couldn't generate documentation: docutils "
                     "module is missing\n")
    sys.stderr.write("please install python-docutils or see "
                     "http://docutils.sourceforge.net/\n")
    sys.exit(-1)

def role_hg(name, rawtext, text, lineno, inliner,
            options={}, content=[]):
    text = "hg " + utils.unescape(text)
    linktext = nodes.literal(rawtext, text)
    parts = text.split()
    cmd, args = parts[1], parts[2:]
    if cmd == 'help' and args:
        cmd = args[0] # link to 'dates' for 'hg help dates'
    node = nodes.reference(rawtext, '', linktext,
                           refuri="hg.1.html#%s" % cmd)
    return [node], []

roles.register_local_role("hg", role_hg)

if __name__ == "__main__":
    if len(sys.argv) < 2:
        sys.stderr.write(__doc__ % sys.argv[0])
        sys.exit(1)

    writer = sys.argv[1]
    del sys.argv[1]

    publish_cmdline(writer_name=writer)