001/**
002 * The MIT License (MIT)
003 *
004 * Copyright (c) 2018 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.loop;
025
026import java.util.concurrent.ExecutorService;
027import java.util.concurrent.TimeUnit;
028
029/**
030 * Shutdownable is a running service such as a thread that can be shutdown orderly or abruptly in a way similar to
031 * {@link ExecutorService}.
032 */
033public interface Shutdownable {
034    /**
035     * Initiates an orderly shutdown in which the service will be continue to perform its duties
036     * as long as there is work to be done.  For instance for a sequence of steps, the service could
037     * continue to invoke the steps' {@link Step#perform() perform()} methods until all invocations
038     * yield false (indicating that no work was done).
039     * <p>
040     * This method does not wait for for termination; use {@link #awaitTermination awaitTermination}
041     * to do that.
042     * <p>
043     * Invocation has no additional effect if already shut down.
044     */
045    void shutdown();
046
047    /**
048     * Initiates an immediate shutdown in which the service will stop even if there is more work
049     * to be done.  For instance for a sequence of steps, the service could abort invocation of the
050     * steps' {@link Step#perform() perform()} irrespective of prior invocation results.
051     * <p>
052     * This method does not wait for for termination; use {@link #awaitTermination awaitTermination}
053     * to do that.
054     * <p>
055     * Invocation has no additional effect if already shut down.
056     */
057    void shutdownNow();
058
059    /**
060     * Returns {@code true} if this service has been shut down.
061     *
062     * @return {@code true} if this service has been shut down
063     */
064    boolean isShutdown();
065
066    /**
067     * Returns {@code true} if this service has terminated following shut down.  Note that
068     * {@code isTerminated} is never {@code true} unless either {@code shutdown} or
069     * {@code shutdownNow} was called first.
070     *
071     * @return {@code true} if the service has terminated following shut down
072     */
073    boolean isTerminated();
074
075    /**
076     * Blocks until all tasks have completed execution after a shutdown request, or the timeout occurs,
077     * whichever happens first.
078     *
079     * @param timeout the maximum time to wait
080     * @param unit the time unit of the timeout argument
081     * @return {@code true} if this executor terminated and
082     *         {@code false} if the timeout elapsed before termination
083     */
084    boolean awaitTermination(long timeout, TimeUnit unit);
085}