document requirements of our Scheduler service

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();

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 }

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")

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.