From b2a8e4ccae93e88ca83536eb8c2983fddd172706 Mon Sep 17 00:00:00 2001
From: Roland <rk@rkuhn.info>
Date: Tue, 6 Dec 2011 09:27:32 +0100
Subject: [PATCH] document requirements of our Scheduler service

---
 .../java/org/jboss/netty/akka/util/HashedWheelTimer.java | 4 ++++
 .../src/main/scala/akka/actor/ActorRefProvider.scala     | 4 ++++
 akka-actor/src/main/scala/akka/actor/ActorSystem.scala   | 4 ++++
 akka-actor/src/main/scala/akka/actor/Scheduler.scala     | 9 +++++++++
 4 files changed, 21 insertions(+)

diff --git a/akka-actor/src/main/java/org/jboss/netty/akka/util/HashedWheelTimer.java b/akka-actor/src/main/java/org/jboss/netty/akka/util/HashedWheelTimer.java
index 5b19e1f2eb..d0112ded79 100644
--- a/akka-actor/src/main/java/org/jboss/netty/akka/util/HashedWheelTimer.java
+++ b/akka-actor/src/main/java/org/jboss/netty/akka/util/HashedWheelTimer.java
@@ -76,6 +76,10 @@ import java.util.concurrent.locks.ReentrantReadWriteLock;
  * @version $Rev: 2297 $, $Date: 2010-06-07 10:50:02 +0900 (Mon, 07 Jun 2010) $
  *
  * The original implementation has been slightly altered to fit the specific requirements of Akka.
+ * 
+ * Specifically: it is required to throw an IllegalStateException if a job 
+ * cannot be queued. If no such exception is thrown, the job must be executed
+ * (or returned upon stop()).
  */
 public class HashedWheelTimer implements Timer {
     private final Worker worker = new Worker();
diff --git a/akka-actor/src/main/scala/akka/actor/ActorRefProvider.scala b/akka-actor/src/main/scala/akka/actor/ActorRefProvider.scala
index 51b2bd48af..2fae75983c 100644
--- a/akka-actor/src/main/scala/akka/actor/ActorRefProvider.scala
+++ b/akka-actor/src/main/scala/akka/actor/ActorRefProvider.scala
@@ -562,6 +562,10 @@ class LocalDeathWatch extends DeathWatch with ActorClassification {
  * Scheduled tasks (Runnable and functions) are executed with the supplied dispatcher.
  * Note that dispatcher is by-name parameter, because dispatcher might not be initialized
  * when the scheduler is created.
+ * 
+ * The HashedWheelTimer used by this class MUST throw an IllegalStateException 
+ * if it does not enqueue a task. Once a task is queued, it MUST be executed or
+ * returned from stop().
  */
 class DefaultScheduler(hashedWheelTimer: HashedWheelTimer, log: LoggingAdapter, dispatcher: ⇒ MessageDispatcher) extends Scheduler with Closeable {
   import org.jboss.netty.akka.util.{ Timeout ⇒ HWTimeout }
diff --git a/akka-actor/src/main/scala/akka/actor/ActorSystem.scala b/akka-actor/src/main/scala/akka/actor/ActorSystem.scala
index f9d79e32e5..130bdca85e 100644
--- a/akka-actor/src/main/scala/akka/actor/ActorSystem.scala
+++ b/akka-actor/src/main/scala/akka/actor/ActorSystem.scala
@@ -398,6 +398,10 @@ class ActorSystemImpl(val name: String, applicationConfig: Config) extends Actor
    * Create the scheduler service. This one needs one special behavior: if
    * Closeable, it MUST execute all outstanding tasks upon .close() in order
    * to properly shutdown all dispatchers.
+   * 
+   * Furthermore, this timer service MUST throw IllegalStateException if it
+   * cannot schedule a task. Once scheduled, the task MUST be executed. If
+   * executed upon close(), the task may execute before its timeout.
    */
   protected def createScheduler(): Scheduler = {
     val threadFactory = new MonitorableThreadFactory("DefaultScheduler")
diff --git a/akka-actor/src/main/scala/akka/actor/Scheduler.scala b/akka-actor/src/main/scala/akka/actor/Scheduler.scala
index 5b32a86a60..121b0da181 100644
--- a/akka-actor/src/main/scala/akka/actor/Scheduler.scala
+++ b/akka-actor/src/main/scala/akka/actor/Scheduler.scala
@@ -14,6 +14,15 @@ package akka.actor
 
 import akka.util.Duration
 
+  /**
+   * An Akka scheduler service. This one needs one special behavior: if
+   * Closeable, it MUST execute all outstanding tasks upon .close() in order
+   * to properly shutdown all dispatchers.
+   * 
+   * Furthermore, this timer service MUST throw IllegalStateException if it
+   * cannot schedule a task. Once scheduled, the task MUST be executed. If
+   * executed upon close(), the task may execute before its timeout.
+   */
 trait Scheduler {
   /**
    * Schedules a message to be sent repeatedly with an initial delay and frequency.