/*
* Copyright 2009 Google Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*/
package com.google.gwt.core.client;
import com.google.gwt.core.client.impl.SchedulerImpl;
/**
* This class provides low-level task scheduling primitives. Any exceptions
* thrown by the command objects executed by the scheduler will be passed to the
* {@link GWT.UncaughtExceptionHandler} if one is installed.
*
* <p>
* NOTE: If you are using a timer to schedule a UI animation, use
* {@link com.google.gwt.animation.client.AnimationScheduler} instead. The
* browser can optimize your animation for maximum performance.
* </p>
*
* @see com.google.gwt.core.client.testing.StubScheduler
*/
public abstract class Scheduler {
/**
* General-purpose Command interface for tasks that repeat.
*/
public interface RepeatingCommand {
/**
* Returns true if the RepeatingCommand should be invoked again.
*/
boolean execute();
}
/**
* General-purpose Command interface.
*/
public interface ScheduledCommand {
/**
* Invokes the command.
*/
void execute();
}
/**
* Returns the default implementation of the Scheduler API.
*/
public static Scheduler get() {
return SchedulerImpl.INSTANCE;
}
/**
* A deferred command is executed after the browser event loop returns.
*/
public abstract void scheduleDeferred(ScheduledCommand cmd);
/**
* An "entry" command will be executed before GWT-generated code is invoked by
* the browser's event loop. The {@link RepeatingCommand} will be called once
* per entry from the event loop until <code>false</code> is returned. This
* type of command is appropriate for instrumentation or code that needs to
* know when "something happens."
* <p>
* If an entry command schedules another entry command, the second command
* will be executed before control flow continues to the GWT-generated code.
*/
public abstract void scheduleEntry(RepeatingCommand cmd);
/**
* An "entry" command will be executed before GWT-generated code is invoked by
* the browser's event loop. This type of command is appropriate for code that
* needs to know when "something happens."
* <p>
* If an entry command schedules another entry command, the second command
* will be executed before control flow continues to the GWT-generated code.
*/
public abstract void scheduleEntry(ScheduledCommand cmd);
/**
* A "finally" command will be executed before GWT-generated code returns
* control to the browser's event loop. The {@link RepeatingCommand#execute()}
* method will be called once per exit to the event loop until
* <code>false</code> is returned. This type of command is appropriate for
* instrumentation or cleanup code.
* <p>
* If a finally command schedules another finally command, the second command
* will be executed before control flow returns to the browser.
*/
public abstract void scheduleFinally(RepeatingCommand cmd);
/**
* A "finally" command will be executed before GWT-generated code returns
* control to the browser's event loop. This type of command is used to
* aggregate small amounts of work before performing a non-recurring,
* heavyweight operation.
* <p>
* If a finally command schedules another finally command, the second command
* will be executed before control flow returns to the browser.
* <p>
* Consider the following:
*
* <pre>
* try {
* nativeEventCallback(); // Calls scheduleFinally one or more times
* } finally {
* executeFinallyCommands();
* }
* </pre>
*
* @see com.google.gwt.dom.client.StyleInjector
*/
public abstract void scheduleFinally(ScheduledCommand cmd);
/**
* Schedules a repeating command that is scheduled with a constant delay. That
* is, the next invocation of the command will be scheduled for
* <code>delayMs</code> milliseconds after the last invocation completes.
* <p>
* For example, assume that a command takes 30ms to run and a 100ms delay is
* provided. The second invocation of the command will occur at 130ms after
* the first invocation starts.
*
* @param cmd the command to execute
* @param delayMs the amount of time to wait after one invocation ends before
* the next invocation
*/
public abstract void scheduleFixedDelay(RepeatingCommand cmd, int delayMs);
/**
* Schedules a repeating command that is scheduled with a constant
* periodicity. That is, the command will be invoked every
* <code>delayMs</code> milliseconds, regardless of how long the previous
* invocation took to complete.
*
* @param cmd the command to execute
* @param delayMs the period with which the command is executed
*/
public abstract void scheduleFixedPeriod(RepeatingCommand cmd, int delayMs);
/**
* Schedules a repeating command that performs incremental work. This type of
* command is encouraged for long-running processes that perform computation
* or that manipulate the DOM. The commands in this queue are invoked many
* times in rapid succession and are then deferred to allow the browser to
* process its event queue.
*
* @param cmd the command to execute
*/
public abstract void scheduleIncremental(RepeatingCommand cmd);
}