Package fj.control.parallel

Class Strategy<A>

  • public final class Strategy<A>
extends java.lang.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.

    Version:
    %build.number%

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private F<P1<A>,​P1<A>> f  

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private Strategy​(F<P1<A>,​P1<A>> f)  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static <A> Strategy<java.util.concurrent.Callable<A>> callableStrategy​(Strategy<java.util.concurrent.Callable<A>> s)
      Provides a normalising strategy that fully evaluates its Callable argument.
      static <A> Strategy<A> completionStrategy​(java.util.concurrent.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.
      Strategy<A> contramap​(F<P1<A>,​P1<A>> f)
      Maps the given transformation across this strategy's codomain (Invariant Functor pattern).
      static <A> Effect1<java.util.concurrent.Future<A>> discard()
      Returns an Effect that waits for a given Future to obtain a value, discarding the value.
      static <A> Strategy<A> errorStrategy​(Strategy<A> s, Effect1<java.lang.Error> e)
      Provides an error-handling strategy.
      Strategy<A> errorStrategy​(Effect1<java.lang.Error> e)
      Provides an error-handling strategy.
      static <A> Strategy<A> executorStrategy​(java.util.concurrent.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<java.util.concurrent.Future<A>> xs)
      Waits for every Future in a list to obtain a value, and collects those values in a list.
      static <A> F<java.util.concurrent.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​(java.util.concurrent.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

    • Field Detail

      • f

        private final F<P1<A>,​P1<A>> f

    • Constructor Detail

      • Strategy

        private Strategy​(F<P1<A>,​P1<A>> f)

    • 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<java.util.concurrent.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<java.util.concurrent.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​(java.util.concurrent.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> Effect1<java.util.concurrent.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​(java.util.concurrent.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​(java.util.concurrent.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.

      • contramap

        public Strategy<A> contramap​(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​(Effect1<java.lang.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,
                                            Effect1<java.lang.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<java.util.concurrent.Callable<A>> callableStrategy​(Strategy<java.util.concurrent.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.