/**
 * An {@link ExecutorService} that can schedule commands to run after a given
 * delay, or to execute periodically.
 *
 * <p> The <tt>schedule</tt> methods create tasks with various delays
 * and return a task object that can be used to cancel or check
 * execution. The <tt>scheduleAtFixedRate</tt> and
 * <tt>scheduleWithFixedDelay</tt> methods create and execute tasks
 * that run periodically until cancelled.
 *
 * <p> Commands submitted using the {@link Executor#execute} and
 * {@link ExecutorService} <tt>submit</tt> methods are scheduled with
 * a requested delay of zero. Zero and negative delays (but not
 * periods) are also allowed in <tt>schedule</tt> methods, and are
 * treated as requests for immediate execution.
 *    
 * .....
 * 
 * @since 1.5
 * @author Doug Lea
 */
public interface ScheduledExecutorService extends ExecutorService {

    /**
     * Creates and executes a one-shot action that becomes enabled
     * after the given delay.
     *
     * @param command the task to execute
     * @param delay the time from now to delay execution
     * @param unit the time unit of the delay parameter
     * @return a ScheduledFuture representing pending completion of
     *         the task and whose <tt>get()</tt> method will return
     *         <tt>null</tt> upon completion
     * @throws RejectedExecutionException if the task cannot be
     *         scheduled for execution
     * @throws NullPointerException if command is null
     */
    // 1
    public ScheduledFuture<?> schedule(Runnable command,
				       long delay, TimeUnit unit);

    /**
     * Creates and executes a ScheduledFuture that becomes enabled after the
     * given delay.
     *
     * @param callable the function to execute
     * @param delay the time from now to delay execution
     * @param unit the time unit of the delay parameter
     * @return a ScheduledFuture that can be used to extract result or cancel
     * @throws RejectedExecutionException if the task cannot be
     *         scheduled for execution
     * @throws NullPointerException if callable is null
     */
    // 2
    public <V> ScheduledFuture<V> schedule(Callable<V> callable,
					   long delay, TimeUnit unit);

    /**
     * Creates and executes a periodic action that becomes enabled first
     * after the given initial delay, and subsequently with the given
     * period; that is executions will commence after
     * <tt>initialDelay</tt> then <tt>initialDelay+period</tt>, then
     * <tt>initialDelay + 2 * period</tt>, and so on.
     * If any execution of the task
     * encounters an exception, subsequent executions are suppressed.
     * Otherwise, the task will only terminate via cancellation or
     * termination of the executor.  If any execution of this task
     * takes longer than its period, then subsequent executions
     * may start late, but will not concurrently execute.
     *
     * @param command the task to execute
     * @param initialDelay the time to delay first execution
     * @param period the period between successive executions
     * @param unit the time unit of the initialDelay and period parameters
     * @return a ScheduledFuture representing pending completion of
     *         the task, and whose <tt>get()</tt> method will throw an
     *         exception upon cancellation
     * @throws RejectedExecutionException if the task cannot be
     *         scheduled for execution
     * @throws NullPointerException if command is null
     * @throws IllegalArgumentException if period less than or equal to zero
     */
    // 3
    public ScheduledFuture<?> scheduleAtFixedRate(Runnable command,
						  long initialDelay,
						  long period,
						  TimeUnit unit);

    /**
     * Creates and executes a periodic action that becomes enabled first
     * after the given initial delay, and subsequently with the
     * given delay between the termination of one execution and the
     * commencement of the next.  If any execution of the task
     * encounters an exception, subsequent executions are suppressed.
     * Otherwise, the task will only terminate via cancellation or
     * termination of the executor.
     *
     * @param command the task to execute
     * @param initialDelay the time to delay first execution
     * @param delay the delay between the termination of one
     * execution and the commencement of the next
     * @param unit the time unit of the initialDelay and delay parameters
     * @return a ScheduledFuture representing pending completion of
     *         the task, and whose <tt>get()</tt> method will throw an
     *         exception upon cancellation
     * @throws RejectedExecutionException if the task cannot be
     *         scheduled for execution
     * @throws NullPointerException if command is null
     * @throws IllegalArgumentException if delay less than or equal to zero
     */
    // 4
    public ScheduledFuture<?> scheduleWithFixedDelay(Runnable command,
						     long initialDelay,
						     long delay,
						     TimeUnit unit);

}

