groovyx.gpars.dataflow
Class Select<T>

java.lang.Object
  groovyx.gpars.dataflow.Select<T>

public class Select<T>
extends java.lang.Object

A Select allows the user to select a value from multiple channels, which have a value available for read at the moment. It can either pick a channel randomly, when using the plain select method, or with precedence towards channels with lower position indexes, when the prioritySelect method is used. If a value is not available immediately in any of the channels, Select will wait for the first value to arrive in any of the channels.

Both 'select' and 'prioritySelect' methods come in two flavours - blocking, which wait till a value is available in a channel, and messaging, which send out a message to the specified message handler, as soon as a message is available. Optionally, all methods allow the user to specify a boolean mask, assigning each select 's input channel a flag indicating, whether it should be included in the select operation. This is useful when handling state to selectively block some inputs in some states.

Author:

Vaclav Pech Date: 30th Sep 2010

Field Summary

private SelectBase<T>	selectBase
static java.lang.String	TIMEOUT A value that gets bound to timeout channels through the Select.createTimeout() method
private static java.util.Timer	timer A shared timer to run timeouts for Selects

Constructor Summary

Select(PGroup pGroup, java.util.List<SelectableChannel<? extends T>> channels)

Select(PGroup pGroup, SelectableChannel<? extends T>... channels)

Method Summary

