Copyright 2008 - 2009 Tony Morris, Runar Bjarnason, Tom Adams, Brad Clow, Ricky Clarkson, Nick Partridge, Jason Zaugg

This software is released under an open source BSD licence.

fj.control.parallel
Class Strategy<A>

java.lang.Object
  extended by fj.control.parallel.Strategy<A>

public final class Strategy<A>
extends Object

Functional-style parallel evaluation strategies. A Strategy is a method of evaluating a product-1, yielding another product-1 from which the result of its evaluation can be retrieved at a later time.


Method Summary
static
<A> Strategy<Callable<A>>
callableStrategy(Strategy<Callable<A>> s)
          Provides a normalising strategy that fully evaluates its Callable argument.
 Strategy<A> comap(F<P1<A>,P1<A>> f)
          Maps the given transformation across this strategy's codomain (Invariant Functor pattern).
static
<A> Strategy<A>
completionStrategy(CompletionService<A> s)
          Provides a parallelization strategy that uses a CompletionService to control the method and degree of parallelism, and where each parallel task's completion is registered with the service.
<B> F<B,P1<A>>
concurry(F<B,A> f)
          Promotes a function to a concurrent function.
<B,C> F<B,F<C,P1<A>>>
concurry(F2<B,C,A> f)
          Promotes a function of arity-2 to a concurrent function.
static
<A> Effect<Future<A>>
discard()
          Returns an Effect that waits for a given Future to obtain a value, discarding the value.
 Strategy<A> errorStrategy(Effect<Error> e)
          Provides an error-handling strategy.
static
<A> Strategy<A>
errorStrategy(Strategy<A> s, Effect<Error> e)
          Provides an error-handling strategy.
static
<A> Strategy<A>
executorStrategy(ExecutorService s)
          Provides a parallelization strategy that uses an ExecutorService to control the method and degree of parallelism.
 F<P1<A>,P1<A>> f()
          Returns the functional representation of this Strategy, a function that evaluates a product-1.
static
<A> Strategy<A>
idStrategy()
          Provides a strategy that performs no evaluation of its argument.
 Strategy<A> map(F<P1<A>,P1<A>> f)
          Maps the given transformation across this strategy's domain (Invariant Functor pattern).
static
<A> List<P1<A>>
mergeAll(List<Future<A>> xs)
          Waits for every Future in a list to obtain a value, and collects those values in a list.
static
<A> F<Future<A>,P1<A>>
obtain()
          Returns a function which returns a product-1 which waits for the given Future to obtain a value.
static
<A> P1<A>
obtain(Future<A> t)
          Provides a product-1 that waits for the given future to obtain a value.
 P1<A> par(P1<A> a)
          Apply the strategy to the given product-1.
static
<A,B> P1<Array<B>>
parFlatMap(Strategy<Array<B>> s, F<A,Array<B>> f, Array<A> as)
          Binds the given function in parallel across the given array, using the given strategy, with a final join.
static
<A,B> P1<List<B>>
parFlatMap(Strategy<List<B>> s, F<A,List<B>> f, List<A> as)
          Binds the given function in parallel across the given list, using the given strategy, with a final join.
 P1<List<A>> parList(List<P1<A>> ps)
          Evaluates a list of product-1s in parallel.
static
<A> P1<List<A>>
parListChunk(Strategy<List<A>> s, int chunkLength, List<P1<A>> as)
          Sequentially evaluates chunks (sub-sequences) of a list in parallel.
<B> P1<Array<A>>
parMap(F<B,A> f, Array<B> bs)
          Maps the given function over the given array in parallel using this strategy.
<B> P1<List<A>>
parMap(F<B,A> f, List<B> bs)
          Maps the given function over the given list in parallel using this strategy.
<B> Array<A>
parMap1(F<B,A> f, Array<B> bs)
          A strict version of parMap over arrays.
<B> List<A>
parMap1(F<B,A> f, List<B> bs)
          A strict version of parMap over lists.
<B> F<F<B,A>,F<Array<B>,P1<Array<A>>>>
parMapArray()
          First-class version of parMap on arrays.
<B> F<Array<B>,P1<Array<A>>>
parMapArray(F<B,A> f)
          Promotes a function to a parallel function on arrays using this strategy.
<B> F<F<B,A>,F<Array<B>,Array<A>>>
parMapArray1()
          First-class version of parMap1 on arrays (parallel array functor).
<B> F<F<B,A>,F<List<B>,P1<List<A>>>>
parMapList()
          First-class version of parMap on lists.
<B> F<List<B>,P1<List<A>>>
parMapList(F<B,A> f)
          Promotes a function to a parallel function on lists using this strategy.
