pidgin/android/android

Documented the main purple thread.
soc.2012.android
2012-08-20, Michael Zangl
435f55eca061
Parents 879063803cab
Children e0ee0749df86
Documented the main purple thread.
3 files changed, 67 insertions(+), 15 deletions(-)
  • +14 -4
    android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/thread/AbstractWaitableRunnable.java
  • +52 -9
    android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/thread/PurpleThread.java
  • +1 -2
    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/AbstractWaitableRunnable.java Mon Aug 20 16:01:53 2012 +0200
    +++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/thread/AbstractWaitableRunnable.java Mon Aug 20 16:02:15 2012 +0200
    @@ -2,22 +2,29 @@
    /**
    * 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 @@
    protected void executionFinished() {
    }
    - protected abstract void execute();;
    + /**
    + * Executes the task that should be run.
    + */
    + protected abstract void execute();
    @Override
    public void waitFor() throws InterruptedException {
    --- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/thread/PurpleThread.java Mon Aug 20 16:01:53 2012 +0200
    +++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/thread/PurpleThread.java Mon Aug 20 16:02:15 2012 +0200
    @@ -7,12 +7,12 @@
    * 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 @@
    * 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 @@
    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 @@
    } 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 @@
    }
    }
    + /**
    + * 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) {
    --- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/thread/WaitableRunnableRunner.java Mon Aug 20 16:01:53 2012 +0200
    +++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/core/thread/WaitableRunnableRunner.java Mon Aug 20 16:02:15 2012 +0200
    @@ -2,9 +2,8 @@
    /**
    * A runnable we can wait for. We might use an object pool for this.
    - *
    + *
    * @author michaelz
    - *
    */
    public class WaitableRunnableRunner extends AbstractWaitableRunnable {