Routine (Javadoc - jroutine)

Type Parameters:
IN - the input data type.
OUT - the output data type.

All Known Subinterfaces:

FunctionalRoutine<IN,OUT>, RoutineBuilder<IN,OUT>

All Known Implementing Classes:

AbstractRoutine, TemplateRoutine, TemplateRoutineBuilder
```
public interface Routine<IN,OUT>
```
This interface defines the main component of the library architecture.
The interface takes inspiration from the Go routines, where functions are executed asynchronously and communicate with the external world only through channels. Being Java a strictly object oriented programming language, the routine itself must be an object based on logic implemented in other objects.
The library includes a routine class based on the implementation of an invocation interface. Invocation objects are dynamically instantiated when needed, effectively mimicking the temporary scope of a function call.
The paradigm is based on input, result and output channels. A routine can be invoked in different ways (as explained below). Each routine invocation returns an input channel through which the caller can pass the input parameters. When all the parameters has been passed, the input channel is closed and returns the output channel from which to read the invocation results. At the same time a result channel is passed to the invocation implementation, so that the output computed from the input parameters can be published outside.
The advantage of this approach is that the invocation flow can be run in steps, allowing for continuous streaming of the input data and for abortion in the middle of the execution, without blocking the running thread for the whole duration of the asynchronous invocation.
In fact, each channel can abort the execution at any time.
The implementing class must provides an automatic synchronization of the invocation member fields, though, in order to avoid concurrency issues, data passed through the routine channels should be immutable or, at least, never shared inside and outside the routine.
Moreover, it is possible to recursively call the same or another routine from inside a routine invocation in a safe way. Nevertheless, it is not allow to perform blocking calls (such as reading data from an output channel) in the middle of an execution when shared runner instances are employed. Additionally, to prevent deadlock or starvation issues, it is encouraged the use of finite timeouts when performing blocking calls.
The routine object provides three different ways to invoke an execution:
Synchronous invocation
The routine starts an invocation employing a synchronous runner. The result is similar to a classic method call where the processing completes as soon as the function exits.
Asynchronous invocation
The routine starts an invocation employing an asynchronous runner. In this case the processing happens in a different thread, while the calling process may go on with its own execution and perform other tasks. The invocation results can be collected at any time through the output channel methods.
Parallel invocation
Processing parallelization is the key to leverage the power of multi-core machines. In order to achieve it, the input data must be divided into subsets which are then processed on different threads.
A routine object provides a convenient way to start an invocation which in turn spawns another invocation for each input passed. This particular type of invocation obviously produces meaningful results only for routines which takes a single input parameter and computes the relative output results.
It is worth noting how the library has been designed only through interfaces, so that, as far as the implementation honors the specific contracts, it is possible to seamlessly combine different routine instances, even the ones coming from third party libraries.
Created by davide-maestroni on 09/07/2014.

Method Summary

Methods
Modifier and Type	Method and Description
`Channel.OutputChannel<OUT>`	`asyncCall()` Short for `asyncInvoke().result()`.
`Channel.OutputChannel<OUT>`	`asyncCall(Channel.OutputChannel<? extends IN> inputs)` Short for `asyncInvoke().pass(inputs).result()`.
`Channel.OutputChannel<OUT>`	`asyncCall(IN... inputs)` Short for `asyncInvoke().pass(inputs).result()`.
`Channel.OutputChannel<OUT>`	`asyncCall(IN input)` Short for `asyncInvoke().pass(input).result()`.
`Channel.OutputChannel<OUT>`	`asyncCall(Iterable<? extends IN> inputs)` Short for `asyncInvoke().pass(inputs).result()`.
`InvocationChannel<IN,OUT>`	`asyncInvoke()` Invokes the execution of this routine in asynchronous mode.
`Channel.OutputChannel<OUT>`	`parallelCall()` Short for `parallelInvoke().result()`.
`Channel.OutputChannel<OUT>`	`parallelCall(Channel.OutputChannel<? extends IN> inputs)` Short for `parallelInvoke().pass(inputs).result()`.
`Channel.OutputChannel<OUT>`	`parallelCall(IN... inputs)` Short for `parallelInvoke().pass(inputs).result()`.
`Channel.OutputChannel<OUT>`	`parallelCall(IN input)` Short for `parallelInvoke().pass(input).result()`.
`Channel.OutputChannel<OUT>`	`parallelCall(Iterable<? extends IN> inputs)` Short for `parallelInvoke().pass(inputs).result()`.
`InvocationChannel<IN,OUT>`	`parallelInvoke()` Invokes the execution of this routine in parallel mode.
`void`	`purge()` Makes the routine destroy all the cached invocation instances.
`Channel.OutputChannel<OUT>`	`syncCall()` Short for `syncInvoke().result()`.
`Channel.OutputChannel<OUT>`	`syncCall(Channel.OutputChannel<? extends IN> inputs)` Short for `syncInvoke().pass(inputs).result()`.
`Channel.OutputChannel<OUT>`	`syncCall(IN... inputs)` Short for `syncInvoke().pass(inputs).result()`.
`Channel.OutputChannel<OUT>`	`syncCall(IN input)` Short for `syncInvoke().pass(input).result()`.
`Channel.OutputChannel<OUT>`	`syncCall(Iterable<? extends IN> inputs)` Short for `syncInvoke().pass(inputs).result()`.
`InvocationChannel<IN,OUT>`	`syncInvoke()` Invokes the execution of this routine in synchronous mode.