SelectResult<T>	call() Selects a value from a single randomly chosen input channel, which has a value available for read.
SelectResult<T>	call(java.util.List<java.lang.Boolean> mask) Selects a value from a single randomly chosen input channel, which has a value available for read.
void	call(MessageStream messageStream) Selects a value from a single randomly chosen input channel, which has a value available for read.
void	call(MessageStream messageStream, java.util.List<java.lang.Boolean> mask) Selects a value from a single randomly chosen input channel, which has a value available for read.
static DataflowReadChannel<java.lang.String>	createTimeout(long timeout) Creates a timeout channel (DataflowVariable) that will bind a Select.TIMEOUT value after the specified timeout.
SelectResult<T>	prioritySelect() Selects a value from a single input channel, which has a value available for read.
SelectResult<T>	prioritySelect(java.util.List<java.lang.Boolean> mask) Selects a value from a single input channel, which has a value available for read.
void	prioritySelect(MessageStream messageStream) Selects a value from a single input channel, which has a value available for read.
void	prioritySelect(MessageStream messageStream, java.util.List<java.lang.Boolean> mask) Selects a value from a single input channel, which has a value available for read.
Promise<SelectResult<T>>	prioritySelectToPromise() Selects asynchronously a value from a single input channel, which has a value available for read.
Promise<SelectResult<T>>	prioritySelectToPromise(java.util.List<java.lang.Boolean> mask) Selects asynchronously a value from a single input channel, which has a value available for read.
SelectResult<T>	select() Selects a value from a single randomly chosen input channel, which has a value available for read.
private SelectResult<T>	select(int startIndex, java.util.List<java.lang.Boolean> mask) Invokes the internal select base with a SelectRequest instance ensuring the current thread can continue returning the correct value, once a value has been selected
SelectResult<T>	select(java.util.List<java.lang.Boolean> mask) Selects a value from a single randomly chosen input channel, which has a value available for read.
void	select(MessageStream messageStream) Selects a value from a single randomly chosen input channel, which has a value available for read.
private void	select(MessageStream messageStream, int startIndex, java.util.List<java.lang.Boolean> mask) Invokes the internal select base with a SelectRequest instance ensuring a message is sent, once a value has been selected
void	select(MessageStream messageStream, java.util.List<java.lang.Boolean> mask) Selects a value from a single randomly chosen input channel, which has a value available for read.
Promise<SelectResult<T>>	selectToPromise() Selects asynchronously a value from a single randomly chosen input channel, which has a value available for read.
private Promise<SelectResult<T>>	selectToPromise(int startIndex, java.util.List<java.lang.Boolean> mask) Invokes the internal select base with a SelectRequest instance ensuring a message is sent, once a value has been selected
Promise<SelectResult<T>>	selectToPromise(java.util.List<java.lang.Boolean> mask) /** Selects asynchronously a value from a single randomly chosen input channel, which has a value available for read.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

selectBase

private final SelectBase<T> selectBase

timer

private static final java.util.Timer timer

A shared timer to run timeouts for Selects

TIMEOUT

public static final java.lang.String TIMEOUT

A value that gets bound to timeout channels through the Select.createTimeout() method

See Also:

Constant Field Values

Constructor Detail

Select

public Select(PGroup pGroup,
              SelectableChannel<? extends T>... channels)

Parameters:

pGroup - The group, the thread pool of which should be used for notification message handlers

channels - The input channels to select from

Select

public Select(PGroup pGroup,
              java.util.List<SelectableChannel<? extends T>> channels)

Parameters:

pGroup - The group, the thread pool of which should be used for notification message handlers

channels - The list of input channels to select from

Method Detail

select

public SelectResult<T> select()
                       throws java.lang.InterruptedException

Selects a value from a single randomly chosen input channel, which has a value available for read.

Returns:

The read value. It will be of SelectResult type, holding the actual value as well as the channel index.

Throws:

java.lang.InterruptedException - If the current thread gets interrupted

select

public SelectResult<T> select(java.util.List<java.lang.Boolean> mask)
                       throws java.lang.InterruptedException

Selects a value from a single randomly chosen input channel, which has a value available for read. Only the channels marked with 'true' in the supplied mask will be considered.

Parameters:

mask - A list of boolean values indicating, whether the input channel with the same position index should be included in the selection or not

Returns:

The read value. It will be of SelectResult type, holding the actual value as well as the channel index.

Throws:

java.lang.InterruptedException - If the current thread gets interrupted

createTimeout

public static DataflowReadChannel<java.lang.String> createTimeout(long timeout)

Creates a timeout channel (DataflowVariable) that will bind a Select.TIMEOUT value after the specified timeout.

Parameters:

timeout - The delay in milliseconds to wait before the value gets bound

Returns:

A DataflowVariable instance that will have the Select.TIMEOUT value bound after the specified number of milliseconds elapse

select

public void select(MessageStream messageStream)
            throws java.lang.InterruptedException

Selects a value from a single randomly chosen input channel, which has a value available for read. The read value is send to the supplied messageStream

Parameters:

messageStream - A message stream accepting the selected value. The message will be of SelectResult type, holding the actual value as well as the channel index.

Throws:

java.lang.InterruptedException - If the current thread gets interrupted

select

public void select(MessageStream messageStream,
                   java.util.List<java.lang.Boolean> mask)
            throws java.lang.InterruptedException

Selects a value from a single randomly chosen input channel, which has a value available for read. The read value is send to the supplied messageStream

Parameters:

messageStream - A message stream accepting the selected value. The message will be of SelectResult type, holding the actual value as well as the channel index.

mask - A list of boolean values indicating, whether the input channel with the same position index should be included in the selection or not

Throws:

java.lang.InterruptedException - If the current thread gets interrupted

selectToPromise

public Promise<SelectResult<T>> selectToPromise()
                                         throws java.lang.InterruptedException

Selects asynchronously a value from a single randomly chosen input channel, which has a value available for read. The returned Promise will eventually get bound to the selected value (wrapped inside s SelectResult instance)

Throws:

java.lang.InterruptedException - If the current thread gets interrupted

selectToPromise

public Promise<SelectResult<T>> selectToPromise(java.util.List<java.lang.Boolean> mask)
                                         throws java.lang.InterruptedException

/** Selects asynchronously a value from a single randomly chosen input channel, which has a value available for read. The returned Promise will eventually get bound to the selected value (wrapped inside s SelectResult instance)

Parameters:

mask - A list of boolean values indicating, whether the input channel with the same position index should be included in the selection or not

Throws:

java.lang.InterruptedException - If the current thread gets interrupted

prioritySelect

public SelectResult<T> prioritySelect()
                               throws java.lang.InterruptedException

Selects a value from a single input channel, which has a value available for read. Channels with lower position index are preferred.

Returns:

The read value. It will be of SelectResult type, holding the actual value as well as the channel index.

Throws:

java.lang.InterruptedException - If the current thread gets interrupted

prioritySelect

public SelectResult<T> prioritySelect(java.util.List<java.lang.Boolean> mask)
                               throws java.lang.InterruptedException

Selects a value from a single input channel, which has a value available for read. Channels with lower position index are preferred. Only the channels marked with 'true' in the supplied mask will be considered.

Parameters:

mask - A list of boolean values indicating, whether the input channel with the same position index should be included in the selection or not

Returns:

The read value. It will be of SelectResult type, holding the actual value as well as the channel index.

Throws:

java.lang.InterruptedException - If the current thread gets interrupted

prioritySelect

public void prioritySelect(MessageStream messageStream)
                    throws java.lang.InterruptedException

Selects a value from a single input channel, which has a value available for read. Channels with lower position index are preferred. The read value is send to the supplied messageStream

Parameters:

messageStream - A message stream accepting the selected value. The message will be of SelectResult type, holding the actual value as well as the channel index.

Throws:

java.lang.InterruptedException - If the current thread gets interrupted

prioritySelect

public void prioritySelect(MessageStream messageStream,
                           java.util.List<java.lang.Boolean> mask)
                    throws java.lang.InterruptedException

Selects a value from a single input channel, which has a value available for read. Channels with lower position index are preferred. The read value is send to the supplied messageStream

Parameters:

messageStream - A message stream accepting the selected value. The message will be of SelectResult type, holding the actual value as well as the channel index.

mask - A list of boolean values indicating, whether the input channel with the same position index should be included in the selection or not

Throws:

java.lang.InterruptedException - If the current thread gets interrupted

prioritySelectToPromise

public Promise<SelectResult<T>> prioritySelectToPromise()
                                                 throws java.lang.InterruptedException

Selects asynchronously a value from a single input channel, which has a value available for read. Channels with lower position index are preferred. The returned Promise will eventually get bound to the selected value (wrapped inside s SelectResult instance)

Throws:

java.lang.InterruptedException - If the current thread gets interrupted

prioritySelectToPromise

public Promise<SelectResult<T>> prioritySelectToPromise(java.util.List<java.lang.Boolean> mask)
                                                 throws java.lang.InterruptedException

Selects asynchronously a value from a single input channel, which has a value available for read. Channels with lower position index are preferred. The returned Promise will eventually get bound to the selected value (wrapped inside s SelectResult instance)

Parameters:

mask - A list of boolean values indicating, whether the input channel with the same position index should be included in the selection or not

Throws:

java.lang.InterruptedException - If the current thread gets interrupted

call

public final SelectResult<T> call()
                           throws java.lang.InterruptedException

Selects a value from a single randomly chosen input channel, which has a value available for read.

Returns:

The read value. It will be of SelectResult type, holding the actual value as well as the channel index.

Throws:

java.lang.InterruptedException - If the current thread gets interrupted

call

public final SelectResult<T> call(java.util.List<java.lang.Boolean> mask)
                           throws java.lang.InterruptedException

Selects a value from a single randomly chosen input channel, which has a value available for read. Only the channels marked with 'true' in the supplied mask will be considered.

Parameters:

mask - A list of boolean values indicating, whether the input channel with the same position index should be included in the selection or not

Returns:

The read value. It will be of SelectResult type, holding the actual value as well as the channel index.

Throws:

java.lang.InterruptedException - If the current thread gets interrupted

call

public final void call(MessageStream messageStream)
                throws java.lang.InterruptedException

Selects a value from a single randomly chosen input channel, which has a value available for read. The read value is send to the supplied messageStream

Parameters:

messageStream - A message stream accepting the selected value. The message will be of SelectResult type, holding the actual value as well as the channel index.

Throws:

java.lang.InterruptedException - If the current thread gets interrupted

call

public final void call(MessageStream messageStream,
                       java.util.List<java.lang.Boolean> mask)
                throws java.lang.InterruptedException

Selects a value from a single randomly chosen input channel, which has a value available for read. The read value is send to the supplied messageStream

Parameters:

messageStream - A message stream accepting the selected value. The message will be of SelectResult type, holding the actual value as well as the channel index.

mask - A list of boolean values indicating, whether the input channel with the same position index should be included in the selection or not

Throws:

java.lang.InterruptedException - If the current thread gets interrupted

selectToPromise

private Promise<SelectResult<T>> selectToPromise(int startIndex,
                                                 java.util.List<java.lang.Boolean> mask)
                                          throws java.lang.InterruptedException

Invokes the internal select base with a SelectRequest instance ensuring a message is sent, once a value has been selected

Throws:

java.lang.InterruptedException

select

private void select(MessageStream messageStream,
                    int startIndex,
                    java.util.List<java.lang.Boolean> mask)
             throws java.lang.InterruptedException

Invokes the internal select base with a SelectRequest instance ensuring a message is sent, once a value has been selected

Throws:

java.lang.InterruptedException

select

private SelectResult<T> select(int startIndex,
                               java.util.List<java.lang.Boolean> mask)
                        throws java.lang.InterruptedException

Invokes the internal select base with a SelectRequest instance ensuring the current thread can continue returning the correct value, once a value has been selected

Throws:

java.lang.InterruptedException