<?php
/*
- * Laconica - a distributed open-source microblogging tool
- * Copyright (C) 2008, Controlez-Vous, Inc.
+ * StatusNet - the distributed open-source microblogging tool
+ * Copyright (C) 2008, 2009, StatusNet, Inc.
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as published by
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
-define('CLAIM_TIMEOUT', 1200);
-
-if (!defined('LACONICA')) { exit(1); }
+if (!defined('STATUSNET') && !defined('LACONICA')) { exit(1); }
require_once(INSTALLDIR.'/lib/daemon.php');
require_once(INSTALLDIR.'/classes/Queue_item.php');
require_once(INSTALLDIR.'/classes/Notice.php');
+define('CLAIM_TIMEOUT', 1200);
+define('QUEUE_HANDLER_MISS_IDLE', 10);
+define('QUEUE_HANDLER_HIT_IDLE', 0);
+
+/**
+ * Base class for queue handlers.
+ *
+ * As extensions of the Daemon class, each queue handler has the ability
+ * to launch itself in the background, at which point it'll pass control
+ * to the configured QueueManager class to poll for updates.
+ *
+ * Subclasses must override at least the following methods:
+ * - transport
+ * - start
+ * - finish
+ * - handle_notice
+ *
+ * Some subclasses will also want to override the idle handler:
+ * - idle
+ */
class QueueHandler extends Daemon
{
- var $_id = 'generic';
-
- function QueueHandler($id=null)
+ function __construct($id=null, $daemonize=true)
{
+ parent::__construct($daemonize);
+
if ($id) {
$this->set_id($id);
}
}
+ /**
+ * How many seconds a polling-based queue manager should wait between
+ * checks for new items to handle.
+ *
+ * Defaults to 60 seconds; override to speed up or slow down.
+ *
+ * @return int timeout in seconds
+ */
+ function timeout()
+ {
+ return 60;
+ }
+
function class_name()
{
return ucfirst($this->transport()) . 'Handler';
return strtolower($this->class_name().'.'.$this->get_id());
}
- function get_id()
- {
- return $this->_id;
- }
-
- function set_id($id)
- {
- $this->_id = $id;
- }
-
+ /**
+ * Return transport keyword which identifies items this queue handler
+ * services; must be defined for all subclasses.
+ *
+ * Must be 8 characters or less to fit in the queue_item database.
+ * ex "email", "jabber", "sms", "irc", ...
+ *
+ * @return string
+ */
function transport()
{
return null;
}
+ /**
+ * Initialization, run when the queue handler starts.
+ * If this function indicates failure, the handler run will be aborted.
+ *
+ * @fixme run() will abort if this doesn't return true,
+ * but some subclasses don't bother.
+ * @return boolean true on success, false on failure
+ */
function start()
{
}
+ /**
+ * Cleanup, run when the queue handler ends.
+ * If this function indicates failure, a warning will be logged.
+ *
+ * @fixme run() will throw warnings if this doesn't return true,
+ * but many subclasses don't bother.
+ * @return boolean true on success, false on failure
+ */
function finish()
{
}
+ /**
+ * Here's the meat of your queue handler -- you're handed a Notice
+ * object, which you may do as you will with.
+ *
+ * If this function indicates failure, a warning will be logged
+ * and the item is placed back in the queue to be re-run.
+ *
+ * @param Notice $notice
+ * @return boolean true on success, false on failure
+ */
function handle_notice($notice)
{
return true;
}
- function db_dispatch() {
- do {
- $qi = Queue_item::top($this->transport());
- if ($qi) {
- $this->log(LOG_INFO, 'Got item enqueued '.common_exact_date($qi->created));
- $notice = Notice::staticGet($qi->notice_id);
- if ($notice) {
- $this->log(LOG_INFO, 'broadcasting notice ID = ' . $notice->id);
- # XXX: what to do if broadcast fails?
- $result = $this->handle_notice($notice);
- if (!$result) {
- $this->log(LOG_WARNING, 'Failed broadcast for notice ID = ' . $notice->id);
- $orig = $qi;
- $qi->claimed = null;
- $qi->update($orig);
- $this->log(LOG_WARNING, 'Abandoned claim for notice ID = ' . $notice->id);
- continue;
- }
- $this->log(LOG_INFO, 'finished broadcasting notice ID = ' . $notice->id);
- $notice->free();
- unset($notice);
- $notice = null;
- } else {
- $this->log(LOG_WARNING, 'queue item for notice that does not exist');
- }
- $qi->delete();
- $qi->free();
- unset($qi);
- $this->idle(0);
- } else {
- $this->clear_old_claims();
- $this->idle(5);
- }
- } while (true);
- }
-
- function stomp_dispatch() {
- require("Stomp.php");
- $con = new Stomp(common_config('queue','stomp_server'));
- if (!$con->connect()) {
- $this->log(LOG_ERR, 'Failed to connect to queue server');
- return false;
- }
- $queue_basename = common_config('queue','queue_basename');
- // subscribe to the relevant queue (format: basename-transport)
- $con->subscribe('/queue/'.$queue_basename.'-'.$this->transport());
-
- do {
- $frame = $con->readFrame();
- if ($frame) {
- $this->log(LOG_INFO, 'Got item enqueued '.common_exact_date($frame->headers['created']));
-
- // XXX: Now the queue handler receives only the ID of the
- // notice, and it has to get it from the DB
- // A massive improvement would be avoid DB query by transmitting
- // all the notice details via queue server...
- $notice = Notice::staticGet($frame->body);
-
- if ($notice) {
- $this->log(LOG_INFO, 'broadcasting notice ID = ' . $notice->id);
- $result = $this->handle_notice($notice);
- if ($result) {
- // if the msg has been handled positively, ack it
- // and the queue server will remove it from the queue
- $con->ack($frame);
- $this->log(LOG_INFO, 'finished broadcasting notice ID = ' . $notice->id);
- }
- else {
- // no ack
- $this->log(LOG_WARNING, 'Failed broadcast for notice ID = ' . $notice->id);
- }
- $notice->free();
- unset($notice);
- $notice = null;
- } else {
- $this->log(LOG_WARNING, 'queue item for notice that does not exist');
- }
- }
- } while (true);
-
- $con->disconnect();
- }
-
+ /**
+ * Setup and start of run loop for this queue handler as a daemon.
+ * Most of the heavy lifting is passed on to the QueueManager's service()
+ * method, which passes control back to our handle_notice() method for
+ * each notice that comes in on the queue.
+ *
+ * Most of the time this won't need to be overridden in a subclass.
+ *
+ * @return boolean true on success, false on failure
+ */
function run()
{
if (!$this->start()) {
+ $this->log(LOG_WARNING, 'failed to start');
return false;
}
+
$this->log(LOG_INFO, 'checking for queued notices');
- if (common_config('queue','subsystem') == 'stomp') {
- $this->stomp_dispatch();
- }
- else {
- $this->db_dispatch();
- }
+
+ $queue = $this->transport();
+ $timeout = $this->timeout();
+
+ $qm = QueueManager::get();
+
+ $qm->service($queue, $this);
+
+ $this->log(LOG_INFO, 'finished servicing the queue');
+
if (!$this->finish()) {
+ $this->log(LOG_WARNING, 'failed to clean up');
return false;
}
+
+ $this->log(LOG_INFO, 'terminating normally');
+
return true;
}
+ /**
+ * Called by QueueHandler after each handled item or empty polling cycle.
+ * This is a good time to e.g. service your XMPP connection.
+ *
+ * Doesn't need to be overridden if there's no maintenance to do.
+ *
+ * @param int $timeout seconds to sleep if there's nothing to do
+ */
function idle($timeout=0)
{
- if ($timeout>0) {
+ if ($timeout > 0) {
sleep($timeout);
}
}
- function clear_old_claims()
+ function log($level, $msg)
{
- $qi = new Queue_item();
- $qi->transport = $this->transport();
- $qi->whereAdd('now() - claimed > '.CLAIM_TIMEOUT);
- $qi->update(DB_DATAOBJECT_WHEREADD_ONLY);
- $qi->free();
- unset($qi);
+ common_log($level, $this->class_name() . ' ('. $this->get_id() .'): '.$msg);
}
- function log($level, $msg)
+ function getSockets()
{
- common_log($level, $this->class_name() . ' ('. $this->get_id() .'): '.$msg);
+ return array();
}
}