<B> F<F<B,A>,F<List<B>,List<A>>>
parMapList1()
          First-class version of parMap1 on lists (parallel list functor).
<B,C> F2<Array<B>,Array<C>,P1<Array<A>>>
parZipArrayWith(F2<B,C,A> f)
          Lifts a given function of arity-2 so that it zips together two arrays in parallel, using this strategy, calling the function once for each corresponding pair in the arrays, position-wise.
<B,C> F2<List<B>,List<C>,P1<List<A>>>
parZipListWith(F2<B,C,A> f)
          Lifts a given function of arity-2 so that it zips together two lists in parallel, using this strategy, calling the function once for each corresponding pair in the lists, position-wise.
<B,C> P1<Array<A>>
parZipWith(F2<B,C,A> f, Array<B> bs, Array<C> cs)
          Zips together two arrays in parallel using a given function, with this strategy.
<B,C> P1<List<A>>
parZipWith(F2<B,C,A> f, List<B> bs, List<C> cs)
          Zips together two lists in parallel using a given function, with this strategy.
static
<A> Strategy<A>
seqStrategy()
          Provides a strategy that performs sequential (non-concurrent) evaluation of its argument.
static
<A> Strategy<A>
simpleThreadStrategy()
          Provides a simple parallelization strategy that creates, and discards, a new thread for every evaluation.
static
<A> Strategy<A>
strategy(F<P1<A>,P1<A>> f)
          Constructs a strategy from the given evaluation function.
<B> Strategy<B>
xmap(F<P1<A>,P1<B>> f, F<P1<B>,P1<A>> g)
          Maps the given bijective transformation across this strategy (Exponential Functor pattern).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

f

public F<P1<A>,P1<A>> f()
Returns the functional representation of this Strategy, a function that evaluates a product-1.

Returns:
The function representing this strategy, which evaluates a product-1.

strategy

public static <A> Strategy<A> strategy(F<P1<A>,P1<A>> f)
Constructs a strategy from the given evaluation function.

Parameters:
f - The execution function for the strategy
Returns:
A strategy that uses the given function to evaluate product-1s.

par

public P1<A> par(P1<A> a)
Apply the strategy to the given product-1.

Parameters:
a - A P1 to evaluate according to this strategy.
Returns:
A P1 that yields the value from calling the given product-1.

concurry

public <B> F<B,P1<A>> concurry(F<B,A> f)
Promotes a function to a concurrent function.

Parameters:
f - A function to promote to a concurrent function.
Returns:
A function that executes concurrently when called, yielding a Future value.

concurry

public <B,C> F<B,F<C,P1<A>>> concurry(F2<B,C,A> f)
Promotes a function of arity-2 to a concurrent function.

Parameters:
f - The function to promote to a concurrent function.
Returns:
A function that executes concurrently when called, yielding a product-1 that returns the value.

mergeAll

public static <A> List<P1<A>> mergeAll(List<Future<A>> xs)
Waits for every Future in a list to obtain a value, and collects those values in a list.

Parameters:
xs - The list of Futures from which to get values.
Returns:
A list of values extracted from the Futures in the argument list.

parList

public P1<List<A>> parList(List<P1<A>> ps)
Evaluates a list of product-1s in parallel.

Parameters:
ps - A list to evaluate in parallel.
Returns:
A list of the values of the product-1s in the argument.

parMap

public <B> P1<List<A>> parMap(F<B,A> f,
                              List<B> bs)
Maps the given function over the given list in parallel using this strategy.

Parameters:
f - A function to map over the given list in parallel.
bs - A list over which to map the given function in parallel.
Returns:
A product-1 that returns the list with all of its elements transformed by the given function.

parMap

public <B> P1<Array<A>> parMap(F<B,A> f,
                               Array<B> bs)
Maps the given function over the given array in parallel using this strategy.

Parameters:
f - A function to map over the given array in parallel.
bs - An array over which to map the given function in parallel.
Returns:
A product-1 that returns the array with all of its elements transformed by the given function.

parMap1

public <B> List<A> parMap1(F<B,A> f,
                           List<B> bs)
A strict version of parMap over lists. Maps the given function over the given list in parallel using this strategy, blocking the current thread until all values have been obtained.

Parameters:
f - A function to map over the given list in parallel.
bs - A list over which to map the given function in parallel.
Returns:
A list with all of its elements transformed by the given function.

parMap1

public <B> Array<A> parMap1(F<B,A> f,
                            Array<B> bs)
A strict version of parMap over arrays. Maps the given function over the given arrays in parallel using this strategy, blocking the current thread until all values have been obtained.

Parameters:
f - A function to map over the given array in parallel.
bs - An array over which to map the given function in parallel.
Returns:
An array with all of its elements transformed by the given function.

