From a7ca96fcb7d20182e80afab3e4341f011aa56fdb Mon Sep 17 00:00:00 2001
From: Simon Rettberg
Date: Mon, 23 Jun 2014 20:18:24 +0200
Subject: Added doxygen comments to Taskmanager class

---
 inc/taskmanager.inc.php | 63 +++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 56 insertions(+), 7 deletions(-)

(limited to 'inc/taskmanager.inc.php')

diff --git a/inc/taskmanager.inc.php b/inc/taskmanager.inc.php
index 3862ac72..d9e890c6 100644
--- a/inc/taskmanager.inc.php
+++ b/inc/taskmanager.inc.php
@@ -6,6 +6,10 @@
 class Taskmanager
 {
 
+	/**
+	 * UDP socket used for communication with the task manager
+	 * @var resource
+	 */
 	private static $sock = false;
 
 	private static function init()
@@ -18,6 +22,15 @@ class Taskmanager
 		socket_connect(self::$sock, '127.0.0.1', 9215);
 	}
 
+	/**
+	 * Start a task via the task manager.
+	 *
+	 * @param string $task name of task to start
+	 * @param array $data data to pass to the task. the structure depends on the task.
+	 * @param boolean $async if true, the function will not wait for the reply of the taskmanager, which means
+	 *		the return value is just true (and you won't know if the task could acutally be started)
+	 * @return array struct representing the task status, or result of submit, false on communication error
+	 */
 	public static function submit($task, $data = false, $async = false)
 	{
 		self::init();
@@ -44,11 +57,22 @@ class Taskmanager
 		return $reply;
 	}
 
-	public static function status($taskId)
+	/**
+	 * Query status of given task.
+	 *
+	 * @param mixed $task task id or task struct
+	 * @return array status of task as array, or false on communication error
+	 */
+	public static function status($task)
 	{
+		if (is_array($task) && isset($task['id'])) {
+			$task = $task['id'];
+		}
+		if (!is_string($task))
+			return false;
 		self::init();
 		$seq = (string) mt_rand();
-		$message = "$seq, status, $taskId";
+		$message = "$seq, status, $task";
 		$sent = socket_send(self::$sock, $message, strlen($message), 0);
 		$reply = self::readReply($seq);
 		if (!is_array($reply))
@@ -56,6 +80,13 @@ class Taskmanager
 		return $reply;
 	}
 
+	/**
+	 * Wait for the given task's completion.
+	 *
+	 * @param type $task task to wait for
+	 * @param int $timeout maximum time in ms to wait for completion of task
+	 * @return array result/status of task, or false if it couldn't be queried
+	 */
 	public static function waitComplete($task, $timeout = 1500)
 	{
 		if (is_array($task) && isset($task['id'])) {
@@ -76,13 +107,19 @@ class Taskmanager
 				$done = true;
 				break;
 			}
-			usleep(150000);
+			usleep(100000);
 		}
 		if ($done)
 			self::release($task);
 		return $status;
 	}
 
+	/**
+	 * Check whether the given task can be considered failed.
+	 *
+	 * @param mixed $task task id or struct representing task
+	 * @return boolean true if task failed, false if finished successfully or still waiting/running
+	 */
 	public static function isFailed($task)
 	{
 		if (!is_array($task) || !isset($task['statusCode']) || !isset($task['id']))
@@ -113,17 +150,29 @@ class Taskmanager
 		Message::addError('task-error', $task['statusCode']);
 	}
 
-	public static function release($taskId)
+	/**
+	 * Release a given task from the task manager, so it won't keep the result anymore in case it's finished running.
+	 *
+	 * @param string $task task to release. can either be its id, or a struct representing the task, as returned
+	 * by ::submit() or ::status()
+	 */
+	public static function release($task)
 	{
+		if (is_array($task) && isset($task['id'])) {
+			$task = $task['id'];
+		}
+		if (!is_string($task))
+			return;
 		self::init();
 		$seq = (string) mt_rand();
-		$message = "$seq, release, $taskId";
+		$message = "$seq, release, $task";
 		socket_send(self::$sock, $message, strlen($message), 0);
 	}
 
 	/**
-	 * 
-	 * @param type $seq
+	 * Read reply from socket for given sequence number.
+	 *
+	 * @param string $seq
 	 * @return mixed the decoded json data for that message as an array, or null on error
 	 */
 	private static function readReply($seq)
-- 
cgit v1.2.3-55-g7522