*GParallelizer* allows Groovy code to easily handle tasks concurrently, leveraging either the JSR-166y _Parallel Arrays_ or Java's executor services.

The framework offers developers straightforward Groovy-based Domain Specific Languages (DSLs) to declare, which parts of the code should be performed in parallel. Objects are enhanced with asynchronous methods like _eachAsync()_, _collectAsync()_ and others, to perform these collection-based operations in parallel. Closures can be turned into asynchronous variants, which when invoked schedule the original closure for processing in an executor service. The library also provides helper methods for running a bunch of closures concurrently.

The library has two logical parts, which differ in the implementation technology.
# *Parallelizer* uses JSR-166y Parallel Arrays and is limited to collection processing.
# *Asynchronizer* uses the Java 1.5 built-in support for executor services and supports not only collections and all other types, which can be iterated in Groovy. but also consurrent closures' execution.

==Usage of Parallelizer==

The _Parallelizer_ class enables a ParallelArray-based (from JSR-166y) DSL on collections. The jsr166y.jar (downloadable from e.g. http://gee.cs.oswego.edu/dl/concurrency-interest/index.html) must be on the classpath.

Examples of use:
{{{
//summarize numbers concurrently
Parallelizer.withParallelizer(5) {
  final AtomicInteger result = new AtomicInteger(0)
  [1, 2, 3, 4, 5].eachAsync {result.addAndGet(it)}
  assertEquals 15, result
}

//multiply numbers asynchronously
Parallelizer.withParallelizer(5) {
  final List result = [1, 2, 3, 4, 5].collectAsync {it * 2}
  assert ([2, 4, 6, 8, 10].equals(result))
}
}}}
The passed-in closure takes an instance of a _ForkJoinPool_ as a parameter, which can be then used freely inside the closure.
{{{
//check whether all elements within a collection meet certain criteria
Parallelizer.withParallelizer(5) {ForkJoinPool pool ->
  assert [1, 2, 3, 4, 5].allAsync {it > 0}
  assert ![1, 2, 3, 4, 5].allAsync {it > 1}
}
}}}
The _Parallelizer.withParallelizer()_ method takes optional parameters for number of threads in the created pool and unhandled exception handler. The _Parallelizer.withExistingParallelizer()_ takes an already existing thread pool to reuse.
The DSL is valid only within the associated block of code and only for the thread that has called the _withParallelizer()_ or _withExistingParallelizer()_ method. The _withParallelizer()_ method returns only after all the worker threads have finished their tasks and the pool has been destroyed, returning back the return value of the associated block of code. The _withExistingParallelizer()_ method doesn't wait for the pool threads to finish.

Alternatively, the _Parallelizer_ class can be statically imported _import static org.gparallelizer.Parallelizer.`*`_, which will allow omitting the _Parallelizer_ class name.
{{{
withParallelizer {
  assert [1, 2, 3, 4, 5].allAsync {it > 0}
  assert ![1, 2, 3, 4, 5].allAsync {it > 1}
}
}}}
The following methods on collections are currently supported:
* eachAsync()
* collectAsync()
* findAllAsync()
* findAsync()
* allAsync()
* anyAsync()

==Usage of Asynchronizer==

The _Asynchronizer_ class enables a Java's Executor Service-based DSL on collections and closures. At least Java 1.5 must be used.

Examples of use:
{{{
//multiply numbers asynchronously
Asynchronizer.withAsynchronizer(5) {
  Collection<Future> result = [1, 2, 3, 4, 5].collectAsync{it * 10}
  assertEquals(new HashSet([10, 20, 30, 40, 50]), new HashSet((Collection)result*.get()))
}

//multiply numbers asynchronously using an asynchronous closure
Asynchronizer.withAsynchronizer(5) {
  def closure={it * 10}
  def asyncClosure=closure.async()
  Collection<Future> result = [1, 2, 3, 4, 5].collect(asyncClosure)
  assertEquals(new HashSet([10, 20, 30, 40, 50]), new HashSet((Collection)result*.get()))
}
}}}

The passed-in closure takes an instance of a _ExecutorService_ as a parameter, which can be then used freely inside the closure.
{{{
//find an element meeting specified criteria
Asynchronizer.withAsynchronizer(5) {ExecutorService service ->
  service.submit({performLongCalculation()} as Runnable)
}
}}}
The _Asynchronizer.withAsynchronizer()_ method takes optional parameters for number of threads in the created pool and a thread factory. The _Asynchronizer.withExistingAsynchronizer()_ takes an already existing executor service to reuse. The DSL is valid only within the associated block of code and only for the thread that has called the _withAsynchronizer()_ or _withExistingAsynchronizer()_ method. The _withAsynchronizer()_ method returns only after all the worker threads have finished their tasks and the executor service has been destroyed, returning back the return value of the associated block of code. The _withExistingAsynchronizer()_ method doesn't wait for the executor service threads to finish.

Alternatively, the _Asynchronizer_ class can be statically imported _import static org.gparallelizer.Asynchronizer.`*`_, which will allow omitting the _Asynchronizer_ class name.
{{{
withAsynchronizer {
  def result = [1, 2, 3, 4, 5].findAsync{Number number -> number > 2}
  assert result in [3, 4, 5]
}
}}}

The following methods on all objects, which support iterations in Groovy, are currently supported:
* eachAsync()
* collectAsync()
* findAllAsync()
* findAsync()
* allAsync()
* anyAsync()

The following methods are added to closures inside the _Asynchronizer.withAsynchronizer()_ blocks:
* async() - Creates an asynchronous variant of the supplied closure, which when invoked returns a future for the potential return value
* callAsync() - Calls a closure in a separate thread supplying the given arguments, returning a future for the potential return value,

Example:
{{{
Asynchronizer.withAsynchronizer() {
 Closure longLastingCalculation = {calculate()}
 Closure fastCalculation = longLastingCalculation.async()
 Future result=fastCalculation()
 //do stuff while calculation performs
 println result.get()
}
}}}
The ExecutorService class is enhanced with the << (leftShift) operator to submit tasks to it returning a _Future_ for the result. It wraps the _submit()_ method call on the service.

Example:
{{{
Asynchronizer.withAsynchronizer {ExecutorService executorService ->
 executorService << {println 'Inside parallel task'}
}
}}}
The AsyncInvokerUtil class offers methods _doInParallel()_, _executeInParallel()_ and _startInParallel()_ to easily run multiple closures in parallel.

Example:
{{{
Asynchronizer.withAsynchronizer {
 assertEquals([10, 20], AsyncInvokerUtil.doInParallel({calculateA()}, {calculateB()}))
}
}}}