parMapList

public <B> F<List<B>,P1<List<A>>> parMapList(F<B,A> f)
Promotes a function to a parallel function on lists using this strategy.

Parameters:
f - A function to transform into a parallel function on lists.
Returns:
The function transformed into a parallel function on lists.

parMapList

public <B> F<F<B,A>,F<List<B>,P1<List<A>>>> parMapList()
First-class version of parMap on lists.

Returns:
A function that promotes another function to a parallel function on lists.

parMapList1

public <B> F<F<B,A>,F<List<B>,List<A>>> parMapList1()
First-class version of parMap1 on lists (parallel list functor).

Returns:
A function that promotes another function to a blocking parallel function on lists.

parMapArray

public <B> F<Array<B>,P1<Array<A>>> parMapArray(F<B,A> f)
Promotes a function to a parallel function on arrays using this strategy.

Parameters:
f - A function to transform into a parallel function on arrays.
Returns:
The function transformed into a parallel function on arrays.

parMapArray

public <B> F<F<B,A>,F<Array<B>,P1<Array<A>>>> parMapArray()
First-class version of parMap on arrays.

Returns:
A function that promotes another function to a parallel function on arrays.

parMapArray1

public <B> F<F<B,A>,F<Array<B>,Array<A>>> parMapArray1()
First-class version of parMap1 on arrays (parallel array functor).

Returns:
A function that promotes another function to a blocking parallel function on arrays.

parFlatMap

public static <A,B> P1<List<B>> parFlatMap(Strategy<List<B>> s,
                                           F<A,List<B>> f,
                                           List<A> as)
Binds the given function in parallel across the given list, using the given strategy, with a final join.

Parameters:
s - The strategy to use for parallelization.
f - The function to bind across the given list.
as - The list across which to bind the given function.
Returns:
A P1 containing the result of the parallel map operation after the final join.

parFlatMap

public static <A,B> P1<Array<B>> parFlatMap(Strategy<Array<B>> s,
                                            F<A,Array<B>> f,
                                            Array<A> as)
Binds the given function in parallel across the given array, using the given strategy, with a final join.

Parameters:
s - The strategy to use for parallelization.
f - The function to bind across the given array.
as - The array across which to bind the given function.
Returns:
A P1 containing the result of the parallel map operation after the final join.

parListChunk

public static <A> P1<List<A>> parListChunk(Strategy<List<A>> s,
                                           int chunkLength,
                                           List<P1<A>> as)
Sequentially evaluates chunks (sub-sequences) of a list in parallel. Splits the list into chunks, evaluating the chunks simultaneously, but each chunk as a sequence.

Parameters:
s - The strategy to use for parallelization.
chunkLength - The length of each sequence.
as - The list to evaluate in parallel chunks.
Returns:
A product-1 containing the list of results extracted from the given list of product-1s.

parZipWith

public <B,C> P1<List<A>> parZipWith(F2<B,C,A> f,
                                    List<B> bs,
                                    List<C> cs)
Zips together two lists in parallel using a given function, with this strategy. Calls the given function once for each corresponding pair in the lists, position-wise, passing elements from the first list to the first argument of the function, and elements from the second list to the second argument of the function, yielding a list of the results. If the lists are not of the same length, the remaining elements of the longer list are ignored.

Parameters:
f - The function of arity-2 with which to zip.
bs - A list to zip with the given function.
cs - A list to zip with the given function.
Returns:
The list of the results of calling the given function on corresponding elements of the given lists.

parZipWith

public <B,C> P1<Array<A>> parZipWith(F2<B,C,A> f,
                                     Array<B> bs,
                                     Array<C> cs)
Zips together two arrays in parallel using a given function, with this strategy. Calls the given function once for each corresponding pair in the arrays, position-wise, passing elements from the first array to the first argument of the function, and elements from the second array to the second argument of the function, yielding a array of the results. If the arrays are not of the same length, the remaining elements of the longer array are ignored.

Parameters:
f - The function of arity-2 with which to zip.
bs - A array to zip with the given function.
cs - A array to zip with the given function.
Returns:
The array of the results of calling the given function on corresponding elements of the given arrays.

parZipListWith

public <B,C> F2<List<B>,List<C>,P1<List<A>>> parZipListWith(F2<B,C,A> f)
Lifts a given function of arity-2 so that it zips together two lists in parallel, using this strategy, calling the function once for each corresponding pair in the lists, position-wise.

Parameters:
f - The function of arity-2 with which to zip.
Returns:
A transformation that zips two lists using the argument function, in parallel.

parZipArrayWith

