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

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 Summary

Fields

Modifier and Type	Field	Description
protected EolThreadPoolExecutor	executorService

Fields inherited from class org.eclipse.epsilon.eol.execute.context.EolContext

assertionsEnabled, asyncStatementsQueue, classpathNativeTypeDelegate, errorStream, executorFactory, extendedProperties, frameStack, introspectionManager, methodContributorRegistry, modelRepository, module, nativeTypeDelegates, operationFactory, outputStream, prettyPrinterManager, profilingEnabled, userInput, warningStream

Fields inherited from interface org.eclipse.epsilon.eol.execute.context.concurrent.IEolContextParallel

NUM_THREADS_CONFIG

Constructor Summary

Constructors

Modifier	Constructor	Description
	EolContextParallel()
	EolContextParallel(int parallelism)
protected	EolContextParallel(IEolContext other)	Copy constructor.

Method Summary

Modifier and Type	Method	Description
ExecutorService	beginParallelTask(ModuleElement entryPoint, boolean shortCircuiting)	Registers the beginning of parallel task on the default ExecutorService.
protected void	clearExecutor()
protected void	clearThreadLocals()
static IEolContextParallel	convertToParallel(IEolContext context)	Utility method for converting a sequential context to a parallel one, if it is not already parallel.
protected IEolContext	createShadowThreadLocalContext()
protected ExecutorFactory	createThreadLocalExecutorFactory()
protected FrameStack	createThreadLocalFrameStack()
protected OperationContributorRegistry	createThreadLocalOperationContributorRegistry()
void	dispose()
void	endParallelTask()	Must be called once parallel processing has finished.
Object	executeJob(Object job)	Evaluates the job using this context's parallel execution facilities.
ExecutorFactory	getExecutorFactory()
EolThreadPoolExecutor	getExecutorService()	A re-usable ExecutorService.
FrameStack	getFrameStack()
int	getParallelism()	Indicates the scalability of this Context when more processing nodes are added.
IEolContext	getShadow()	Can be used to obtain an optimal execution context while executing in parallel.
protected <T extends BaseDelegate<T>> DelegatePersistentThreadLocal<T>	initDelegateThreadLocal(Supplier<? extends T> constructor)
protected void	initThreadLocals()
boolean	isParallel()	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.
protected EolThreadPoolExecutor	newExecutorService()
protected void	nullifyThreadLocals()
protected <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().
protected <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().
protected <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().
protected void	removeAll(ThreadLocal<?>... threadLocals)
void	setExecutorFactory(ExecutorFactory executorFactory)
void	setFrameStack(FrameStack frameStack)
void	setParallelism(int threads)	Attempts to set the parallelism of this context and its associated executor.
String	toString()
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.

Methods inherited from class org.eclipse.epsilon.eol.execute.context.EolContext

getAsyncStatementsQueue, getErrorStream, getExtendedProperties, getIntrospectionManager, getModelRepository, getModule, getNativeTypeDelegates, getOperationContributorRegistry, getOperationFactory, getOutputStream, getPrettyPrinterManager, getUserInput, getWarningStream, isAssertionsEnabled, isProfilingEnabled, setAssertionsEnabled, setErrorStream, setExtendedProperties, setIntrospectionManager, setModelRepository, setModule, setNativeTypeDelegates, setOperationFactory, setOutputStream, setPrettyPrinterManager, setProfilingEnabled, setUserInput, setWarningStream

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.eclipse.epsilon.eol.execute.context.IEolContext

getAsyncStatementsQueue, getErrorStream, getExtendedProperties, getIntrospectionManager, getModelRepository, getModule, getNativeTypeDelegates, getOperationContributorRegistry, getOperationFactory, getOutputStream, getPrettyPrinterManager, getUserInput, getWarningStream, isAssertionsEnabled, isProfilingEnabled, setAssertionsEnabled, setErrorStream, setExtendedProperties, setIntrospectionManager, setModelRepository, setModule, setNativeTypeDelegates, setOperationFactory, setOutputStream, setPrettyPrinterManager, setProfilingEnabled, setUserInput, setWarningStream

Methods inherited from interface org.eclipse.epsilon.eol.execute.context.concurrent.IEolContextParallel

beginParallelTask, ensureNotNested, executeAll, executeAny, isParallelisationLegal

Field Detail

executorService

protected EolThreadPoolExecutor executorService

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()

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:

IEolContextParallel.beginParallelTask(ModuleElement)

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