Package org.eclipse.epsilon.eol.execute.context.concurrent

Class EolContextParallel

  • All Implemented Interfaces:
    IEolContextParallel, IEolContext
    Direct Known Subclasses:
    ErlContextParallel, EwlContextParallel
    public class EolContextParallel
extends EolContext
implements IEolContextParallel
    Skeletal implementation of a parallel IEolContext. This class takes care of the common structures which are affected by multi-threading using ThreadLocals. For use cases where these thread-local values are required, a PersistentThreadLocal is used, so that the context will be consistent with a sequential implementation once #endParallel() is invoked.

    For optimal performance, it is recommend that parallel tasks obtain a sequential "snapshot" of this context to avoid frequent retrieval of ThreadLocal values using the getShadow() method.
    Since:
    1.6
    Author:
    Sina Madani

    • Constructor Detail

      • EolContextParallel

        public EolContextParallel()

      • EolContextParallel

        public EolContextParallel​(int parallelism)
        Parameters:
        parallelism - The number of threads to use.

      • EolContextParallel

        protected EolContextParallel​(IEolContext other)
        Copy constructor.
        Parameters:
        other - The parent context to copy from. Must not be null.

    • Method Detail

      • initThreadLocals

        protected void initThreadLocals()

      • parallelGet

        protected final <R> R parallelGet​(java.lang.ThreadLocal<? extends R> threadLocal,
                                  java.util.function.Supplier<? extends R> originalValueGetter)
        Utility method used to appropriately return either a thread-local or the original value, depending on whether this context isParallel().
        Type Parameters:
        R - The value type
        Parameters:
        threadLocal - The ThreadLocal value (returned if parallel).
        originalValueGetter - The non-thread-local value (returned if not parallel).
        Returns:
        The appropriate value for the current thread.

      • parallelGet

        protected final <R> R parallelGet​(java.lang.ThreadLocal<? extends R> threadLocal,
                                  R originalValue)
        Utility method used to appropriately return either a thread-local or the original value, depending on whether this context isParallel().
        Type Parameters:
        R - The value type
        Parameters:
        threadLocal - The thread-local wrapper for the value
        originalValue - The main, persistent variable
        Returns:
        The appropriate value for the current thread.

      • parallelSet

        protected final <T> void parallelSet​(T value,
                                     java.lang.ThreadLocal<? super T> threadLocal,
                                     java.util.function.Consumer<? super T> originalValueSetter)
        Utility method used to appropriately set either a thread-local or the original value, depending on whether this context isParallel().
        Parameters:
        value - The value to set.
        threadLocal - The ThreadLocal value (will be set if parallel).
        originalValueSetter - The non-thread-local value (will be set if not parallel).

      • removeAll

        protected void removeAll​(java.lang.ThreadLocal<?>... threadLocals)

      • clearThreadLocals

        protected void clearThreadLocals()

      • nullifyThreadLocals

        protected void nullifyThreadLocals()

      • clearExecutor

        protected void clearExecutor()

      • setParallelism

        public void setParallelism​(int threads)
                    throws java.lang.IllegalStateException,
                           java.lang.IllegalArgumentException
        Description copied from interface: IEolContextParallel
        Attempts to set the parallelism of this context and its associated executor. Note that this may not take effect immediately and is intended to be called during parallel execution. Implementations may ignore this operation or throw an UnsupportedOperationException. It is recommended that this method is only called during initialisation, and is present for convenience only.
        Specified by:
        setParallelism in interface IEolContextParallel
        Parameters:
        threads - The new value. Must be positive.
        Throws:
        java.lang.IllegalStateException - If this method is called at an inconvenient time.
        java.lang.IllegalArgumentException - If the new value is out of bounds.

      • getParallelism

        public final int getParallelism()
        Description copied from interface: IEolContextParallel
        Indicates the scalability of this Context when more processing nodes are added.
        Specified by:
        getParallelism in interface IEolContextParallel
        Returns:
        the number of threads.

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • createThreadLocalExecutorFactory

        protected ExecutorFactory createThreadLocalExecutorFactory()

      • createThreadLocalFrameStack

        protected FrameStack createThreadLocalFrameStack()

      • createShadowThreadLocalContext

        protected IEolContext createShadowThreadLocalContext()

      • getShadow

        public IEolContext getShadow()
        Can be used to obtain an optimal execution context while executing in parallel. If execution is currently not parallel, then this context itself is returned.
        Returns:
        A ThreadLocal copy of this context if in parallel, or this context otherwise.

      • convertToParallel

        public static IEolContextParallel convertToParallel​(IEolContext context)
                                             throws EolNestedParallelismException
        Utility method for converting a sequential context to a parallel one, if it is not already parallel.
        Parameters:
        context - The current execution context to check or convert.
        Returns:
        The context if it is already parallel, or a new EolContextParallel with state copied over from the context parameter.
        Throws:
        EolNestedParallelismException - If the context is already derived from a parallel context.

      • executeJob

        public java.lang.Object executeJob​(java.lang.Object job)
                            throws EolRuntimeException
        Evaluates the job using this context's parallel execution facilities. Subclasses may override this to support additional job types, calling the super method as the last resort for unknown cases. Supported types include multi-valued types (e.g. arrays, Iterable / Iterator, Stream etc.) as well as common concurrency units such as Runnable, Callable and Future.
        Parameters:
        job - The job (or jobs) to evaluate.
        Returns:
        The result of evaluating the job, if any.
        Throws:
        java.lang.IllegalArgumentException - If the job type is not recognised.
        EolRuntimeException - If an exception is thrown whilst evaluating the job(s).