public <B,C> F2<Array<B>,Array<C>,P1<Array<A>>> parZipArrayWith(F2<B,C,A> f)
Lifts a given function of arity-2 so that it zips together two arrays in parallel, using this strategy, calling the function once for each corresponding pair in the arrays, position-wise.

Parameters:
f - The function of arity-2 with which to zip.
Returns:
A transformation that zips two arrays using the argument function, in parallel.

obtain

public static <A> F<Future<A>,P1<A>> obtain()
Returns a function which returns a product-1 which waits for the given Future to obtain a value.

Returns:
A function which, given a Future, yields a product-1 that waits for it.

obtain

public static <A> P1<A> obtain(Future<A> t)
Provides a product-1 that waits for the given future to obtain a value.

Parameters:
t - A Future for which to wait.
Returns:
A product-1 that waits for the given future to obtain a value.

discard

public static <A> Effect<Future<A>> discard()
Returns an Effect that waits for a given Future to obtain a value, discarding the value.

Returns:
An effect, which, given a Future, waits for it to obtain a value, discarding the value.

simpleThreadStrategy

public static <A> Strategy<A> simpleThreadStrategy()
Provides a simple parallelization strategy that creates, and discards, a new thread for every evaluation.

Returns:
a simple parallelization strategy that creates, and discards, a new thread for every evaluation.

executorStrategy

public static <A> Strategy<A> executorStrategy(ExecutorService s)
Provides a parallelization strategy that uses an ExecutorService to control the method and degree of parallelism.

Parameters:
s - The ExecutorService to use for scheduling evaluations.
Returns:
A Strategy that uses the provided ExecutorService to control the method and degree of parallelism.

completionStrategy

public static <A> Strategy<A> completionStrategy(CompletionService<A> s)
Provides a parallelization strategy that uses a CompletionService to control the method and degree of parallelism, and where each parallel task's completion is registered with the service.

Parameters:
s - The CompletionService to use for scheduling evaluations and detect their completion.
Returns:
A Strategy that uses the provided CompletionService to control the method and degree of parallelism, and notifies the service of task completion.

seqStrategy

public static <A> Strategy<A> seqStrategy()
Provides a strategy that performs sequential (non-concurrent) evaluation of its argument.

Returns:
A strategy that performs sequential (non-concurrent) evaluation of its argument.

idStrategy

public static <A> Strategy<A> idStrategy()
Provides a strategy that performs no evaluation of its argument.

Returns:
A strategy that performs no evaluation of its argument.

xmap

public <B> Strategy<B> xmap(F<P1<A>,P1<B>> f,
                            F<P1<B>,P1<A>> g)
Maps the given bijective transformation across this strategy (Exponential Functor pattern).

Parameters:
f - A transformation from this strategy's codomain to the resulting strategy's codomain.
g - A transformation from the resulting strategy's domain to this strategy's domain.
Returns:
A new strategy that maps to this strategy and back again.

map

public Strategy<A> map(F<P1<A>,P1<A>> f)
Maps the given transformation across this strategy's domain (Invariant Functor pattern).

Parameters:
f - A transformation from this strategy's codomain to the resulting strategy's codomain.
Returns:
A new strategy that applies the given transformation after each application of this strategy.

comap

public Strategy<A> comap(F<P1<A>,P1<A>> f)
Maps the given transformation across this strategy's codomain (Invariant Functor pattern).

Parameters:
f - A transformation from the resulting strategy's domain to this strategy's domain.
Returns:
A new strategy that applies the given transformation before each application of this strategy.

errorStrategy

public Strategy<A> errorStrategy(Effect<Error> e)
Provides an error-handling strategy. Captures any uncaught runtime errors encountered by this strategy and applies the given side-effect to them.

Parameters:
e - The effect that should handle errors.
Returns:
A strategy that captures any runtime errors with a side-effect.

errorStrategy

public static <A> Strategy<A> errorStrategy(Strategy<A> s,
                                            Effect<Error> e)
Provides an error-handling strategy. Captures any uncaught runtime errors encountered by the given strategy and applies the given side-effect to them.

Parameters:
s - The strategy to equip with an error-handling effect.
e - The effect that should handle errors.
Returns:
A strategy that captures any runtime errors with a side-effect.

callableStrategy

public static <A> Strategy<Callable<A>> callableStrategy(Strategy<Callable<A>> s)
Provides a normalising strategy that fully evaluates its Callable argument.

Parameters:
s - A non-normalising strategy to use for the evaluation.
Returns:
A new strategy that fully evaluates Callables, using the given strategy.

Copyright 2008 - 2009 Tony Morris, Runar Bjarnason, Tom Adams, Brad Clow, Ricky Clarkson, Nick Partridge, Jason Zaugg

This software is released under an open source BSD licence.