001 package org.bukkit.scheduler;
002
003 import org.bukkit.plugin.Plugin;
004 import java.util.concurrent.Callable;
005 import java.util.concurrent.Future;
006 import java.util.List;
007
008 public interface BukkitScheduler {
009
010 /**
011 * Schedules a once off task to occur after a delay.
012 * <p>
013 * This task will be executed by the main server thread.
014 *
015 * @param plugin Plugin that owns the task
016 * @param task Task to be executed
017 * @param delay Delay in server ticks before executing task
018 * @return Task id number (-1 if scheduling failed)
019 */
020 public int scheduleSyncDelayedTask(Plugin plugin, Runnable task, long delay);
021
022 /**
023 * @deprecated Use {@link BukkitRunnable#runTaskLater(Plugin, long)}
024 */
025 @Deprecated
026 public int scheduleSyncDelayedTask(Plugin plugin, BukkitRunnable task, long delay);
027
028 /**
029 * Schedules a once off task to occur as soon as possible.
030 * <p>
031 * This task will be executed by the main server thread.
032 *
033 * @param plugin Plugin that owns the task
034 * @param task Task to be executed
035 * @return Task id number (-1 if scheduling failed)
036 */
037 public int scheduleSyncDelayedTask(Plugin plugin, Runnable task);
038
039 /**
040 * @deprecated Use {@link BukkitRunnable#runTask(Plugin)}
041 */
042 @Deprecated
043 public int scheduleSyncDelayedTask(Plugin plugin, BukkitRunnable task);
044
045 /**
046 * Schedules a repeating task.
047 * <p>
048 * This task will be executed by the main server thread.
049 *
050 * @param plugin Plugin that owns the task
051 * @param task Task to be executed
052 * @param delay Delay in server ticks before executing first repeat
053 * @param period Period in server ticks of the task
054 * @return Task id number (-1 if scheduling failed)
055 */
056 public int scheduleSyncRepeatingTask(Plugin plugin, Runnable task, long delay, long period);
057
058 /**
059 * @deprecated Use {@link BukkitRunnable#runTaskTimer(Plugin, long, long)}
060 */
061 @Deprecated
062 public int scheduleSyncRepeatingTask(Plugin plugin, BukkitRunnable task, long delay, long period);
063
064 /**
065 * <b>Asynchronous tasks should never access any API in Bukkit. Great care
066 * should be taken to assure the thread-safety of asynchronous tasks.</b>
067 * <p>
068 * Schedules a once off task to occur after a delay. This task will be
069 * executed by a thread managed by the scheduler.
070 *
071 * @param plugin Plugin that owns the task
072 * @param task Task to be executed
073 * @param delay Delay in server ticks before executing task
074 * @return Task id number (-1 if scheduling failed)
075 * @deprecated This name is misleading, as it does not schedule "a sync"
076 * task, but rather, "an async" task
077 */
078 @Deprecated
079 public int scheduleAsyncDelayedTask(Plugin plugin, Runnable task, long delay);
080
081 /**
082 * <b>Asynchronous tasks should never access any API in Bukkit. Great care
083 * should be taken to assure the thread-safety of asynchronous tasks.</b>
084 * <p>
085 * Schedules a once off task to occur as soon as possible. This task will
086 * be executed by a thread managed by the scheduler.
087 *
088 * @param plugin Plugin that owns the task
089 * @param task Task to be executed
090 * @return Task id number (-1 if scheduling failed)
091 * @deprecated This name is misleading, as it does not schedule "a sync"
092 * task, but rather, "an async" task
093 */
094 @Deprecated
095 public int scheduleAsyncDelayedTask(Plugin plugin, Runnable task);
096
097 /**
098 * <b>Asynchronous tasks should never access any API in Bukkit. Great care
099 * should be taken to assure the thread-safety of asynchronous tasks.</b>
100 * <p>
101 * Schedules a repeating task. This task will be executed by a thread
102 * managed by the scheduler.
103 *
104 * @param plugin Plugin that owns the task
105 * @param task Task to be executed
106 * @param delay Delay in server ticks before executing first repeat
107 * @param period Period in server ticks of the task
108 * @return Task id number (-1 if scheduling failed)
109 * @deprecated This name is misleading, as it does not schedule "a sync"
110 * task, but rather, "an async" task
111 */
112 @Deprecated
113 public int scheduleAsyncRepeatingTask(Plugin plugin, Runnable task, long delay, long period);
114
115 /**
116 * Calls a method on the main thread and returns a Future object. This
117 * task will be executed by the main server thread.
118 * <ul>
119 * <li>Note: The Future.get() methods must NOT be called from the main
120 * thread.
121 * <li>Note2: There is at least an average of 10ms latency until the
122 * isDone() method returns true.
123 * </ul>
124 * @param <T> The callable's return type
125 * @param plugin Plugin that owns the task
126 * @param task Task to be executed
127 * @return Future Future object related to the task
128 */
129 public <T> Future<T> callSyncMethod(Plugin plugin, Callable<T> task);
130
131 /**
132 * Removes task from scheduler.
133 *
134 * @param taskId Id number of task to be removed
135 */
136 public void cancelTask(int taskId);
137
138 /**
139 * Removes all tasks associated with a particular plugin from the
140 * scheduler.
141 *
142 * @param plugin Owner of tasks to be removed
143 */
144 public void cancelTasks(Plugin plugin);
145
146 /**
147 * Removes all tasks from the scheduler.
148 */
149 public void cancelAllTasks();
150
151 /**
152 * Check if the task currently running.
153 * <p>
154 * A repeating task might not be running currently, but will be running in
155 * the future. A task that has finished, and does not repeat, will not be
156 * running ever again.
157 * <p>
158 * Explicitly, a task is running if there exists a thread for it, and that
159 * thread is alive.
160 *
161 * @param taskId The task to check.
162 * <p>
163 * @return If the task is currently running.
164 */
165 public boolean isCurrentlyRunning(int taskId);
166
167 /**
168 * Check if the task queued to be run later.
169 * <p>
170 * If a repeating task is currently running, it might not be queued now
171 * but could be in the future. A task that is not queued, and not running,
172 * will not be queued again.
173 *
174 * @param taskId The task to check.
175 * <p>
176 * @return If the task is queued to be run.
177 */
178 public boolean isQueued(int taskId);
179
180 /**
181 * Returns a list of all active workers.
182 * <p>
183 * This list contains asynch tasks that are being executed by separate
184 * threads.
185 *
186 * @return Active workers
187 */
188 public List<BukkitWorker> getActiveWorkers();
189
190 /**
191 * Returns a list of all pending tasks. The ordering of the tasks is not
192 * related to their order of execution.
193 *
194 * @return Active workers
195 */
196 public List<BukkitTask> getPendingTasks();
197
198 /**
199 * Returns a task that will run on the next server tick.
200 *
201 * @param plugin the reference to the plugin scheduling task
202 * @param task the task to be run
203 * @return a BukkitTask that contains the id number
204 * @throws IllegalArgumentException if plugin is null
205 * @throws IllegalArgumentException if task is null
206 */
207 public BukkitTask runTask(Plugin plugin, Runnable task) throws IllegalArgumentException;
208
209 /**
210 * @deprecated Use {@link BukkitRunnable#runTask(Plugin)}
211 */
212 @Deprecated
213 public BukkitTask runTask(Plugin plugin, BukkitRunnable task) throws IllegalArgumentException;
214
215 /**
216 * <b>Asynchronous tasks should never access any API in Bukkit. Great care
217 * should be taken to assure the thread-safety of asynchronous tasks.</b>
218 * <p>
219 * Returns a task that will run asynchronously.
220 *
221 * @param plugin the reference to the plugin scheduling task
222 * @param task the task to be run
223 * @return a BukkitTask that contains the id number
224 * @throws IllegalArgumentException if plugin is null
225 * @throws IllegalArgumentException if task is null
226 */
227 public BukkitTask runTaskAsynchronously(Plugin plugin, Runnable task) throws IllegalArgumentException;
228
229 /**
230 * @deprecated Use {@link BukkitRunnable#runTaskAsynchronously(Plugin)}
231 */
232 @Deprecated
233 public BukkitTask runTaskAsynchronously(Plugin plugin, BukkitRunnable task) throws IllegalArgumentException;
234
235 /**
236 * Returns a task that will run after the specified number of server
237 * ticks.
238 *
239 * @param plugin the reference to the plugin scheduling task
240 * @param task the task to be run
241 * @param delay the ticks to wait before running the task
242 * @return a BukkitTask that contains the id number
243 * @throws IllegalArgumentException if plugin is null
244 * @throws IllegalArgumentException if task is null
245 */
246 public BukkitTask runTaskLater(Plugin plugin, Runnable task, long delay) throws IllegalArgumentException;
247
248 /**
249 * @deprecated Use {@link BukkitRunnable#runTaskLater(Plugin, long)}
250 */
251 @Deprecated
252 public BukkitTask runTaskLater(Plugin plugin, BukkitRunnable task, long delay) throws IllegalArgumentException;
253
254 /**
255 * <b>Asynchronous tasks should never access any API in Bukkit. Great care
256 * should be taken to assure the thread-safety of asynchronous tasks.</b>
257 * <p>
258 * Returns a task that will run asynchronously after the specified number
259 * of server ticks.
260 *
261 * @param plugin the reference to the plugin scheduling task
262 * @param task the task to be run
263 * @param delay the ticks to wait before running the task
264 * @return a BukkitTask that contains the id number
265 * @throws IllegalArgumentException if plugin is null
266 * @throws IllegalArgumentException if task is null
267 */
268 public BukkitTask runTaskLaterAsynchronously(Plugin plugin, Runnable task, long delay) throws IllegalArgumentException;
269
270 /**
271 * @deprecated Use {@link BukkitRunnable#runTaskLaterAsynchronously(Plugin, long)}
272 */
273 @Deprecated
274 public BukkitTask runTaskLaterAsynchronously(Plugin plugin, BukkitRunnable task, long delay) throws IllegalArgumentException;
275
276 /**
277 * Returns a task that will repeatedly run until cancelled, starting after
278 * the specified number of server ticks.
279 *
280 * @param plugin the reference to the plugin scheduling task
281 * @param task the task to be run
282 * @param delay the ticks to wait before running the task
283 * @param period the ticks to wait between runs
284 * @return a BukkitTask that contains the id number
285 * @throws IllegalArgumentException if plugin is null
286 * @throws IllegalArgumentException if task is null
287 */
288 public BukkitTask runTaskTimer(Plugin plugin, Runnable task, long delay, long period) throws IllegalArgumentException;
289
290 /**
291 * @deprecated Use {@link BukkitRunnable#runTaskTimer(Plugin, long, long)}
292 */
293 @Deprecated
294 public BukkitTask runTaskTimer(Plugin plugin, BukkitRunnable task, long delay, long period) throws IllegalArgumentException;
295
296 /**
297 * <b>Asynchronous tasks should never access any API in Bukkit. Great care
298 * should be taken to assure the thread-safety of asynchronous tasks.</b>
299 * <p>
300 * Returns a task that will repeatedly run asynchronously until cancelled,
301 * starting after the specified number of server ticks.
302 *
303 * @param plugin the reference to the plugin scheduling task
304 * @param task the task to be run
305 * @param delay the ticks to wait before running the task for the first
306 * time
307 * @param period the ticks to wait between runs
308 * @return a BukkitTask that contains the id number
309 * @throws IllegalArgumentException if plugin is null
310 * @throws IllegalArgumentException if task is null
311 */
312 public BukkitTask runTaskTimerAsynchronously(Plugin plugin, Runnable task, long delay, long period) throws IllegalArgumentException;
313
314 /**
315 * @deprecated Use {@link BukkitRunnable#runTaskTimerAsynchronously(Plugin, long, long)}
316 */
317 @Deprecated
318 public BukkitTask runTaskTimerAsynchronously(Plugin plugin, BukkitRunnable task, long delay, long period) throws IllegalArgumentException;
319 }