com.gh.bmd.jrt.channel.OutputChannel Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jroutine Show documentation
Parallel programming on the go
There is a newer version: 5.9.0
/*
 * Licensed 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 com.gh.bmd.jrt.channel;

import com.gh.bmd.jrt.util.TimeDuration;

import java.util.Collection;
import java.util.Iterator;
import java.util.List;
import java.util.concurrent.TimeUnit;

import javax.annotation.Nonnull;

/**
 * Interface defining an output channel, that is the channel used to read the routine invocation
 * output data.
 * 
 * Note that the delivery order of the output data might not be guaranteed.
 * 

 * Created by davide-maestroni on 9/4/14.
 *
 * @param  the output data type.
 */
public interface OutputChannel extends Channel, Iterator, Iterable {

    /**
     * Tells the channel to wait at the max the specified time duration for the next result to be
     * available.
     * 

     * By default the timeout is set to 0 to avoid unexpected deadlocks.
     *
     * @param timeout the maximum timeout.
     * @return this channel.
     */
    @Nonnull
    OutputChannel afterMax(@Nonnull TimeDuration timeout);

    /**
     * Tells the channel to wait at the max the specified time duration for the next result to be
     * available.
     * 

     * By default the timeout is set to 0 to avoid unexpected deadlocks.
     *
     * @param timeout  the maximum timeout value.
     * @param timeUnit the timeout time unit.
     * @return this channel.
     * @throws java.lang.IllegalArgumentException if the specified timeout is negative.
     */
    @Nonnull
    OutputChannel afterMax(long timeout, @Nonnull TimeUnit timeUnit);

    /**
     * Consumes all the results by waiting for the routine to complete at the maximum for the set
     * timeout.
     *
     * @return this channel.
     * @throws com.gh.bmd.jrt.channel.ExecutionTimeoutException if the channel is set to throw an
     *                                                          exception when the timeout elapses.
     * @throws com.gh.bmd.jrt.channel.RoutineException          if the execution has been aborted.
     * @throws java.lang.IllegalStateException                  if this channel is already bound
     *                                                          to a consumer.
     * @see #afterMax(com.gh.bmd.jrt.util.TimeDuration)
     * @see #afterMax(long, java.util.concurrent.TimeUnit)
     * @see #eventually()
     * @see #immediately()
     * @see #eventuallyAbort()
     * @see #eventuallyExit()
     * @see #eventuallyThrow()
     */
    @Nonnull
    List all();

    /**
     * Consumes all the results by waiting for the routine to complete at the maximum for the set
     * timeout, and put them into the specified collection.
     *
     * @param results the collection to fill.
     * @return this channel.
     * @throws com.gh.bmd.jrt.channel.ExecutionTimeoutException if the channel is set to throw an
     *                                                          exception when the timeout elapses.
     * @throws com.gh.bmd.jrt.channel.RoutineException          if the execution has been aborted.
     * @throws java.lang.IllegalStateException                  if this channel is already bound
     *                                                          to a consumer.
     * @see #afterMax(TimeDuration)
     * @see #afterMax(long, java.util.concurrent.TimeUnit)
     * @see #eventually()
     * @see #immediately()
     * @see #eventuallyAbort()
     * @see #eventuallyExit()
     * @see #eventuallyThrow()
     */
    @Nonnull
    OutputChannel allInto(@Nonnull Collection results);

    /**
     * Checks if the routine is complete, waiting at the maximum for the set timeout.
     *
     * @return whether the routine execution has complete.
     * @see #afterMax(com.gh.bmd.jrt.util.TimeDuration)
     * @see #afterMax(long, java.util.concurrent.TimeUnit)
     * @see #immediately()
     */
    boolean checkComplete();

    /**
     * Tells the channel to wait indefinitely for results to be available.
     * 

     * By default the timeout is set to 0 to avoid unexpected deadlocks.
     *
     * @return this channel.
     */
    @Nonnull
    OutputChannel eventually();

    /**
     * Tells the channel to abort the invocation execution in case no result is available before
     * the timeout has elapsed.
     * 

     * By default an {@link com.gh.bmd.jrt.channel.ExecutionTimeoutException
     * ExecutionTimeoutException} exception will be thrown.
     *
     * @return this channel.
     * @see #afterMax(com.gh.bmd.jrt.util.TimeDuration)
     * @see #afterMax(long, java.util.concurrent.TimeUnit)
     * @see #immediately()
     * @see #eventuallyExit()
     * @see #eventuallyThrow()
     */
    @Nonnull
    OutputChannel eventuallyAbort();

