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

Class EolContextParallel

java.lang.Object
org.eclipse.epsilon.eol.execute.context.EolContext
org.eclipse.epsilon.eol.execute.context.concurrent.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

  • Field Details

  • Constructor Details

    • 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 Details

    • initThreadLocals

      protected void initThreadLocals()

    • initDelegateThreadLocal

      protected <T extends BaseDelegate<T>> DelegatePersistentThreadLocal<T> initDelegateThreadLocal(Supplier<? extends T> constructor)

    • useThreadLocalValue

      protected boolean useThreadLocalValue()
      Determines whether calling parallelGet(ThreadLocal, Object) or parallelSet(Object, ThreadLocal, Consumer) should use the ThreadLocal value or if the alternative value should be returned.
      Returns:
      true if the ThreadLocal should be used, false otherwise.

    • parallelGet

      protected final <R> R parallelGet(ThreadLocal<? extends R> threadLocal, 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(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, ThreadLocal<? super T> threadLocal, 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(ThreadLocal<?>... threadLocals)

    • clearThreadLocals

      protected void clearThreadLocals()

    • nullifyThreadLocals

      protected void nullifyThreadLocals()

    • clearExecutor

      protected void clearExecutor()

    • newExecutorService

      protected EolThreadPoolExecutor newExecutorService()

    • beginParallelTask

      public ExecutorService beginParallelTask(ModuleElement entryPoint, boolean shortCircuiting) throws EolNestedParallelismException
      Description copied from interface: IEolContextParallel
      Registers the beginning of parallel task on the default ExecutorService. The IEolContextParallel.endParallelTask() method must be called once finished.
      Specified by:
      beginParallelTask in interface IEolContextParallel
      Parameters:
      entryPoint - The AST to associate with this task. May be null, in which case a default value (e.g. IEolContext.getModule()) should be used.
      shortCircuiting - Whether the task may be terminated abruptly.
      Returns:
      IEolContextParallel.getExecutorService()
      Throws:
      EolNestedParallelismException - If there was already a parallel task in progress.

    • endParallelTask

      public void endParallelTask() throws EolRuntimeException
      Description copied from interface: IEolContextParallel
      Must be called once parallel processing has finished.
      Specified by:
      endParallelTask in interface IEolContextParallel
      Throws:
      EolRuntimeException - if the status completed exceptionally.
      See Also:

    • setParallelism

      public void setParallelism(int threads) throws IllegalStateException, 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:
      IllegalStateException - If this method is called at an inconvenient time.
      IllegalArgumentException - If the new value is out of bounds.

    • isParallel

      public boolean isParallel()
      Description copied from interface: IEolContextParallel
      This method will return true if #beginParallelTask() has been called and false if IEolContextParallel.endParallelTask() has been called, or if #beginParallelTask() has not been called yet.
      Specified by:
      isParallel in interface IEolContextParallel
      Returns:
      Whether this Context is currently executing in parallel mode.

    • 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.

    • getExecutorService

      public final EolThreadPoolExecutor getExecutorService()
      Description copied from interface: IEolContextParallel
      A re-usable ExecutorService.
      Specified by:
      getExecutorService in interface IEolContextParallel
      Returns:
      a cached ExecutorService.

    • dispose

      public void dispose()
      Specified by:
      dispose in interface IEolContext
      Overrides:
      dispose in class EolContext

    • getFrameStack

      public FrameStack getFrameStack()
      Specified by:
      getFrameStack in interface IEolContext
      Overrides:
      getFrameStack in class EolContext

    • getExecutorFactory

      public ExecutorFactory getExecutorFactory()
      Specified by:
      getExecutorFactory in interface IEolContext
      Overrides:
      getExecutorFactory in class EolContext

    • setFrameStack

      public void setFrameStack(FrameStack frameStack)
      Specified by:
      setFrameStack in interface IEolContext
      Overrides:
      setFrameStack in class EolContext

    • setExecutorFactory

      public void setExecutorFactory(ExecutorFactory executorFactory)
      Specified by:
      setExecutorFactory in interface IEolContext
      Overrides:
      setExecutorFactory in class EolContext

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • createThreadLocalExecutorFactory

      protected ExecutorFactory createThreadLocalExecutorFactory()

    • createThreadLocalFrameStack

      protected FrameStack createThreadLocalFrameStack()

    • createThreadLocalOperationContributorRegistry

      protected OperationContributorRegistry createThreadLocalOperationContributorRegistry()

    • 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 Object executeJob(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:
      IllegalArgumentException - If the job type is not recognised.
      EolRuntimeException - If an exception is thrown whilst evaluating the job(s).