src/java/org/apache/cassandra/concurrent/ExecutorPlus.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you 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 org.apache.cassandra.concurrent;

import java.util.Collection;
import java.util.List;
import java.util.concurrent.Callable;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

import org.apache.cassandra.utils.Shared;
import org.apache.cassandra.utils.WithResources;
import org.apache.cassandra.utils.concurrent.Future;

import static org.apache.cassandra.utils.Shared.Recursive.INTERFACES;
import static org.apache.cassandra.utils.Shared.Scope.SIMULATION;

/**
 * Cassandra's extension of {@link ExecutorService}, using our own {@link Future}, supporting
 * {@link #inExecutor()}, and execution with associated resources {@link #execute(WithResources, Runnable)}
 * (which is primarily used for encapsulating {@link ExecutorLocals} without leaking implementing classes).
 */
@Shared(scope = SIMULATION, inner = INTERFACES)
public interface ExecutorPlus extends ExecutorService, ResizableThreadPool
{
    interface MaximumPoolSizeListener
    {
        /**
         * Listener to follow changes to the maximum pool size
         */
        void onUpdateMaximumPoolSize(int maximumPoolSize);
    }

    /**
     * MAY execute {@code task} immediately, if the calling thread is permitted to do so.
     */
    default void maybeExecuteImmediately(Runnable task)
    {
        execute(task);
    }

    /**
     * Overrides {@link ExecutorService#submit(Callable)} to return a Cassandra {@link Future}
     */
    @Override
    <T> Future<T> submit(Callable<T> task);

    /**
     * Overrides {@link ExecutorService#submit(Runnable, Object)} to return a Cassandra {@link Future}
     */
    @Override
    <T> Future<T> submit(Runnable task, T result);

    /**
     * Overrides {@link ExecutorService#submit(Runnable)} to return a Cassandra {@link Future}
     */
    @Override
    Future<?> submit(Runnable task);

    /*
     * ==============================================
     * WithResources variants of submit and execute.
     *
     * (We need a way to inject a TraceState directly into the Executor context without going through
     * the global Tracing sessions; see CASSANDRA-5668)
     * ==============================================
     */

    /**
     * Invoke {@code task}. The invoking thread will first instantiate the resources provided before
     * invoking {@code task}, so that thread state may be modified and cleaned up.
     *
     * The invoking thread will execute something semantically equivlent to:
     *
     * <code>
     *     try (Closeable close = withResources.get())
     *     {
     *         task.run();
     *     }
     * </code>
     *
     * @param withResources the resources to create and hold while executing {@code task}
     * @param task the task to execute
     */
    void execute(WithResources withResources, Runnable task);

    /**
     * Invoke {@code task}, returning a future representing this computation.
     * The invoking thread will first instantiate the resources provided before
     * invoking {@code task}, so that thread state may be modified and cleaned up.
     *
     * The invoking thread will execute something semantically equivlent to:
     *
     * <code>
     *     try (Closeable close = withResources.get())
     *     {
     *         return task.call();
     *     }
     * </code>
     *
     * @param withResources the resources to create and hold while executing {@code task}
     * @param task the task to execute
     */
    <T> Future<T> submit(WithResources withResources, Callable<T> task);

    /**
     * Invoke {@code task}, returning a future yielding {@code null} if successful,
     * or the abnormal termination of {@code task} otherwise.
     *
     * The invoking thread will first instantiate the resources provided before
     * invoking {@code task}, so that thread state may be modified and cleaned up
     *
     * <code>
     *     try (Closeable close = withResources.get())
     *     {
     *         task.run();
     *         return null;
     *     }
     * </code>
     *
     * @param withResources the resources to create and hold while executing {@code task}
     * @param task the task to execute
     */
    Future<?> submit(WithResources withResources, Runnable task);

    /**
     * Invoke {@code task}, returning a future yielding {@code result} if successful,
     * or the abnormal termination of {@code task} otherwise.
     *
     * The invoking thread will first instantiate the resources provided before
     * invoking {@code task}, so that thread state may be modified and cleaned up.
     *
     * The invoking thread will execute something semantically equivlent to:
     *
     * <code>
     *     try (Closeable close = withResources.get())
     *     {
     *         task.run();
     *         return result;
     *     }
     * </code>
     *
     * @param withResources the resources to create and hold while executing {@code task}
     * @param task the task to execute
     * @param result the result if successful
     */
    <T> Future<T> submit(WithResources withResources, Runnable task, T result);

    /**
     * @return true iff the caller is a worker thread actively serving this executor
     */
    boolean inExecutor();

    default <T> List<java.util.concurrent.Future<T>> invokeAll(Collection<? extends Callable<T>> tasks) throws InterruptedException
    {
        throw new UnsupportedOperationException();
    }
    default <T> List<java.util.concurrent.Future<T>> invokeAll(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit) throws InterruptedException
    {
        throw new UnsupportedOperationException();
    }
    default <T> T invokeAny(Collection<? extends Callable<T>> tasks) throws InterruptedException, ExecutionException
    {
        throw new UnsupportedOperationException();
    }
    default <T> T invokeAny(Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit) throws InterruptedException, ExecutionException, TimeoutException
    {
        throw new UnsupportedOperationException();
    }
}