public class ScheduledThreadPoolExecutor
        extends ThreadPoolExecutor
        implements ScheduledExecutorService {

    /**
     * False if should cancel/suppress periodic tasks on shutdown.
     */
    // 1
    private volatile boolean continueExistingPeriodicTasksAfterShutdown;

    /**
     * False if should cancel non-periodic tasks on shutdown.
     */
    // 2
    private volatile boolean executeExistingDelayedTasksAfterShutdown = true;

    /**
     * Sequence number to break scheduling ties, and in turn to
     * guarantee FIFO order among tied entries.
     */
    // 3
    private static final AtomicLong sequencer = new AtomicLong(0);

    /** Base of nanosecond timings, to avoid wrapping */
    private static final long NANO_ORIGIN = System.nanoTime();
    ....

/**
     * Creates a new ScheduledThreadPoolExecutor with the given core
     * pool size.
     *
     * @param corePoolSize the number of threads to keep in the pool,
     * even if they are idle
     * @throws IllegalArgumentException if <tt>corePoolSize &lt; 0</tt>
     */
    public ScheduledThreadPoolExecutor(int corePoolSize) {
        super(corePoolSize, Integer.MAX_VALUE, 0, TimeUnit.NANOSECONDS,
              new DelayedWorkQueue());
    }

    /**
     * Creates a new ScheduledThreadPoolExecutor with the given
     * initial parameters.
     *
     * @param corePoolSize the number of threads to keep in the pool,
     * even if they are idle
     * @param threadFactory the factory to use when the executor
     * creates a new thread
     * @throws IllegalArgumentException if <tt>corePoolSize &lt; 0</tt>
     * @throws NullPointerException if threadFactory is null
     */
    public ScheduledThreadPoolExecutor(int corePoolSize,
                             ThreadFactory threadFactory) {
        super(corePoolSize, Integer.MAX_VALUE, 0, TimeUnit.NANOSECONDS,
              new DelayedWorkQueue(), threadFactory);
    }

    /**
     * Creates a new ScheduledThreadPoolExecutor with the given
     * initial parameters.
     *
     * @param corePoolSize the number of threads to keep in the pool,
     * even if they are idle
     * @param handler the handler to use when execution is blocked
     * because the thread bounds and queue capacities are reached
     * @throws IllegalArgumentException if <tt>corePoolSize &lt; 0</tt>
     * @throws NullPointerException if handler is null
     */
    public ScheduledThreadPoolExecutor(int corePoolSize,
                              RejectedExecutionHandler handler) {
        super(corePoolSize, Integer.MAX_VALUE, 0, TimeUnit.NANOSECONDS,
              new DelayedWorkQueue(), handler);
    }
 
    /**
     * Creates a new ScheduledThreadPoolExecutor with the given
     * initial parameters.
     *
     * @param corePoolSize the number of threads to keep in the pool,
     * even if they are idle
     * @param threadFactory the factory to use when the executor
     * creates a new thread
     * @param handler the handler to use when execution is blocked
     * because the thread bounds and queue capacities are reached.
     * @throws IllegalArgumentException if <tt>corePoolSize &lt; 0</tt>
     * @throws NullPointerException if threadFactory or handler is null
     */
    public ScheduledThreadPoolExecutor(int corePoolSize,
                              ThreadFactory threadFactory,
                              RejectedExecutionHandler handler) {
        super(corePoolSize, Integer.MAX_VALUE, 0, TimeUnit.NANOSECONDS,
              new DelayedWorkQueue(), threadFactory, handler);
    }

/**
    * An annoying wrapper class to convince javac to use a
    * DelayQueue<RunnableScheduledFuture> as a BlockingQueue<Runnable>
    */
   private static class DelayedWorkQueue
       extends AbstractCollection<Runnable>
       implements BlockingQueue<Runnable> {

       private final DelayQueue<RunnableScheduledFuture> dq = new DelayQueue<RunnableScheduledFuture>();
       public Runnable poll() { return dq.poll(); }
       public Runnable peek() { return dq.peek(); }
       public Runnable take() throws InterruptedException { return dq.take(); }
       public Runnable poll(long timeout, TimeUnit unit) throws InterruptedException {
           return dq.poll(timeout, unit);
       }

       public boolean add(Runnable x) {
    return dq.add((RunnableScheduledFuture)x);
}
       public boolean offer(Runnable x) {
    return dq.offer((RunnableScheduledFuture)x);
}
       public void put(Runnable x) {
           dq.put((RunnableScheduledFuture)x);
       }
       public boolean offer(Runnable x, long timeout, TimeUnit unit) {
           return dq.offer((RunnableScheduledFuture)x, timeout, unit);
       }
       ....

public ScheduledFuture<?> schedule(Runnable command,
                                      long delay,
                                      TimeUnit unit) {
       if (command == null || unit == null)
           throw new NullPointerException();
       // 1
       RunnableScheduledFuture<?> t = decorateTask(command,
           new ScheduledFutureTask<Void>(command, null,
                                         triggerTime(delay, unit)));

       // 2
       delayedExecute(t);
       return t;
   }

   public <V> ScheduledFuture<V> schedule(Callable<V> callable,
                                          long delay,
                                          TimeUnit unit) {
       if (callable == null || unit == null)
           throw new NullPointerException();
       RunnableScheduledFuture<V> t = decorateTask(callable,
           new ScheduledFutureTask<V>(callable,
   			       triggerTime(delay, unit)));
       delayedExecute(t);
       return t;
   }

/**
  * Returns the trigger time of a delayed action.
  */
 // 1
 private long triggerTime(long delay, TimeUnit unit) {
      return triggerTime(unit.toNanos((delay < 0) ? 0 : delay));
 }

 /**
  * Returns the trigger time of a delayed action.
  */
 long triggerTime(long delay) {
      // 2
      return now() +
          ((delay < (Long.MAX_VALUE >> 1)) ? delay : overflowFree(delay));
 }

/**
 * Constrains the values of all delays in the queue to be within
 * Long.MAX_VALUE of each other, to avoid overflow in compareTo.
 * This may occur if a task is eligible to be dequeued, but has
 * not yet been, while some other task is added with a delay of
 * Long.MAX_VALUE.
 */
private long overflowFree(long delay) {
    Delayed head = (Delayed) super.getQueue().peek();
    if (head != null) {
        long headDelay = head.getDelay(TimeUnit.NANOSECONDS);
        if (headDelay < 0 && (delay - headDelay < 0))
            delay = Long.MAX_VALUE + headDelay;
    }
    return delay;
}

/**
    * Modifies or replaces the task used to execute a runnable.
    * This method can be used to override the concrete
    * class used for managing internal tasks.
    * The default implementation simply returns the given task.
    *
    * @param runnable the submitted Runnable
    * @param task the task created to execute the runnable
    * @return a task that can execute the runnable
    * @since 1.6
    */
   protected <V> RunnableScheduledFuture<V> decorateTask(
       Runnable runnable, RunnableScheduledFuture<V> task) {
       return task;
   }

   /**
    * Modifies or replaces the task used to execute a callable.
    * This method can be used to override the concrete
    * class used for managing internal tasks.
    * The default implementation simply returns the given task.
    *
    * @param callable the submitted Callable
    * @param task the task created to execute the callable
    * @return a task that can execute the callable
    * @since 1.6
    */
   protected <V> RunnableScheduledFuture<V> decorateTask(
       Callable<V> callable, RunnableScheduledFuture<V> task) {
       return task;
   }

private class ScheduledFutureTask<V>
            extends FutureTask<V> implements RunnableScheduledFuture<V> {

        /** Sequence number to break ties FIFO */
        // 1
        private final long sequenceNumber;
        /** The time the task is enabled to execute in nanoTime units */
        // 2
        private long time;
        /**
         * Period in nanoseconds for repeating tasks.  A positive
         * value indicates fixed-rate execution.  A negative value
         * indicates fixed-delay execution.  A value of 0 indicates a
         * non-repeating task.
         */
        // 3
        private final long period;

        /**
         * Creates a one-shot action with given nanoTime-based trigger time.
         */
        ScheduledFutureTask(Runnable r, V result, long ns) {
            super(r, result);
            this.time = ns;
            this.period = 0;
            this.sequenceNumber = sequencer.getAndIncrement();
        }

        /**
         * Creates a periodic action with given nano time and period.
         */
        ScheduledFutureTask(Runnable r, V result, long ns, long period) {
            super(r, result);
            this.time = ns;
            this.period = period;
            this.sequenceNumber = sequencer.getAndIncrement();
        }

        /**
         * Creates a one-shot action with given nanoTime-based trigger.
         */
        ScheduledFutureTask(Callable<V> callable, long ns) {
            super(callable);
            this.time = ns;
            this.period = 0;
            this.sequenceNumber = sequencer.getAndIncrement();
        }
        ....

/**
 * A {@link ScheduledFuture} that is {@link Runnable}. Successful
 * execution of the <tt>run</tt> method causes completion of the
 * <tt>Future</tt> and allows access to its results.
 * @see FutureTask
 * @see Executor
 * @since 1.6
 * @author Doug Lea
 * @param <V> The result type returned by this Future's <tt>get</tt> method
 */
public interface RunnableScheduledFuture<V> extends RunnableFuture<V>, ScheduledFuture<V> {

    /**
     * Returns true if this is a periodic task. A periodic task may
     * re-run according to some schedule. A non-periodic task can be
     * run only once.
     *
     * @return true if this task is periodic
     */
    // 1
    boolean isPeriodic();
}

// 1
public long getDelay(TimeUnit unit) {
            return unit.convert(time - now(), TimeUnit.NANOSECONDS);
        }

/**
  * Returns the task queue used by this executor.  Each element of
  * this queue is a {@link ScheduledFuture}, including those
  * tasks submitted using <tt>execute</tt> which are for scheduling
  * purposes used as the basis of a zero-delay
  * <tt>ScheduledFuture</tt>. Iteration over this queue is
  * <em>not</em> guaranteed to traverse tasks in the order in
  * which they will execute.
  *
  * @return the task queue
  */
 public BlockingQueue<Runnable> getQueue() {
     return super.getQueue();
 }

/**
     * Specialized variant of ThreadPoolExecutor.execute for delayed tasks.
     */
    private void delayedExecute(Runnable command) {
        if (isShutdown()) {
            // 1
            reject(command);
            return;
        }
        // Prestart a thread if necessary. We cannot prestart it
        // running the task because the task (probably) shouldn't be
        // run yet, so thread will just idle until delay elapses.
        // 2
        if (getPoolSize() < getCorePoolSize())
            prestartCoreThread();
        // 3
        super.getQueue().add(command);
    }

/**
 * Runs a periodic task.
 */
private void runPeriodic() {
    boolean ok = ScheduledFutureTask.super.runAndReset();
    boolean down = isShutdown();
    // Reschedule if not cancelled and not shutdown or policy allows
    if (ok && (!down ||
               (getContinueExistingPeriodicTasksAfterShutdownPolicy() &&
                !isStopped()))) {
        long p = period;
        if (p > 0)
            time += p;
        else
            time = triggerTime(-p);
        ScheduledThreadPoolExecutor.super.getQueue().add(this);
    }
    // This might have been the final executed delayed
    // task.  Wake up threads to check.
    else if (down)
        interruptIdleWorkers();
}

/**
 * Overrides FutureTask version so as to reset/requeue if periodic.
 */
public void run() {
    // 1
    if (isPeriodic())
        // 2
        runPeriodic();
    else
        // 3
        ScheduledFutureTask.super.run();
}

/**
         * Runs a periodic task.
         */
        private void runPeriodic() {
            // 1
            boolean ok = ScheduledFutureTask.super.runAndReset();
            // 2
            boolean down = isShutdown();
            // Reschedule if not cancelled and not shutdown or policy allows
            // 3
            if (ok && (!down ||
                       (getContinueExistingPeriodicTasksAfterShutdownPolicy() &&
                        !isStopped()))) {
                // 4
                long p = period;
                if (p > 0)
                    // 5
                    time += p;
                else
                    // 6
                    time = triggerTime(-p);
                // 7
                ScheduledThreadPoolExecutor.super.getQueue().add(this);
            }
            // This might have been the final executed delayed
            // task.  Wake up threads to check.
            // 8
            else if (down)
                interruptIdleWorkers();
        }

public ScheduledFuture<?> scheduleAtFixedRate(Runnable command,
                                                  long initialDelay,
                                                  long period,
                                                  TimeUnit unit) {
        if (command == null || unit == null)
            throw new NullPointerException();
        if (period <= 0)
            throw new IllegalArgumentException();
        RunnableScheduledFuture<?> t = decorateTask(command,
            new ScheduledFutureTask<Object>(command,
                                            null,
                                            triggerTime(initialDelay, unit),
                                            unit.toNanos(period)));
        delayedExecute(t);
        return t;
    }

public ScheduledFuture<?> scheduleWithFixedDelay(Runnable command,
                                                 long initialDelay,
                                                 long delay,
                                                 TimeUnit unit) {
    if (command == null || unit == null)
        throw new NullPointerException();
    if (delay <= 0)
        throw new IllegalArgumentException();
    RunnableScheduledFuture<?> t = decorateTask(command,
        new ScheduledFutureTask<Boolean>(command,
                                         null,
                                         triggerTime(initialDelay, unit),
                                         unit.toNanos(-delay)));
    delayedExecute(t);
    return t;
}

/**
     * Sets the policy on whether to continue executing existing periodic
     * tasks even when this executor has been <tt>shutdown</tt>. In
     * this case, these tasks will only terminate upon
     * <tt>shutdownNow</tt>, or after setting the policy to
     * <tt>false</tt> when already shutdown. This value is by default
     * false.
     *
     * @param value if true, continue after shutdown, else don't.
     * @see #getContinueExistingPeriodicTasksAfterShutdownPolicy
     */
    public void setContinueExistingPeriodicTasksAfterShutdownPolicy(boolean value) {
        continueExistingPeriodicTasksAfterShutdown = value;
        if (!value && isShutdown())
            cancelUnwantedTasks();
    }

/**
     * Sets the policy on whether to execute existing delayed
     * tasks even when this executor has been <tt>shutdown</tt>. In
     * this case, these tasks will only terminate upon
     * <tt>shutdownNow</tt>, or after setting the policy to
     * <tt>false</tt> when already shutdown. This value is by default
     * true.
     *
     * @param value if true, execute after shutdown, else don't.
     * @see #getExecuteExistingDelayedTasksAfterShutdownPolicy
     */
    public void setExecuteExistingDelayedTasksAfterShutdownPolicy(boolean value) {
        executeExistingDelayedTasksAfterShutdown = value;
        if (!value && isShutdown())
            cancelUnwantedTasks();
    }

/**
 * Initiates an orderly shutdown in which previously submitted
 * tasks are executed, but no new tasks will be accepted. If the
 * <tt>ExecuteExistingDelayedTasksAfterShutdownPolicy</tt> has
 * been set <tt>false</tt>, existing delayed tasks whose delays
 * have not yet elapsed are cancelled. And unless the
 * <tt>ContinueExistingPeriodicTasksAfterShutdownPolicy</tt> has
 * been set <tt>true</tt>, future executions of existing periodic
 * tasks will be cancelled.
 */
public void shutdown() {
    cancelUnwantedTasks();
    super.shutdown();
}

/**
     * Cancels and clears the queue of all tasks that should not be run
     * due to shutdown policy.
     */
    private void cancelUnwantedTasks() {
        // 1
        boolean keepDelayed = getExecuteExistingDelayedTasksAfterShutdownPolicy();
        // 2
        boolean keepPeriodic = getContinueExistingPeriodicTasksAfterShutdownPolicy();
        if (!keepDelayed && !keepPeriodic)
            // 3
            super.getQueue().clear();
        else if (keepDelayed || keepPeriodic) {
            // 4
            Object[] entries = super.getQueue().toArray();
            for (int i = 0; i < entries.length; ++i) {
                Object e = entries[i];
                if (e instanceof RunnableScheduledFuture) {
                    RunnableScheduledFuture<?> t = (RunnableScheduledFuture<?>)e;
                    if (t.isPeriodic()? !keepPeriodic : !keepDelayed)
                        t.cancel(false);
                }
            }
            entries = null;
            // 5
            purge();
        }
    }