| 1 | <!--
|
|---|
| 2 | Licensed to the Apache Software Foundation (ASF) under one or more
|
|---|
| 3 | contributor license agreements. See the NOTICE file distributed with
|
|---|
| 4 | this work for additional information regarding copyright ownership.
|
|---|
| 5 | The ASF licenses this file to You under the Apache License, Version 2.0
|
|---|
| 6 | (the "License"); you may not use this file except in compliance with
|
|---|
| 7 | the License. You may obtain a copy of the License at
|
|---|
| 8 |
|
|---|
| 9 | http://www.apache.org/licenses/LICENSE-2.0
|
|---|
| 10 |
|
|---|
| 11 | Unless required by applicable law or agreed to in writing, software
|
|---|
| 12 | distributed under the License is distributed on an "AS IS" BASIS,
|
|---|
| 13 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|---|
| 14 | See the License for the specific language governing permissions and
|
|---|
| 15 | limitations under the License.
|
|---|
| 16 | -->
|
|---|
| 17 | <html>
|
|---|
| 18 |
|
|---|
| 19 | <head>
|
|---|
| 20 | <meta http-equiv="Content-Language" content="en-us">
|
|---|
| 21 | <link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
|
|---|
| 22 | <title>Parallel Task</title>
|
|---|
| 23 | </head>
|
|---|
| 24 |
|
|---|
| 25 | <body>
|
|---|
| 26 |
|
|---|
| 27 | <h2>Parallel</h2>
|
|---|
| 28 | <h3>Description</h3>
|
|---|
| 29 | <p>Parallel is a container task - it can contain other Ant tasks. Each nested
|
|---|
| 30 | task within the parallel task will be executed in its own thread. </p>
|
|---|
| 31 | <h3>Parameters</h3>
|
|---|
| 32 | <table border="1" cellpadding="2" cellspacing="0">
|
|---|
| 33 | <tr>
|
|---|
| 34 | <td valign="top"><b>Attribute</b></td>
|
|---|
| 35 | <td valign="top"><b>Description</b></td>
|
|---|
| 36 | <td align="center" valign="top"><b>Required</b></td>
|
|---|
| 37 | </tr>
|
|---|
| 38 | <tr>
|
|---|
| 39 | <td valign="top">threadCount</td>
|
|---|
| 40 | <td valign="top">Maximum numbers of thread to use.</td>
|
|---|
| 41 | <td align="center" valign="top">No</td>
|
|---|
| 42 | </tr>
|
|---|
| 43 | <tr>
|
|---|
| 44 | <td valign="top">threadsPerProcessor</td>
|
|---|
| 45 | <td valign="top">Maximum number of threads to use per available processor
|
|---|
| 46 | (Requires JDK 1.4)</td>
|
|---|
| 47 | <td align="center" valign="top">No, defers to threadCount</td>
|
|---|
| 48 | </tr>
|
|---|
| 49 | <tr>
|
|---|
| 50 | <td valign="top">pollInterval</td>
|
|---|
| 51 | <td valign="top">Currently has no effect</td>
|
|---|
| 52 | <td align="center" valign="top">No, default is 1000</td>
|
|---|
| 53 | </tr>
|
|---|
| 54 | <tr>
|
|---|
| 55 | <td valign="top">timeout</td>
|
|---|
| 56 | <td valign="top">Number of milliseconds before execution is terminated</td>
|
|---|
| 57 | <td align="center" valign="top">No</td>
|
|---|
| 58 | </tr>
|
|---|
| 59 | <tr>
|
|---|
| 60 | <td valign="top">failonany</td>
|
|---|
| 61 | <td valign="top">If any of the nested tasks fails, execution of the task completes
|
|---|
| 62 | at that point without waiting for any other tasks to complete.</td>
|
|---|
| 63 | <td align="center" valign="top">No</td>
|
|---|
| 64 | </tr>
|
|---|
| 65 | </table>
|
|---|
| 66 |
|
|---|
| 67 | <p>Parallel tasks have a number of uses in an Ant build file including:</p>
|
|---|
| 68 | <ul>
|
|---|
| 69 | <li>Taking advantage of available processing resources to reduce build time</li>
|
|---|
| 70 | <li>Testing servers, where the server can be run in one thread and the test
|
|---|
| 71 | harness is run in another thread.</li>
|
|---|
| 72 | </ul>
|
|---|
| 73 |
|
|---|
| 74 | <p>Care must be taken when using multithreading to ensure the tasks within the
|
|---|
| 75 | threads do not interact. For example, two javac compile tasks which write
|
|---|
| 76 | classes into the same destination directory may interact where one tries to
|
|---|
| 77 | read a class for dependency information while the other task is writing the
|
|---|
| 78 | class file. Be sure to avoid these types of interactions within a
|
|---|
| 79 | <code><parallel></code> task</p>
|
|---|
| 80 |
|
|---|
| 81 | <p>Any valid Ant task may be embedded within a
|
|---|
| 82 | parallel task, including other parallel tasks.</p>
|
|---|
| 83 |
|
|---|
| 84 | <p>Note that while the tasks within the parallel task are being run, the main
|
|---|
| 85 | thread will be blocked waiting for all the child threads to complete. If
|
|---|
| 86 | execution is terminated by a timeout or a nested task failure when the failonany
|
|---|
| 87 | flag is set, the parallel task will complete without waiting for other nested
|
|---|
| 88 | tasks to complete in other threads.
|
|---|
| 89 | </p>
|
|---|
| 90 |
|
|---|
| 91 | <p>If any of the tasks within the <code><parallel></code> task fails and failonany is
|
|---|
| 92 | not set, the remaining tasks in other threads will continue to run until
|
|---|
| 93 | all threads have completed. In this situation, the parallel task will also fail.</p>
|
|---|
| 94 |
|
|---|
| 95 | <p>The parallel task may be combined with the <a href="sequential.html">
|
|---|
| 96 | sequential</a> task to define sequences of tasks to be executed on each thread
|
|---|
| 97 | within the parallel block</p>
|
|---|
| 98 |
|
|---|
| 99 | <p>The threadCount attribute can be used to place a maximum number of available
|
|---|
| 100 | threads for the execution. When not present all child tasks will be executed at
|
|---|
| 101 | once. When present then the maximum number of concurrently executing tasks will
|
|---|
| 102 | not exceed the number of threads specified. Furthermore, each task will be
|
|---|
| 103 | started in the order they are given. But no guarantee is made as to the speed
|
|---|
| 104 | of execution or the order of completion of the tasks, only that each will be
|
|---|
| 105 | started before the next.<p>
|
|---|
| 106 |
|
|---|
| 107 | <p>If you are using J2RE 1.4 or later you can also use the threadsPerProcessor
|
|---|
| 108 | and the number of available threads will be the stated multiple of the number of
|
|---|
| 109 | processors (there is no affinity to a particular processor however). This will
|
|---|
| 110 | override the value in threadCount. If threadsPerProcessor is specified using
|
|---|
| 111 | any version prior to 1.4 then the value in threadCount will be used as is.</p>
|
|---|
| 112 |
|
|---|
| 113 | <p>When using threadCount and threadsPerProcessor care should be taken to ensure
|
|---|
| 114 | that the build does not deadlock. This can be caused by tasks such as waitFor
|
|---|
| 115 | taking up all available threads before the tasks that would unlock the waitfor
|
|---|
| 116 | would occur. This is not a repalcement for Java Language level thread
|
|---|
| 117 | semantics and is best used for "embarassingly parallel" tasks.</p>
|
|---|
| 118 |
|
|---|
| 119 |
|
|---|
| 120 | <h3>Parameters specified as nested elements</h3>
|
|---|
| 121 |
|
|---|
| 122 | <h4>daemons</h4>
|
|---|
| 123 | <p>
|
|---|
| 124 | The parallel task supports a <code><daemons></code> nested element. This is a list of tasks
|
|---|
| 125 | which are to be run in parallel daemon threads. The parallel task will not wait for
|
|---|
| 126 | these tasks to complete. Being daemon threads, however, they will not prevent Ant from
|
|---|
| 127 | completing, whereupon the threads are terminated. Failures in daemon threads which
|
|---|
| 128 | occur before the parallel task itself finishes will be reported and can cause
|
|---|
| 129 | parallel to throw an exception. Failures which occur after parallel has completed are not
|
|---|
| 130 | reported.
|
|---|
| 131 | </p>
|
|---|
| 132 |
|
|---|
| 133 | <p>Daemon tasks can be used, for example, to start test servers which might not be easily
|
|---|
| 134 | terminated from Ant. By using <code><daemons></code> such servers do not halt the build.
|
|---|
| 135 | </p>
|
|---|
| 136 |
|
|---|
| 137 |
|
|---|
| 138 | <h3>Examples</h3>
|
|---|
| 139 | <pre>
|
|---|
| 140 | <parallel>
|
|---|
| 141 | <wlrun ... >
|
|---|
| 142 | <sequential>
|
|---|
| 143 | <sleep seconds="30"/>
|
|---|
| 144 | <junit ... >
|
|---|
| 145 | <wlstop/>
|
|---|
| 146 | </sequential>
|
|---|
| 147 | </parallel>
|
|---|
| 148 | </pre>
|
|---|
| 149 | <p>This example represents a typical pattern for testing a server application.
|
|---|
| 150 | In one thread the server is started (the wlrun task). The other thread consists
|
|---|
| 151 | of a three tasks which are performed in sequence. The sleep task is used to
|
|---|
| 152 | give the server time to come up. Another task which is capable of validating
|
|---|
| 153 | that the server is available could be used in place of the sleep task. The
|
|---|
| 154 | test harness is then run. Once the tests are complete, the server is stopped
|
|---|
| 155 | (using wlstop in this example), allowing both threads to complete. The
|
|---|
| 156 | parallel task will also complete at this time and the build will then
|
|---|
| 157 | continue.</p>
|
|---|
| 158 |
|
|---|
| 159 | <pre>
|
|---|
| 160 | <parallel>
|
|---|
| 161 | <javac ...> <!-- compiler servlet code -->
|
|---|
| 162 | <wljspc ...> <!-- precompile JSPs -->
|
|---|
| 163 | </parallel>
|
|---|
| 164 | </pre>
|
|---|
| 165 |
|
|---|
| 166 | <p>This example shows two independent tasks being run to achieve better
|
|---|
| 167 | resource utilization during the build. In this instance, some servlets are being
|
|---|
| 168 | compiled in one thead and a set of JSPs is being precompiled in another. As
|
|---|
| 169 | noted above, you need to be careful that the two tasks are independent, both in
|
|---|
| 170 | terms of their dependencies and in terms of their potential interactions in
|
|---|
| 171 | Ant's external environment.</p>
|
|---|
| 172 |
|
|---|
| 173 | <pre>
|
|---|
| 174 | <parallel threadCount='4'>
|
|---|
| 175 | <ant target='TargetThatConsumesLotsOfCPUTimeAndMemory'>
|
|---|
| 176 | <param name='file' value='one.txt'/>
|
|---|
| 177 | </ant>
|
|---|
| 178 | <ant target='TargetThatConsumesLotsOfCPUTimeAndMemory'>
|
|---|
| 179 | <param name='file' value='two.txt'/>
|
|---|
| 180 | </ant>
|
|---|
| 181 | <ant target='TargetThatConsumesLotsOfCPUTimeAndMemory'>
|
|---|
| 182 | <param name='file' value='three.txt'/>
|
|---|
| 183 | </ant>
|
|---|
| 184 | <!-- repeated about 40 times -->
|
|---|
| 185 | </parallel>
|
|---|
| 186 | </pre>
|
|---|
| 187 |
|
|---|
| 188 | <p>This example represents a typical need for use of the threadCount and
|
|---|
| 189 | threadsPerProcessor attributes. Spinning up all 40 of those tasks could cripple
|
|---|
| 190 | the JVM for memory and the CPU for available time. By limiting the number of
|
|---|
| 191 | concurrent executions you can get the task done in about the same assuming
|
|---|
| 192 | infinite memory time without needing infinite memory. This is also a good
|
|---|
| 193 | candidiate for use of threadCount (and possibly threadsPerProcessor) because
|
|---|
| 194 | each task (in this hypothetical case) is independent and has no dependencies on
|
|---|
| 195 | the other tasks.</p>
|
|---|
| 196 |
|
|---|
| 197 |
|
|---|
| 198 | </body>
|
|---|
| 199 | </html>
|
|---|
| 200 |
|
|---|