    /**
     * Tells the channel to break execution in case no result is available before the timeout has
     * elapsed.
     * 

     * By default an {@link com.gh.bmd.jrt.channel.ExecutionTimeoutException
     * ExecutionTimeoutException} exception will be thrown.
     *
     * @return this channel.
     * @see #afterMax(com.gh.bmd.jrt.util.TimeDuration)
     * @see #afterMax(long, java.util.concurrent.TimeUnit)
     * @see #immediately()
     * @see #eventuallyAbort()
     * @see #eventuallyThrow()
     */
    @Nonnull
    OutputChannel eventuallyExit();

    /**
     * Tells the channel to throw an {@link com.gh.bmd.jrt.channel.ExecutionTimeoutException
     * ExecutionTimeoutException} in case no result is available before the timeout has elapsed.
     * 

     * This is the default behavior.
     *
     * @return this channel.
     * @see #afterMax(com.gh.bmd.jrt.util.TimeDuration)
     * @see #afterMax(long, java.util.concurrent.TimeUnit)
     * @see #immediately()
     * @see #eventuallyAbort()
     * @see #eventuallyExit()
     */
    @Nonnull
    OutputChannel eventuallyThrow();

    /**
     * Checks if more results are available by waiting at the maximum for the set timeout.
     *
     * @return whether at least one result is available.
     * @throws com.gh.bmd.jrt.channel.ExecutionTimeoutException if the channel is set to throw an
     *                                                          exception when the timeout elapses.
     * @throws com.gh.bmd.jrt.channel.RoutineException          if the execution has been aborted.
     * @throws java.lang.IllegalStateException                  if this channel is already bound
     *                                                          to a consumer.
     * @see #afterMax(com.gh.bmd.jrt.util.TimeDuration)
     * @see #afterMax(long, java.util.concurrent.TimeUnit)
     * @see #eventually()
     * @see #immediately()
     * @see #eventuallyAbort()
     * @see #eventuallyExit()
     * @see #eventuallyThrow()
     */
    boolean hasNext();

    /**
     * Consumes the first available result by waiting at the maximum for the set timeout.
     *
     * @return the first available result.
     * @throws com.gh.bmd.jrt.channel.ExecutionTimeoutException if the channel is set to throw an
     *                                                          exception when the timeout elapses.
     * @throws com.gh.bmd.jrt.channel.RoutineException          if the execution has been aborted.
     * @throws java.lang.IllegalStateException                  if this channel is already bound
     *                                                          to a consumer.
     * @throws java.util.NoSuchElementException                 if no output is available (it might
     *                                                          be thrown also in the case the read
     *                                                          timeout elapses and no timeout
     *                                                          exception is set to be thrown).
     * @see #afterMax(com.gh.bmd.jrt.util.TimeDuration)
     * @see #afterMax(long, java.util.concurrent.TimeUnit)
     * @see #eventually()
     * @see #immediately()
     * @see #eventuallyAbort()
     * @see #eventuallyExit()
     * @see #eventuallyThrow()
     */
    OUTPUT next();

    /**
     * Tells the channel to not wait for results to be available.
     * 
     * By default the timeout is set to 0 to avoid unexpected deadlocks.
     *
     * @return this channel.
     */
    @Nonnull
    OutputChannel immediately();

    /**
     * Checks if this channel is bound to a consumer or another channel.
     *
     * @return whether the channel is bound.
     * @see #passTo(InputChannel)
     * @see #passTo(OutputConsumer)
     */
    boolean isBound();

    /**
     * Binds this channel to the specified one. After the call, all the output will be passed
     * only to the specified input channel. Attempting to read through the dedicated methods will
     * cause an {@link java.lang.IllegalStateException} to be thrown.
     *
     * @param channel the input channel
     * @param  the input data type.
     * @return this channel.
     * @throws java.lang.IllegalStateException if this channel is already bound.
     */
    @Nonnull
    > INPUT passTo(@Nonnull INPUT channel);

    /**
     * Binds this channel to the specified consumer. After the call, all the output will be passed
     * only to the consumer. Attempting to read through the dedicated methods will cause an
     * {@link java.lang.IllegalStateException} to be thrown.

     * Note that the consumer methods will be called on the runner thread.
     *
     * @param consumer the consumer instance.
     * @return this channel.
     * @throws java.lang.IllegalStateException if this channel is already bound.
     */
    @Nonnull
    OutputChannel passTo(@Nonnull OutputConsumer consumer);
}