Fishpoll
=======
Fishpoll is meant to deal with a common situation. You have a data source
(a version control repository, a database, etc). You have something built from
that data source (a web site, say). When the data source changes, you want
to rebuild.

The traditional thing to do is to run your update out of a cron job.
But even if you are running the script every minute, that's still a whole
minute you have to wait. So, fishpoll acts as a network daemon that allows
checking to be triggered explicitly by sending a message.

The latest version of this file can be found at:

 http://git.fishsoup.net/cgit/fishpoll/plain/README

To get the latest version of Fishpoll:

 git clone git://git.fishsoup.net/fishpoll

Send patches to Owen Taylor <otaylor@fishsoup.net>

Topics and Subjects
===================
The basic unit of checking with Fishpoll is the 'topic'. Each topic has
a handler script that is run to "check" that topic.

Sometimes you might want to have multiple things handled by the same topic
handler. When a topic is triggered over the network, a a list of "subjects"
can be provided. (If no subject is provided, a default subject of DEFAULT
is used.) These are simply passed as additional arguments to the
handler script.

Topic handlers
==============
fishpolld looks for in its handler directory (default /etc/fishpoll.d) for
topic handlers. Each topic handler is simply an executable script named
the same as the topic.

There can also be a configuration file for a topic named as the topic
name followed by '.conf'.

Only one instance of a handler script is run at a time. If a topic
is triggered (either from the network or from a configured interval) while
the previous instance is running, the subjects are queued up and run
when the previous instance finishes.

Topic configuration example
===========================
[fishpoll]
# Whether to run the handler once when fishpolld is started. Defaults
# to False
on_start = True

# How often to run the handler (in seconds) if not otherwise triggered.
# A negative value (the default) means never.
interval = 500

fishpolld usage
==============
Usage: fishpolld [options]

Options:

  -d, --debug

    If specified, do not daemonize and run in the background. Logging information
    (including stuff logged at the debug level) will be written to standard out.

  --pid-file=PID_FILE

    A filename into which to write the PID of daemon. Defaults to
    /var/run/fishpolld.pid. If empty, the PID will not be written.

  --handler-dir=HANDLER_DIR

    The directory in which to look for handler scripts and configuration scripts.

  --listen=HOST[:PORT]

    The address and (optionally) port to listen on. Defaults to '*' meaning to
    listen on all interfaces. If the port is not specified, uses port 27527.

fishpolld is very much a standard Unix daemon. It would normally be started
from an init script.

fishpoke usage
==============
Usage: fishpoke HOST[:PORT] TOPIC [SUBJECT...]

Options:
 No options currently

License
=======
Fishpoll is copyright (C) Owen Taylor 2009 and licensed under the GNU General
Public License. See the file COPYING for details.
