2001-08-09 10:48:12 +00:00
|
|
|
<html>
|
|
|
|
|
|
|
|
|
|
<head>
|
|
|
|
|
<meta http-equiv="Content-Language" content="en-us">
|
2002-02-03 22:00:42 +00:00
|
|
|
<title>Parallel Task</title>
|
2001-08-09 10:48:12 +00:00
|
|
|
</head>
|
|
|
|
|
|
|
|
|
|
<body>
|
|
|
|
|
|
|
|
|
|
<h2>Parallel</h2>
|
|
|
|
|
<h3>Description</h3>
|
|
|
|
|
<p>Parallel is a container task - it can contain other Ant tasks. Each nested
|
|
|
|
|
task within the parallel task will be executed in its own thread. </p>
|
2003-02-19 05:11:34 +00:00
|
|
|
<h3>Parameters</h3>
|
|
|
|
|
<table border="1" cellpadding="2" cellspacing="0">
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top"><b>Attribute</b></td>
|
|
|
|
|
<td valign="top"><b>Description</b></td>
|
|
|
|
|
<td align="center" valign="top"><b>Required</b></td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">threadCount</td>
|
|
|
|
|
<td valign="top">Maximum numbers of thread to use.</td>
|
|
|
|
|
<td align="center" valign="top">No</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">threadsPerProcessor</td>
|
|
|
|
|
<td valign="top">Maximum number of threads to use per available processor
|
|
|
|
|
(Requires JDK 1.4)</td>
|
|
|
|
|
<td align="center" valign="top">No, defers to threadCount</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">pollInterval</td>
|
2003-07-24 14:24:07 +00:00
|
|
|
<td valign="top">Currently has no effect</td>
|
2003-02-19 05:11:34 +00:00
|
|
|
<td align="center" valign="top">No, default is 1000</td>
|
|
|
|
|
</tr>
|
2003-07-24 14:24:07 +00:00
|
|
|
<tr>
|
|
|
|
|
<td valign="top">timeout</td>
|
|
|
|
|
<td valign="top">Number of milliseconds before execution is terminated</td>
|
|
|
|
|
<td align="center" valign="top">No</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td valign="top">failonany</td>
|
|
|
|
|
<td valign="top">If any of the nested tasks fails, execution of the task completes
|
|
|
|
|
at that point without waiting for any other tasks to complete.</td>
|
|
|
|
|
<td align="center" valign="top">No</td>
|
|
|
|
|
</tr>
|
2003-02-19 05:11:34 +00:00
|
|
|
</table>
|
2001-08-09 10:48:12 +00:00
|
|
|
|
2001-09-08 01:05:18 +00:00
|
|
|
<p>Parallel tasks have a number of uses in an Ant build file including:</p>
|
2001-08-09 10:48:12 +00:00
|
|
|
<ul>
|
|
|
|
|
<li>Taking advantage of available processing resources to reduce build time</li>
|
|
|
|
|
<li>Testing servers, where the server can be run in one thread and the test
|
|
|
|
|
harness is run in another thread.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<p>Care must be taken when using multithreading to ensure the tasks within the
|
2003-07-24 14:24:07 +00:00
|
|
|
threads do not interact. For example, two javac compile tasks which write
|
2001-08-09 10:48:12 +00:00
|
|
|
classes into the same destination directory may interact where one tries to
|
2003-07-24 14:24:07 +00:00
|
|
|
read a class for dependency information while the other task is writing the
|
|
|
|
|
class file. Be sure to avoid these types of interactions within a
|
2001-08-09 10:48:12 +00:00
|
|
|
<parallel> task</p>
|
2003-07-24 14:24:07 +00:00
|
|
|
|
|
|
|
|
<p>Any valid Ant task may be embedded within a
|
2001-08-09 10:48:12 +00:00
|
|
|
parallel task, including other parallel tasks.</p>
|
|
|
|
|
|
2003-07-24 14:24:07 +00:00
|
|
|
<p>Note that while the tasks within the parallel task are being run, the main
|
|
|
|
|
thread will be blocked waiting for all the child threads to complete. If
|
|
|
|
|
execution is terminated by a timeout or a nested task failure when the failonany
|
|
|
|
|
flag is set, the parallel task will complete without waiting for other nested
|
|
|
|
|
tasks to complete in other threads.
|
|
|
|
|
</p>
|
2001-08-09 10:48:12 +00:00
|
|
|
|
2003-07-24 14:24:07 +00:00
|
|
|
<p>If any of the tasks within the <parallel> task fails and failonany is
|
|
|
|
|
not set, the remaining tasks in other threads will continue to run until
|
|
|
|
|
all threads have completed. In this situation, the parallel task will also fail.</p>
|
2001-08-09 10:48:12 +00:00
|
|
|
|
2001-08-09 11:03:39 +00:00
|
|
|
<p>The parallel task may be combined with the <a href="sequential.html">
|
|
|
|
|
sequential</a> task to define sequences of tasks to be executed on each thread
|
|
|
|
|
within the parallel block</p>
|
|
|
|
|
|
2003-02-19 05:11:34 +00:00
|
|
|
<p>The threadCount attribute can be used to place a maximum number of available
|
|
|
|
|
threads for the execution. When not present all child tasks will be executed at
|
|
|
|
|
once. When present then the maximum number of concurrently executing tasks will
|
|
|
|
|
not exceed the number of threads specified. Furthermore, each task will be
|
2003-07-24 14:24:07 +00:00
|
|
|
started in the order they are given. But no guarantee is made as to the speed
|
2003-02-19 05:11:34 +00:00
|
|
|
of execution or the order of completion of the tasks, only that each will be
|
|
|
|
|
started before the next.<p>
|
|
|
|
|
|
|
|
|
|
<p>If you are using J2RE 1.4 or later you can also use the threadsPerProcessor
|
|
|
|
|
and the number of available threads will be the stated multiple of the number of
|
|
|
|
|
processors (there is no affinity to a particular processor however). This will
|
|
|
|
|
override the value in threadCount. If threadsPerProcessor is specified using
|
|
|
|
|
any version prior to 1.4 then the value in threadCount will be used as is.</p>
|
|
|
|
|
|
2003-07-24 14:24:07 +00:00
|
|
|
<p>When using threadCount and threadsPerProcessor care should be taken to ensure
|
2003-02-19 05:11:34 +00:00
|
|
|
that the build does not deadlock. This can be caused by tasks such as waitFor
|
2003-07-24 14:24:07 +00:00
|
|
|
taking up all available threads before the tasks that would unlock the waitfor
|
2003-02-19 05:11:34 +00:00
|
|
|
would occur. This is not a repalcement for Java Language level thread
|
2003-07-24 14:24:07 +00:00
|
|
|
semantics and is best used for "embarassingly parallel" tasks.</p>
|
2003-02-19 05:11:34 +00:00
|
|
|
|
2001-08-09 10:48:12 +00:00
|
|
|
<h3>Examples</h3>
|
|
|
|
|
<pre>
|
|
|
|
|
<parallel>
|
2002-09-04 11:05:19 +00:00
|
|
|
<wlrun ... >
|
2001-08-09 10:48:12 +00:00
|
|
|
<sequential>
|
|
|
|
|
<sleep seconds="30"/>
|
2002-09-04 11:05:19 +00:00
|
|
|
<junit ... >
|
2001-08-09 10:48:12 +00:00
|
|
|
<wlstop/>
|
|
|
|
|
</sequential>
|
|
|
|
|
</parallel>
|
|
|
|
|
</pre>
|
2003-07-24 14:24:07 +00:00
|
|
|
<p>This example represents a typical pattern for testing a server application.
|
|
|
|
|
In one thread the server is started (the wlrun task). The other thread consists
|
|
|
|
|
of a three tasks which are performed in sequence. The sleep task is used to
|
|
|
|
|
give the server time to come up. Another task which is capable of validating
|
|
|
|
|
that the server is available could be used in place of the sleep task. The
|
|
|
|
|
test harness is then run. 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 then
|
2001-08-09 10:48:12 +00:00
|
|
|
continue.</p>
|
|
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
<parallel>
|
|
|
|
|
<javac ...> <!-- compiler servlet code -->
|
|
|
|
|
<wljspc ...> <!-- precompile JSPs -->
|
|
|
|
|
</parallel>
|
|
|
|
|
</pre>
|
|
|
|
|
|
2003-07-24 14:24:07 +00:00
|
|
|
<p>This example shows two independent tasks being run to achieve better
|
2001-08-09 10:48:12 +00:00
|
|
|
resource utilization during the build. In this instance, some servlets are being
|
2003-07-24 14:24:07 +00:00
|
|
|
compiled in one thead and a set of JSPs is being precompiled in another. As
|
|
|
|
|
noted above, you need to be careful that the two tasks are independent, both in
|
2001-08-09 10:48:12 +00:00
|
|
|
terms of their dependencies and in terms of their potential interactions in
|
|
|
|
|
Ant's external environment.</p>
|
2003-02-19 05:11:34 +00:00
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
<parallel threadCount='4'>
|
|
|
|
|
<ant target='TargetThatConsumesLotsOfCPUTimeAndMemory'>
|
|
|
|
|
<param name='file' value='one.txt'/>
|
|
|
|
|
</ant>
|
|
|
|
|
<ant target='TargetThatConsumesLotsOfCPUTimeAndMemory'>
|
|
|
|
|
<param name='file' value='two.txt'/>
|
|
|
|
|
</ant>
|
|
|
|
|
<ant target='TargetThatConsumesLotsOfCPUTimeAndMemory'>
|
|
|
|
|
<param name='file' value='three.txt'/>
|
|
|
|
|
</ant>
|
|
|
|
|
<!-- repeated about 40 times -->
|
|
|
|
|
</parallel>
|
|
|
|
|
</pre>
|
|
|
|
|
|
2003-07-24 14:24:07 +00:00
|
|
|
<p>This example represents a typical need for use of the threadCount and
|
2003-02-19 05:11:34 +00:00
|
|
|
threadsPerProcessor attributes. Spinning up all 40 of those tasks could cripple
|
|
|
|
|
the JVM for memory and the CPU for available time. By limiting the number of
|
|
|
|
|
concurrent executions you can get the task done in about the same assuming
|
|
|
|
|
infinite memory time without needing infinite memory. This is also a good
|
|
|
|
|
candidiate for use of threadCount (and possibly threadsPerProcessor) because
|
|
|
|
|
each task (in this hypothetical case) is independent and has no dependencies on
|
|
|
|
|
the other tasks.</p>
|
|
|
|
|
|
2001-08-09 10:48:12 +00:00
|
|
|
<hr>
|
2003-02-19 07:34:48 +00:00
|
|
|
<p align="center">Copyright © 2001-2003 Apache Software Foundation. All rights
|
2001-08-09 10:48:12 +00:00
|
|
|
Reserved.</p>
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
|
|
|
|
|
