/soc/2012/michael/android: 435f55eca061: Documented the main pur...

[Michael Zangl]

Changeset: 435f55eca06126a0d30846fcf80fe9e884cb3d77
Author:	 Michael Zangl <michael at soc.pidgin.im>
Date:	 2012-08-20 16:02 +0200
Branch:	 soc.2012.android
URL: http://hg.pidgin.im/soc/2012/michael/android/rev/435f55eca061

Description:

Documented the main purple thread.

diffstat:

 android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/thread/AbstractWaitableRunnable.java |  18 ++-
 android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/thread/PurpleThread.java             |  61 ++++++++-
 android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/thread/WaitableRunnableRunner.java   |   3 +-
 3 files changed, 67 insertions(+), 15 deletions(-)

diffs (186 lines):

diff --git a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/thread/AbstractWaitableRunnable.java b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/thread/AbstractWaitableRunnable.java
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/thread/AbstractWaitableRunnable.java
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/thread/AbstractWaitableRunnable.java
@@ -2,22 +2,29 @@ package im.pidgin.libpurple.core.thread;
 
 /**
  * An abstract implementation of {@link WaitableRunnable}
- * 
+ *
  * @author michaelz
- * 
+ *
  */
 public abstract class AbstractWaitableRunnable implements WaitableRunnable {
 	private final Object mutex = new Object();
+
+	/**
+	 * Boolean indicating if we have run.
+	 */
 	private boolean wasRun = false;
 
+	/**
+	 * Counter counting how many objects are waiting for us to run.
+	 */
 	private int waitForRunning = 0;
 
 	@Override
 	public void run() {
 		execute();
 		synchronized (mutex) {
+			wasRun = true;
 			mutex.notifyAll();
-			wasRun = true;
 		}
 		executionFinished();
 	}
@@ -29,7 +36,10 @@ public abstract class AbstractWaitableRu
 	protected void executionFinished() {
 	}
 
-	protected abstract void execute();;
+	/**
+	 * Executes the task that should be run.
+	 */
+	protected abstract void execute();
 
 	@Override
 	public void waitFor() throws InterruptedException {
diff --git a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/thread/PurpleThread.java b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/thread/PurpleThread.java
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/thread/PurpleThread.java
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/thread/PurpleThread.java
@@ -7,12 +7,12 @@ import java.util.concurrent.LinkedBlocki
  * This is the main thread of libpurple. It is used internally to execute
  * libpurple functions that can be called from everywhere, because libpurple is
  * not thread safe.
- * 
+ *
  * @author michaelz
- * 
  */
 public class PurpleThread {
-	private final BlockingQueue<WaitableRunnable> waiting = new LinkedBlockingQueue<WaitableRunnable>();
+	private final BlockingQueue<WaitableRunnable> waiting =
+	        new LinkedBlockingQueue<WaitableRunnable>();
 	private final Object purpleMutex = new Object();
 	private final Object lastScheduledMutex = new Object();
 	private WaitableRunnable lastScheduled;
@@ -27,7 +27,7 @@ public class PurpleThread {
 	 * really short calls. This method blocks until the thread is in a safe
 	 * state and returns a mutex to you. There may be other tasks scheduled
 	 * between you got the mutex and you got the lock.
-	 * 
+	 *
 	 * @return A synchronisation mutex.
 	 * @throws InterruptedException
 	 */
@@ -46,6 +46,11 @@ public class PurpleThread {
 		return purpleMutex;
 	}
 
+	/**
+	 * This class is the main loop of the purple thread.
+	 *
+	 * @author michael
+	 */
 	private class PurpleThreadRunner implements Runnable {
 		@Override
 		public void run() {
@@ -64,16 +69,22 @@ public class PurpleThread {
 
 				} catch (InterruptedException e) {
 					System.out.println("Purple thread was interrupted,"
-							+ " but is continuing.");
+					        + " but is continuing.");
 				} catch (Throwable t) {
 					System.err.println("Purple thread catched throwable: "
-							+ t.getMessage());
+					        + t.getMessage());
 					t.printStackTrace(System.err);
 				}
 			}
 		}
 	}
 
+	/**
+	 * Schedules a waitable runnable to be run somewhere in the future.
+	 *
+	 * @param r
+	 *            The runnable to schedule.
+	 */
 	public void schedule(WaitableRunnable r) {
 		synchronized (lastScheduledMutex) {
 			waiting.offer(r);
@@ -81,23 +92,55 @@ public class PurpleThread {
 		}
 	}
 
+	/**
+	 * Schedules a normal runnable and waits for its execution.
+	 *
+	 * @param r
+	 *            The runnable to schedule.
+	 * @throws InterruptedException
+	 *             If the current thread was interrupted while waiting.
+	 */
 	public void scheduleAndWaitFor(Runnable r) throws InterruptedException {
 		WaitableRunnableRunner waitable = new WaitableRunnableRunner(r);
 		scheduleAndWaitFor(waitable);
 	}
 
+	/**
+	 * Schedules a waitable runnable and waits for its execution.
+	 *
+	 * @param waitable
+	 *            The waitable runnable to schedule.
+	 * @throws InterruptedException
+	 *             If the current thread was interrupted while waiting.
+	 * @see {@link #scheduleAndWaitFor(Runnable)}
+	 */
 	public void scheduleAndWaitFor(WaitableRunnable waitable)
-			throws InterruptedException {
+	        throws InterruptedException {
 		schedule(waitable);
 		waitable.waitFor();
 	}
 
-	public void scheduleAndWaitForUninterruptable(WaitableRunnable r) {
+	/**
+	 * Schedules a runnable and waits for its execution. If the thread is
+	 * interrupted, it just continues to wait.
+	 *
+	 * @param r
+	 *            The normal runnable to schedule.
+	 */
+	public void scheduleAndWaitForUninterruptable(Runnable r) {
 		WaitableRunnableRunner waitable = new WaitableRunnableRunner(r);
 		scheduleAndWaitForUninterruptable(waitable);
 	}
 
-	private void scheduleAndWaitForUninterruptable(WaitableRunnableRunner waitable) {
+	/**
+	 * Schedules a waitable runnable and waits for its execution. If the thread
+	 * is interrupted, it just continues to wait.
+	 *
+	 * @param waitable
+	 *            The waitable runnable to schedule.
+	 * @see #scheduleAndWaitForUninterruptable(Runnable)
+	 */
+	public void scheduleAndWaitForUninterruptable(WaitableRunnable waitable) {
 		schedule(waitable);
 		boolean finished = false;
 		while (!finished) {
diff --git a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/thread/WaitableRunnableRunner.java b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/thread/WaitableRunnableRunner.java
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/thread/WaitableRunnableRunner.java
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/thread/WaitableRunnableRunner.java
@@ -2,9 +2,8 @@ package im.pidgin.libpurple.core.thread;
 
 /**
  * A runnable we can wait for. We might use an object pool for this.
- * 
+ *
  * @author michaelz
- * 
  */
 public class WaitableRunnableRunner extends AbstractWaitableRunnable {