3 * StatusNet, the distributed open-source microblogging tool
5 * Abstract class for i/o managers
9 * LICENCE: This program is free software: you can redistribute it and/or modify
10 * it under the terms of the GNU Affero General Public License as published by
11 * the Free Software Foundation, either version 3 of the License, or
12 * (at your option) any later version.
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU Affero General Public License for more details.
19 * You should have received a copy of the GNU Affero General Public License
20 * along with this program. If not, see <http://www.gnu.org/licenses/>.
22 * @category QueueManager
24 * @author Evan Prodromou <evan@status.net>
25 * @author Sarven Capadisli <csarven@status.net>
26 * @author Brion Vibber <brion@status.net>
27 * @copyright 2009-2010 StatusNet, Inc.
28 * @license http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
29 * @link http://status.net/
32 abstract class IoManager
34 const SINGLE_ONLY = 0;
35 const INSTANCE_PER_SITE = 1;
36 const INSTANCE_PER_PROCESS = 2;
39 * Factory function to get an appropriate subclass.
41 public static function get() {
42 throw new MethodNotImplementedException(__METHOD__);
46 * Tell the i/o queue master if and how we can handle multi-site
50 * IoManager::SINGLE_ONLY
51 * IoManager::INSTANCE_PER_SITE
52 * IoManager::INSTANCE_PER_PROCESS
54 public static function multiSite()
56 return IoManager::SINGLE_ONLY;
60 * If in a multisite configuration, the i/o master will tell
61 * your manager about each site you'll have to handle so you
62 * can do any necessary per-site setup.
64 * The new site will be the currently live configuration during
67 public function addSite()
73 * This method is called when data is available on one of your
74 * i/o manager's sockets. The socket with data is passed in,
75 * in case you have multiple sockets.
77 * If your i/o manager is based on polling during idle processing,
78 * you don't need to implement this.
80 * @param resource $socket
81 * @return boolean true on success, false on failure
83 public function handleInput($socket)
89 * Return any open sockets that the run loop should listen
90 * for input on. If input comes in on a listed socket,
91 * the matching manager's handleInput method will be called.
93 * @return array of resources
101 * Maximum planned time between poll() calls when input isn't waiting.
102 * Actual time may vary!
104 * When we get a polling hit, the timeout will be cut down to 0 while
105 * input is coming in, then will back off to this amount if no further
108 * By default polling is disabled; you must override this to enable
109 * polling for this manager.
111 * @return int max poll interval in seconds, or 0 to disable polling
113 function pollInterval()
119 * Request a maximum timeout for listeners before the next idle period.
120 * Actual wait may be shorter, so don't go crazy in your idle()!
121 * Wait could be longer if other handlers performed some slow activity.
123 * Return 0 to request that listeners return immediately if there's no
124 * i/o and speed up the idle as much as possible; but don't do that all
125 * the time as this will burn CPU.
127 * @return int seconds
135 * Called by IoManager after each handled item or empty polling cycle.
136 * This is a good time to e.g. service your XMPP connection.
138 * Doesn't need to be overridden if there's no maintenance to do.
146 * The meat of a polling manager... check for something to do
147 * and do it! Note that you should not take too long, as other
148 * i/o managers may need to do some work too!
150 * On a successful hit, the next poll() call will come as soon
151 * as possible followed by exponential backoff up to pollInterval()
152 * if no more data is available.
154 * @return boolean true if events were hit
156 public function poll()
162 * Initialization, run when the queue manager starts.
163 * If this function indicates failure, the handler run will be aborted.
165 * @param IoMaster $master process/event controller
166 * @return boolean true on success, false on failure
168 public function start($master)
170 $this->master = $master;
175 * Cleanup, run when the queue manager ends.
176 * If this function indicates failure, a warning will be logged.
178 * @return boolean true on success, false on failure
180 public function finish()
186 * Ping iomaster's queue status monitor with a stats update.
187 * Only valid during input loop!
189 * @param string $counter keyword for counter to increment
191 public function stats($counter, $owners=array())
193 $this->master->stats($counter, $owners);