- Method Detail
  - asyncCall
```
@NotNull
Channel.OutputChannel<OUT> asyncCall()
```
    Short for asyncInvoke().result().
    
    Returns:
    the output channel.
  - asyncCall
```
@NotNull
Channel.OutputChannel<OUT> asyncCall(@Nullable
                                           IN input)
```
    Short for asyncInvoke().pass(input).result().
    
    Parameters:
    input - the input.
    
    Returns:
    the output channel.
  - asyncCall
```
@NotNull
Channel.OutputChannel<OUT> asyncCall(@Nullable
                                           IN... inputs)
```
    Short for asyncInvoke().pass(inputs).result().
    
    Parameters:
    inputs - the input data.
    
    Returns:
    the output channel.
  - asyncCall
```
@NotNull
Channel.OutputChannel<OUT> asyncCall(@Nullable
                                           Iterable<? extends IN> inputs)
```
    Short for asyncInvoke().pass(inputs).result().
    
    Parameters:
    inputs - the iterable returning the input data.
    
    Returns:
    the output channel.
  - asyncCall
```
@NotNull
Channel.OutputChannel<OUT> asyncCall(@Nullable
                                           Channel.OutputChannel<? extends IN> inputs)
```
    Short for asyncInvoke().pass(inputs).result().
    
    Parameters:
    inputs - the output channel returning the input data.
    
    Returns:
    the output channel.
  - asyncInvoke
```
@NotNull
InvocationChannel<IN,OUT> asyncInvoke()
```
    Invokes the execution of this routine in asynchronous mode.
    
    Returns:
    the invocation channel.
  - parallelCall
```
@NotNull
Channel.OutputChannel<OUT> parallelCall()
```
    Short for parallelInvoke().result().
    (This method actually makes little sense, and should never need to be called, thought it is here for completeness)
    
    Returns:
    the output channel.
  - parallelCall
```
@NotNull
Channel.OutputChannel<OUT> parallelCall(@Nullable
                                              IN input)
```
    Short for parallelInvoke().pass(input).result().
    (This method actually makes little sense, and should never need to be called, thought it is here for completeness)
    
    Parameters:
    input - the input.
    
    Returns:
    the output channel.
  - parallelCall
```
@NotNull
Channel.OutputChannel<OUT> parallelCall(@Nullable
                                              IN... inputs)
```
    Short for parallelInvoke().pass(inputs).result().
    
    Parameters:
    inputs - the input data.
    
    Returns:
    the output channel.
  - parallelCall
```
@NotNull
Channel.OutputChannel<OUT> parallelCall(@Nullable
                                              Iterable<? extends IN> inputs)
```
    Short for parallelInvoke().pass(inputs).result().
    
    Parameters:
    inputs - the iterable returning the input data.
    
    Returns:
    the output channel.
  - parallelCall
```
@NotNull
Channel.OutputChannel<OUT> parallelCall(@Nullable
                                              Channel.OutputChannel<? extends IN> inputs)
```
    Short for parallelInvoke().pass(inputs).result().
    
    Parameters:
    inputs - the output channel returning the input data.
    
    Returns:
    the output channel.
  - parallelInvoke
```
@NotNull
InvocationChannel<IN,OUT> parallelInvoke()
```
    Invokes the execution of this routine in parallel mode.
    
    Returns:
    the invocation channel.
  - purge
```
void purge()
```
    Makes the routine destroy all the cached invocation instances.
    This method is useful to force the release of external resources when done with the routine. Note however that the routine will still be usable after the method returns.
    Normally it is not needed to call this method.
  - syncCall
```
@NotNull
Channel.OutputChannel<OUT> syncCall()
```
    Short for syncInvoke().result().
    
    Returns:
    the output channel.
  - syncCall
```
@NotNull
Channel.OutputChannel<OUT> syncCall(@Nullable
                                          IN input)
```
    Short for syncInvoke().pass(input).result().
    
    Parameters:
    input - the input.
    
    Returns:
    the output channel.
  - syncCall
```
@NotNull
Channel.OutputChannel<OUT> syncCall(@Nullable
                                          IN... inputs)
```
    Short for syncInvoke().pass(inputs).result().
    
    Parameters:
    inputs - the input data.
    
    Returns:
    the output channel.
  - syncCall
```
@NotNull
Channel.OutputChannel<OUT> syncCall(@Nullable
                                          Iterable<? extends IN> inputs)
```
    Short for syncInvoke().pass(inputs).result().
    
    Parameters:
    inputs - the iterable returning the input data.
    
    Returns:
    the output channel.
  - syncCall
```
@NotNull
Channel.OutputChannel<OUT> syncCall(@Nullable
                                          Channel.OutputChannel<? extends IN> inputs)
```
    Short for syncInvoke().pass(inputs).result().
    
    Parameters:
    inputs - the output channel returning the input data.
    
    Returns:
    the output channel.
  - syncInvoke
```
@NotNull
InvocationChannel<IN,OUT> syncInvoke()
```
    Invokes the execution of this routine in synchronous mode.
    
    Returns:
    the invocation channel.

Interface Routine<IN,OUT>

Method Summary

Method Detail

asyncCall

asyncCall

asyncCall

asyncCall

asyncCall

asyncInvoke

parallelCall

parallelCall

parallelCall

parallelCall

parallelCall

parallelInvoke

purge

syncCall

syncCall

syncCall

syncCall

syncCall

syncInvoke