//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//

package org.eclipse.jetty.util.thread;

An ExecutionStrategy executes Runnable tasks produced by a Producer. The strategy to execute the task may vary depending on the implementation; the task may be run in the calling thread, or in a new thread, etc.
The strategy delegates the production of tasks to a Producer, and continues to execute tasks until the producer continues to produce them.
/**
 * <p>An {@link ExecutionStrategy} executes {@link Runnable} tasks produced by a {@link Producer}.
 * The strategy to execute the task may vary depending on the implementation; the task may be
 * run in the calling thread, or in a new thread, etc.</p>
 * <p>The strategy delegates the production of tasks to a {@link Producer}, and continues to
 * execute tasks until the producer continues to produce them.</p>
 */
public interface ExecutionStrategy
{
    
Initiates (or resumes) the task production and consumption.
This method guarantees that the task is never run by the
thread that called this method.
TODO review the need for this (only used by HTTP2 push)
See Also:
produce()/**
     * <p>Initiates (or resumes) the task production and consumption.</p>
     * <p>This method guarantees that the task is never run by the
     * thread that called this method.</p>
     *
     * TODO review the need for this (only used by HTTP2 push)
     *
     * @see #produce()
     */
    public void dispatch();

    
Initiates (or resumes) the task production and consumption.
The produced task may be run by the same thread that called
this method.
See Also:
dispatch()/**
     * <p>Initiates (or resumes) the task production and consumption.</p>
     * <p>The produced task may be run by the same thread that called
     * this method.</p>
     *
     * @see #dispatch()
     */
    public void produce();

    
A producer of Runnable tasks to run.
The ExecutionStrategy will repeatedly invoke produce() until the producer returns null, indicating that it has nothing more to produce.
When no more tasks can be produced, implementations should arrange for the ExecutionStrategy to be invoked again in case an external event resumes the tasks production.
/**
     * <p>A producer of {@link Runnable} tasks to run.</p>
     * <p>The {@link ExecutionStrategy} will repeatedly invoke {@link #produce()} until
     * the producer returns null, indicating that it has nothing more to produce.</p>
     * <p>When no more tasks can be produced, implementations should arrange for the
     * {@link ExecutionStrategy} to be invoked again in case an external event resumes
     * the tasks production.</p>
     */
    public interface Producer
    {
        
Produces a task to be executed.
Returns:
a task to executed or null if there are no more tasks to execute/**
         * <p>Produces a task to be executed.</p>
         *
         * @return a task to executed or null if there are no more tasks to execute
         */
        Runnable produce();
    }
}