.. -*- restructuredtext -*-

====================
statdaemon extension
====================

This is an extension for speeding up ``hg status`` and related
commands that traverse the filesytem. This is done by spawning a
daemon that listens for filesystem events and keeps an up-to-date view
of the filesystem. When ``hg status`` is run, it contacts the daemon
and quickly retrives the stat data it needs.

Design
======

The extension is similar to the `inotify extension`_ in that it
listens for file system events. However, unline inotify, the
statdaemon knows only caches filesystem information and knows nothing
about Mercurial. The hope is that this will make the design simpler
and correct.

Server
------

The server (daemon) is launched automaticaly when needed but it can
also be started by hand with ``hg statdaemon``. This is useful for
debugging.

When started, the server listens on a random port for incoming
requests. Clients can send ``listdir`` and ``fetchall`` queries to the
server:

* ``listdir(path)``: The server begins watching ``path`` for file
  system events and sends back the output of
  ``mercurial.osutil.listdir(path)``.

* ``fetchall()``: The server sends back all cached data. The client
  should call this initially to save the number of round-trips.

Client
------

The extension wraps ``dirstate.status`` to intercept status
calls. When status data is needed, the client will first call
``fetchall()`` to retrive a snapshot of status data for the entire
working copy. The client caches this locally.

Calls to ``osutil.listdir`` are intercepted and will first look in the
cache for status data. If not found there, the server is queried with
a ``listdir(path)`` query so that it can update its cache. This will
make the next ``hg status`` call fast since the server will now keep
track of the needed paths.

.. _inotify extension: http://mercurial.selenic.com/wiki/InotifyExtension

Compatibility
=============

Mercurial
---------

The extension has been tested with Mercurial 1.9 and
later. Development is done against Mercurial 2.3.

Platforms
---------

The extension currently has support for the following platforms:

* **Windows:** The extensio has been tested on Windows XP and Windows
  7. There are no further dependencies apart from Python 2.5 (due to
  the use of ``ctypes``).

* **Linux:** The extension has been tested on Debian Wheezy. The
  extension requires pyinotify_ package (found in ``python-pyinotify``
  on Debian).

.. _pyinotify: https://github.com/seb-m/pyinotify


License
=======

The extension may be used and distributed according to the terms of
the GNU General Public License version 2 or any later version.

Sponsoring
==========

This extension was written by `aragost Trifork`_. Feel free to contact
`aragost Trifork`_ to discuss any further improvements to the
extension.

Contact
=======

Martin Geisler <mg@aragost.com>

.. _aragost Trifork: http://aragost.com/