001/*
002 * Trident - A Multithreaded Server Alternative
003 * Copyright 2014 The TridentSDK Team
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *    http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package net.tridentsdk.concurrent;
019
020import net.tridentsdk.plugin.Plugin;
021import net.tridentsdk.registry.Registered;
022import net.tridentsdk.registry.Registry;
023
024import javax.annotation.concurrent.ThreadSafe;
025
026/**
027 * Generates tasks that are queued for execution in the specified method
028 *
029 * <p>In this context, synchronously defines a task which is run on the same thread which the plugin that submitted it
030 * is also running on. An asynchronous task runs on a separate thread pool and requires the accessed state to be
031 * correct synchronized to prevent inconsistencies.</p>
032 *
033 * <p>Ticks are a measurement of time which take place every 1/20th of a second. This is measured by the server's
034 * ticking thread comparing the timestamps since the epoch.</p>
035 *
036 * <p>This class can be accessed using {@link Registered#tasks()}</p>
037 *
038 * @author The TridentSDK Team
039 * @since 0.3-alpha-DP
040 */
041@ThreadSafe
042public interface Scheduler extends Registry<ScheduledTask> {
043    /**
044     * Asynchronously run a task after the next tick
045     *
046     * @param plugin   the plugin which the task is registered to
047     * @param runnable the runnable to perform the task
048     * @return the task which was wrapped by the scheduler
049     */
050    ScheduledTask asyncRun(Plugin plugin, ScheduledRunnable runnable);
051
052    /**
053     * Synchronously run a task after the next tick
054     *
055     * @param plugin   the plugin which the task is registered to
056     * @param runnable the runnable to perform the task
057     * @return the task which was wrapped by the scheduler
058     */
059    ScheduledTask syncRun(Plugin plugin, ScheduledRunnable runnable);
060
061    /**
062     * Asynchronously run a task after a specified time has passed
063     *
064     * @param plugin   the plugin which the task is registered to
065     * @param runnable the runnable to perform the task
066     * @param delay    the amount of ticks to wait until the task is executed
067     * @return the task which was wrapped by the scheduler
068     */
069    ScheduledTask asyncLater(Plugin plugin, ScheduledRunnable runnable, long delay);
070
071    /**
072     * Asynchronously run a task after a specified time has passed
073     *
074     * @param plugin   the plugin which the task is registered to
075     * @param runnable the runnable to perform the task
076     * @param delay    the amount of ticks to wait until the task is executed
077     * @return the task which was wrapped by the scheduler
078     */
079    ScheduledTask syncLater(Plugin plugin, ScheduledRunnable runnable, long delay);
080
081    /**
082     * Asynchronously run a task repeatedly
083     *
084     * @param plugin          the plugin which the task is registered to
085     * @param runnable        the runnable to perform the task
086     * @param delay           the amount of ticks to wait until the task is executed
087     * @param initialInterval the amount of time between each execution which occurs repeatedly until cancelled
088     * @return the task which was wrapped by the scheduler
089     */
090    ScheduledTask asyncRepeat(Plugin plugin, ScheduledRunnable runnable, long delay, long initialInterval);
091
092    /**
093     * Synchronously run a task repeatedly
094     *
095     * @param plugin          the plugin which the task is registered to
096     * @param runnable        the runnable to perform the task
097     * @param delay           the amount of ticks to wait until the task is executed
098     * @param initialInterval the amount of time between each execution which occurs repeatedly until cancelled
099     * @return the task which was wrapped by the scheduler
100     */
101    ScheduledTask syncRepeat(Plugin plugin, ScheduledRunnable runnable, long delay, long initialInterval);
102}