javolution37.javolution.realtime

Class ConcurrentContext

java.lang.Object

javolution37.javolution.realtime.Context

javolution37.javolution.realtime.ConcurrentContext

public class ConcurrentContext
extends Context

This class represents a concurrent context; it is used to accelerate execution of concurrent algorithms on multi-processors systems.

When a thread enters a concurrent context, it may execute multiple concurrent logics by calling any of the ConcurrentContext.execute(logic, arg0, arg1, ...) static methods. The logic is then executed at the same priority as the current thread and in the same memory area by a ConcurrentThread or by the current thread itself.

Only after all concurrent executions are completed, is the current thread allowed to exit the scope of the concurrent context (internal synchronization).

Concurrent logics always execute within a PoolContext and do not generate garbage. Realtime objects made available outside of the logic scope have therefore to be either exported or preserved.

Concurrent contexts are easy to use, and provide automatic load-balancing between processors with almost no overhead. Here is an example of concurrent/recursive/clean (no garbage generated) implementation of the Karatsuba multiplication for large integers:

     public LargeInteger multiply(LargeInteger that) {
         if (that._size <= 1) {
             return multiply(that.longValue()); // Direct multiplication.
             
         } else { // Karatsuba multiplication in O(n^log2(3))
             int bitLength = this.bitLength();
             int n = (bitLength >> 1) + (bitLength & 1);
             LargeInteger b = this.shiftRight(n);
             LargeInteger a = this.minus(b.shiftLeft(n));
             LargeInteger d = that.shiftRight(n);
             LargeInteger c = that.minus(d.shiftLeft(n));
             StackReference<LargeInteger> ac = StackReference.newInstance();
             StackReference<LargeInteger> bd = StackReference.newInstance();
             StackReference<LargeInteger> abcd = StackReference.newInstance();
             ConcurrentContext.enter();
             try { // this = a + 2^n b,   that = c + 2^n d
                 ConcurrentContext.execute(MULTIPLY, a, c, ac);
                 ConcurrentContext.execute(MULTIPLY, b, d, bd);
                 ConcurrentContext.execute(MULTIPLY, a.plus(b), c.plus(d), abcd);
             } finally {
                 ConcurrentContext.exit(); // Waits for all concurrent threads to complete.
             }
             // a*c + ((a+b)*(c+d)-a*c-b*d) 2^n + b*d 2^2n 
             return ac.get().plus(abcd.get().minus(ac.get()).minus(bd.get()).shiftLeft(n)).plus(bd.get().shiftLeft(2 * n));
         }
     }
     private static final Logic MULTIPLY = new Logic() {
         public void run(Object[] args) {
             LargeInteger left = (LargeInteger) args[0];
             LargeInteger right = (LargeInteger) args[1];
             StackReference result = (StackReference) args[2];
             result.set(left.times(right).export());  // Recursive.
         }
    };

Finally, it should be noted that concurrent contexts ensure the same behavior whether or not the execution is performed by the current thread or concurrent threads. In particular, the current context is inherited by concurrent threads and any exception raised during the concurrent logic executions is automatically propagated to the current thread.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ConcurrentContext.Logic This abstract class represents some parameterized code which may be executed concurrently.

Constructor Summary

Constructors

Constructor and Description
ConcurrentContext() Default constructor.
ConcurrentContext(ConcurrentThread[] threads) Creates a concurrent context using the specified concurrent threads.

Method Summary

Modifier and Type	Method and Description
void	clear() Terminates all the concurrent threads associated to this concurrent context.
static ConcurrentContext	current() Returns the current concurrent context or null if the current thread has not been spawned from a concurrent context.
static void	enter() Enters a ConcurrentContext.
static void	execute(ConcurrentContext.Logic logic) Executes the specified logic by a ConcurrentThread when possible.
static void	execute(ConcurrentContext.Logic logic, java.lang.Object arg0) Executes the specified logic with the specified argument.
static void	execute(ConcurrentContext.Logic logic, java.lang.Object arg0, java.lang.Object arg1) Executes the specified logic with the specified two arguments.
static void	execute(ConcurrentContext.Logic logic, java.lang.Object arg0, java.lang.Object arg1, java.lang.Object arg2) Executes the specified logic with the specified three arguments.
static void	execute(ConcurrentContext.Logic logic, java.lang.Object arg0, java.lang.Object arg1, java.lang.Object arg2, java.lang.Object arg3) Executes the specified logic with the specified four arguments.
static void	execute(ConcurrentContext.Logic logic, java.lang.Object arg0, java.lang.Object arg1, java.lang.Object arg2, java.lang.Object arg3, java.lang.Object arg4) Executes the specified logic with the specified five arguments.
static void	execute(ConcurrentContext.Logic logic, java.lang.Object arg0, java.lang.Object arg1, java.lang.Object arg2, java.lang.Object arg3, java.lang.Object arg4, java.lang.Object arg5) Executes the specified logic with the specified six arguments.
static void	exit() Exits the current ConcurrentContext.
ConcurrentThread[]	getConcurrentThreads() Returns the concurrent threads available to this concurrent context (inherited from outer concurrent contexts unless specified at construction).
static boolean	isEnabled() Indicates if concurrency is locally enabled (default true).
static void	setEnabled(boolean enabled) Enables/disables local concurrency.

Methods inherited from class javolution37.javolution.realtime.Context

enter, exit, getOuter, getOwner

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ConcurrentContext

public ConcurrentContext()

Default constructor. This context has no concurrent thread associated with. The concurrent threads are inherited from outer contexts. If this context is the top-most concurrent context, then new concurrent threads are created and started the first time that this context is entered. The number of threads created is configurable (see Javolution Configuration for details).

ConcurrentContext

public ConcurrentContext(ConcurrentThread[] threads)

Creates a concurrent context using the specified concurrent threads.

Parameters:

threads - the concurrent threads available for dispatching.

Method Detail

getConcurrentThreads

public final ConcurrentThread[] getConcurrentThreads()

Returns the concurrent threads available to this concurrent context (inherited from outer concurrent contexts unless specified at construction).

Returns:

the concurrent threads available to this context or null if none (e.g. context created using default constructor and without outer concurrent context).

clear

public void clear()

Terminates all the concurrent threads associated to this concurrent context.

Overrides:

clear in class Context

current

public static ConcurrentContext current()

Returns the current concurrent context or null if the current thread has not been spawned from a concurrent context.

Returns:

the current concurrent context.

enter

public static void enter()

Enters a ConcurrentContext.

exit

public static void exit()

Exits the current ConcurrentContext. This method blocks until all concurrent executions within the current context are completed. Errors and exceptions raised in concurrent threads are propagated here.

Throws:

java.lang.IllegalStateException - if the current context is not an instance of ConcurrentContext.

ConcurrentException - propagates any error or exception raised during the execution of a concurrent logic.

setEnabled

public static void setEnabled(boolean enabled)

Enables/disables local concurrency.

Parameters:

enabled - true if concurrency is locally enabled; false otherwise.

isEnabled

public static boolean isEnabled()

Indicates if concurrency is locally enabled (default true).

Returns:

true if concurrency is locally enabled; false otherwise.

execute

public static void execute(ConcurrentContext.Logic logic)

Executes the specified logic by a ConcurrentThread when possible. The specified logic is always executed within a PoolContext. It inherits the context stack, priority and memory area of the dispatching thread. Any exception or error during execution is propagated to the current thread upon exit() of the concurrent context.

Parameters:

logic - the logic to execute concurrently when possible.

Throws:

java.lang.ClassCastException - if the current context is not a ConcurrentContext.

execute

public static void execute(ConcurrentContext.Logic logic,
                           java.lang.Object arg0)

Executes the specified logic with the specified argument.

Parameters:

logic - the logic to execute concurrently when possible.

arg0 - the logic argument.

Throws:

java.lang.ClassCastException - if the current context is not a ConcurrentContext.

execute

public static void execute(ConcurrentContext.Logic logic,
                           java.lang.Object arg0,
                           java.lang.Object arg1)

Executes the specified logic with the specified two arguments.

Parameters:

logic - the logic to execute concurrently when possible.

arg0 - the first argument.

arg1 - the second argument.

Throws:

java.lang.ClassCastException - if the current context is not a ConcurrentContext.

See Also:

execute(ConcurrentContext.Logic)

execute

public static void execute(ConcurrentContext.Logic logic,
                           java.lang.Object arg0,
                           java.lang.Object arg1,
                           java.lang.Object arg2)

Executes the specified logic with the specified three arguments.

Parameters:

logic - the logic to execute concurrently when possible.

arg0 - the first argument.

arg1 - the second argument.

arg2 - the third argument.

Throws:

java.lang.ClassCastException - if the current context is not a ConcurrentContext.

See Also:

execute(ConcurrentContext.Logic)

execute

public static void execute(ConcurrentContext.Logic logic,
                           java.lang.Object arg0,
                           java.lang.Object arg1,
                           java.lang.Object arg2,
                           java.lang.Object arg3)

Executes the specified logic with the specified four arguments.

Parameters:

logic - the logic to execute concurrently when possible.

arg0 - the first argument.

arg1 - the second argument.

arg2 - the third argument.

arg3 - the fourth argument.

Throws:

java.lang.ClassCastException - if the current context is not a ConcurrentContext.

See Also:

execute(ConcurrentContext.Logic)

execute

public static void execute(ConcurrentContext.Logic logic,
                           java.lang.Object arg0,
                           java.lang.Object arg1,
                           java.lang.Object arg2,
                           java.lang.Object arg3,
                           java.lang.Object arg4)

Executes the specified logic with the specified five arguments.

Parameters:

logic - the logic to execute concurrently when possible.

arg0 - the first argument.

arg1 - the second argument.

arg2 - the third argument.

arg3 - the fourth argument.

arg4 - the fifth argument.

Throws:

java.lang.ClassCastException - if the current context is not a ConcurrentContext.

See Also:

execute(ConcurrentContext.Logic)

execute

public static void execute(ConcurrentContext.Logic logic,
                           java.lang.Object arg0,
                           java.lang.Object arg1,
                           java.lang.Object arg2,
                           java.lang.Object arg3,
                           java.lang.Object arg4,
                           java.lang.Object arg5)

Executes the specified logic with the specified six arguments.

Parameters:

logic - the logic to execute concurrently when possible.

arg0 - the first argument.

arg1 - the second argument.

arg2 - the third argument.

arg3 - the fourth argument.

arg4 - the fifth argument.

arg5 - the sixth argument.

Throws:

java.lang.ClassCastException - if the current context is not a ConcurrentContext.

See Also:

execute(ConcurrentContext.Logic)