Parallel

Parallel

Description

Executes nested tasks in parallel with no guarantees of thread safety. Every task will run in its own thread, with the likelihood of concurrency problems scaling with the number of CPUs on the host system.

Warning: While the Apache Ant core is believed to be thread safe, no such guarantees are made about tasks, which are not tested for thread safety during Ant's test process. Third party tasks may or may not be thread safe, and some of Ant's core tasks, such as <javac> are definitely not re-entrant. This is because they use libraries that were never designed to be used in a multithreaded environment.

The primary use case for <parallel> is to run external programs such as an application server, and the JUnit or TestNG test suites at the same time. Anyone trying to run large Ant task sequences in parallel, such as javadoc and javac at the same time, is implicitly taking on the task of identifying and fixing all concurrency bugs the tasks that they run.

Accordingly, while this task has uses, it should be considered an advanced task which should be used in certain batch-processing or testing situations, rather than an easy trick to speed up build times on a multiway CPU.

Parameters

Parallel tasks have a number of uses in an Ant build file including:

• Taking advantage of available processing resources to execute external programs simultaneously.
• Testing servers, where the server can be run in one thread and the testharness is run in another thread.

Any valid Ant task may be embedded within aparallel task, including other parallel tasks, though there is no guarantee thatthe tasks will be thread safe in such an environment.

While the tasks within the parallel task are being run, the mainthread will be blocked waiting for all the child threads to complete. Ifexecution is terminated by a timeout or a nested task failure when thefailonanyflag is set, the parallel task will complete without waiting for other nestedtasks to complete in other threads.

If any of the tasks within the <parallel> task fails and failonany isnot set, the remaining tasks in other threads will continue to run untilall threads have completed. In this situation, the parallel task will also fail.

The parallel task may be combined with the sequential task to define sequences of tasks to be executed on each threadwithin the parallel block

The threadCount attribute can be used to place a maximum number of availablethreads for the execution. When not present all child tasks will be executed atonce. When present then the maximum number of concurrently executing tasks willnot exceed the number of threads specified. Furthermore, each task will bestarted in the order they are given. But no guarantee is made as to the speedof execution or the order of completion of the tasks, only that each will bestarted before the next.

If you are using Java 1.4 or later you can also use the threadsPerProcessorand the number of available threads will be the stated multiple of the number ofprocessors (there is no affinity to a particular processor however). This willoverride the value in threadCount. If threadsPerProcessoris specified on any older JVM, then the value in threadCount will be used as is.

When using threadCount and threadsPerProcessor care should be taken to ensure that the build does not deadlock. This can be caused by tasks such as waitfor taking up all available threads before the tasks that would unlock the waitforwould occur. This is not a replacement for Java Language level threadsemantics and is best used for "embarassingly parallel" tasks.

Parameters specified as nested elements

daemons

The parallel task supports a <daemons> nested element. This is a list of taskswhich are to be run in parallel daemon threads. The parallel task will not wait forthese tasks to complete. Being daemon threads, however, they will not prevent Ant fromcompleting, whereupon the threads are terminated. Failures in daemon threads whichoccur before the parallel task itself finishes will be reported and can causeparallel to throw an exception. Failures which occur after parallel has completed are notreported.

Daemon tasks can be used, for example, to start test servers which might not be easilyterminated from Ant. By using <daemons> such servers do not halt the build.

Examples

<parallel>  <wlrun ... >  <sequential> <sleep seconds="30"/> <junit fork="true" forkmode="once" ... > <wlstop/>  </sequential></parallel>

This example represents a typical pattern for testing a server application.In one thread the server is started (the <wlrun> task). The other thread consistsof a three tasks which are performed in sequence. The <sleep> task is used togive the server time to come up. Another task which is capable of validatingthat the server is available could be used in place of the <sleep> task. The<junit> test harness then runs, again in its own JVM. Once the tests are complete, the server is stopped(using <wlstop> in this example), allowing both threads to complete. The<parallel> task will also complete at this time and the build will thencontinue.

<parallel>  <javac fork="true"...> <!-- compiler servlet code -->  <wljspc ...> <!-- precompile JSPs --></parallel>

This example shows two independent tasks being run to achieve betterresource utilization during the build. In this instance, some servlets are beingcompiled in one thead and a set of JSPs is being precompiled in another. Developersneed to be careful that the two tasks are independent, both interms of their dependencies and in terms of their potential interactions inAnt's external environment. Here we set fork="true" for the <javac> task, so that it runs in a new process; if the <wljspc> task used the javac compiler in-VM(it may), concurrency problems may arise.