001/**
002 * The MIT License (MIT)
003 *
004 * Copyright (c) 2019 nobark (tools4j), Marco Terzer, Anton Anufriev
005 *
006 * Permission is hereby granted, free of charge, to any person obtaining a copy
007 * of this software and associated documentation files (the "Software"), to deal
008 * in the Software without restriction, including without limitation the rights
009 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
010 * copies of the Software, and to permit persons to whom the Software is
011 * furnished to do so, subject to the following conditions:
012 *
013 * The above copyright notice and this permission notice shall be included in all
014 * copies or substantial portions of the Software.
015 *
016 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
017 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
018 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
019 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
020 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
021 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
022 * SOFTWARE.
023 */
024package org.tools4j.nobark.run;
025
026import java.util.List;
027import java.util.concurrent.ExecutorService;
028import java.util.concurrent.TimeUnit;
029
030import org.tools4j.nobark.loop.Step;
031
032/**
033 * Shutdownable is a running service such as a thread that can be shutdown orderly or abruptly in a way similar to
034 * {@link ExecutorService}.
035 */
036public interface Shutdownable {
037    /**
038     * Initiates an orderly shutdown in which the service will be continue to perform its duties
039     * as long as there is work to be done.  For instance for a sequence of steps, the service could
040     * continue to invoke the steps' {@link Step#perform() perform()} methods until all invocations
041     * yield false (indicating that no work was done).
042     * <p>
043     * This method does not wait for for termination; use {@link #awaitTermination awaitTermination}
044     * to do that.
045     * <p>
046     * Invocation has no additional effect if already shut down.
047     */
048    void shutdown();
049
050    /**
051     * Initiates an immediate shutdown in which the service will stop even if there is more work
052     * to be done.  For instance for a sequence of steps, the service could abort invocation of the
053     * steps' {@link Step#perform() perform()} irrespective of prior invocation results.
054     * <p>
055     * This method does not wait for for termination; use {@link #awaitTermination awaitTermination}
056     * to do that.
057     * <p>
058     * Invocation has no additional effect if already shut down.
059     *
060     * @return list of tasks that never commenced execution if any, otherwise an empty list
061     */
062    List<Runnable> shutdownNow();
063
064    /**
065     * Returns {@code true} if this service has been shut down.
066     *
067     * @return {@code true} if this service has been shut down
068     */
069    boolean isShutdown();
070
071    /**
072     * Returns {@code true} if this service has terminated.
073     *
074     * @return {@code true} if the service has terminated.
075     */
076    boolean isTerminated();
077
078    /**
079     * Blocks until this service has terminated, or the timeout occurs, whichever happens first.
080     * Zero timeout means waiting forever.
081     *
082     * @param timeout the maximum time to wait, zero to wait indefinitely
083     * @param unit the time unit of the timeout argument
084     * @return {@code true} if this executor terminated and
085     *         {@code false} if the timeout elapsed before termination
086     * @throws IllegalStateException if any thread has interrupted the current thread
087     */
088    boolean awaitTermination(long timeout, TimeUnit unit);
089}