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

Interface IEolContextParallel

All Superinterfaces:

IEolContext

All Known Subinterfaces:

IEclContextParallel, IEgxContextParallel, IEplContextParallel, IErlContextParallel, IEtlContextParallel, IEvlContextParallel, IEwlContextParallel

All Known Implementing Classes:

EclContextParallel, EgxContextParallel, EolContextParallel, EplContextParallel, ErlContextParallel, EtlContextParallel, EvlContextParallel, EwlContextParallel

public interface IEolContextParallel
extends IEolContext

Thread-safe IEolContext, offering utilities for parallel execution.

Since:

1.6

Author:

Sina Madani

Field Summary

Fields

Modifier and Type	Field	Description
static java.lang.String	NUM_THREADS_CONFIG	The key used for configuring the parallelism in dt plugins.

Method Summary

Modifier and Type	Method	Description
default java.util.concurrent.ExecutorService	beginParallelTask(ModuleElement entryPoint)	Registers the beginning of parallel task on the default ExecutorService.
default java.util.concurrent.ExecutorService	beginParallelTask(ModuleElement entryPoint, boolean shortCircuiting)	Registers the beginning of parallel task on the default ExecutorService.
static <C extends IEolContextParallel> C	configureContext(java.util.Map<java.lang.String,?> properties, java.util.function.Function<java.lang.Integer,? extends C> contextConstructor, C currentContext)	Convenience method for setting the parallelism on a context.
void	endParallelTask()	Must be called once parallel processing has finished.
default void	ensureNotNested(ModuleElement entryPoint)	This method should be called prior to performing any parallel execution.
default <T> java.util.List<T>	executeAll(ModuleElement entryPoint, java.util.Collection<? extends java.util.concurrent.Callable<? extends T>> jobs)	Executes all of the tasks in parallel, blocking until they have completed.
default <T> T	executeAny(ModuleElement entryPoint, java.util.Collection<? extends java.util.concurrent.Callable<? extends T>> jobs)	Submits all jobs and waits until either all jobs have completed, or #completeShortCircuit(ModuleElement, Object) is called.
java.util.concurrent.ExecutorService	getExecutorService()	A re-usable ExecutorService.
int	getParallelism()	Indicates the scalability of this Context when more processing nodes are added.
boolean	isParallel()	This method will return true if #beginParallelTask() has been called and false if endParallelTask() has been called, or if #beginParallelTask() has not been called yet.
default boolean	isParallelisationLegal()	Convenience method for testing whether to perform an operation in parallel using this context without encountering an EolNestedParallelismException.
void	setParallelism(int parallelism)	Attempts to set the parallelism of this context and its associated executor.

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

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

Field Detail

NUM_THREADS_CONFIG

static final java.lang.String NUM_THREADS_CONFIG

The key used for configuring the parallelism in dt plugins.

See Also:

Constant Field Values

Method Detail

getParallelism

int getParallelism()

Indicates the scalability of this Context when more processing nodes are added.

Returns:

the number of threads.

setParallelism

void setParallelism(int parallelism)
             throws java.lang.UnsupportedOperationException,
                    java.lang.IllegalStateException,
                    java.lang.IllegalArgumentException

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.

Parameters:

parallelism - The new value. Must be positive.

Throws:

java.lang.UnsupportedOperationException - If this context (or its ExecutorService) has an immutable parallelism.

java.lang.IllegalStateException - If this method is called at an inconvenient time.

java.lang.IllegalArgumentException - If the new value is out of bounds.

isParallel

boolean isParallel()

This method will return true if #beginParallelTask() has been called and false if endParallelTask() has been called, or if #beginParallelTask() has not been called yet.

Returns:

Whether this Context is currently executing in parallel mode.

getExecutorService

java.util.concurrent.ExecutorService getExecutorService()

A re-usable ExecutorService.

Returns:

a cached ExecutorService.

isParallelisationLegal

default boolean isParallelisationLegal()

Convenience method for testing whether to perform an operation in parallel using this context without encountering an EolNestedParallelismException.

Returns:

true if calling #enterParallelNest(ModuleElement) is permitted.

ensureNotNested

default void ensureNotNested(ModuleElement entryPoint)
                      throws EolNestedParallelismException

This method should be called prior to performing any parallel execution.

Parameters:

entryPoint - The module element to use as the cause of an exception

Throws:

EolNestedParallelismException - If #isParallelisationLegal(Object) returns false

beginParallelTask

default java.util.concurrent.ExecutorService beginParallelTask(ModuleElement entryPoint,
                                                               boolean shortCircuiting)
                                                        throws EolNestedParallelismException

Registers the beginning of parallel task on the default ExecutorService. The endParallelTask() method must be called once finished.

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:

getExecutorService()

Throws:

EolNestedParallelismException - If there was already a parallel task in progress.

beginParallelTask

default java.util.concurrent.ExecutorService beginParallelTask(ModuleElement entryPoint)
                                                        throws EolNestedParallelismException

Registers the beginning of parallel task on the default ExecutorService. The endParallelTask() method must be called once finished.

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.

Returns:

getExecutorService()

Throws:

EolNestedParallelismException - If there was already a parallel task in progress.

endParallelTask

void endParallelTask()
              throws EolRuntimeException

Must be called once parallel processing has finished.

Throws:

EolRuntimeException - if the status completed exceptionally.

java.lang.IllegalStateException - if the current job is still executing.

See Also:

beginParallelTask(ModuleElement)

executeAll

default <T> java.util.List<T> executeAll(ModuleElement entryPoint,
                                         java.util.Collection<? extends java.util.concurrent.Callable<? extends T>> jobs)
                                  throws EolRuntimeException

Executes all of the tasks in parallel, blocking until they have completed. The returned Collection is ordered based on the same ordering of the input Collection.

Type Parameters:

T - The return type for each job.

Parameters:

entryPoint - The identifier for this parallel task.

jobs - The transformations to perform.

Returns:

The result of the jobs in encounter order.

Throws:

EolRuntimeException - If any of the jobs fail (i.e. throw an exception).

executeAny

default <T> T executeAny(ModuleElement entryPoint,
                         java.util.Collection<? extends java.util.concurrent.Callable<? extends T>> jobs)
                  throws EolRuntimeException

Submits all jobs and waits until either all jobs have completed, or #completeShortCircuit(ModuleElement, Object) is called.

Type Parameters:

T - The return type of each job.

Parameters:

entryPoint - The identifier for this parallel task.

jobs - The jobs to execute.

Returns:

The result of this task, as set by #completeShortCircuit(ModuleElement, Object), if any.

Throws:

EolRuntimeException - If any of the jobs fail (i.e. throw an exception).

configureContext

static <C extends IEolContextParallel> C configureContext(java.util.Map<java.lang.String,?> properties,
                                                          java.util.function.Function<java.lang.Integer,? extends C> contextConstructor,
                                                          C currentContext)
                                                   throws java.lang.IllegalArgumentException

Convenience method for setting the parallelism on a context.

Parameters:

properties - The parameter passed to the configure method of the module.

contextConstructor - The function which creates a parallel context from a given number of threads.

currentContext - The existing context to return, if no changes are made.

Returns:

The new context if NUM_THREADS_CONFIG is present in the properties, otherwise currentContext.

Throws:

java.lang.IllegalArgumentException - If the value of NUM_THREADS_CONFIG property is invalid.