1 //******************************************************************************
2 //
3 // File: ParallelSection.java
4 // Package: edu.rit.pj
5 // Unit: Class edu.rit.pj.ParallelSection
6 //
7 // This Java source file is copyright (C) 2007 by Alan Kaminsky. All rights
8 // reserved. For further information, contact the author, Alan Kaminsky, at
9 // ark@cs.rit.edu.
10 //
11 // This Java source file is part of the Parallel Java Library ("PJ"). PJ is free
12 // software; you can redistribute it and/or modify it under the terms of the GNU
13 // General Public License as published by the Free Software Foundation; either
14 // version 3 of the License, or (at your option) any later version.
15 //
16 // PJ is distributed in the hope that it will be useful, but WITHOUT ANY
17 // WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
18 // A PARTICULAR PURPOSE. See the GNU General Public License for more details.
19 //
20 // Linking this library statically or dynamically with other modules is making a
21 // combined work based on this library. Thus, the terms and conditions of the GNU
22 // General Public License cover the whole combination.
23 //
24 // As a special exception, the copyright holders of this library give you
25 // permission to link this library with independent modules to produce an
26 // executable, regardless of the license terms of these independent modules, and
27 // to copy and distribute the resulting executable under terms of your choice,
28 // provided that you also meet, for each linked independent module, the terms
29 // and conditions of the license of that module. An independent module is a module
30 // which is not derived from or based on this library. If you modify this library,
31 // you may extend this exception to your version of the library, but you are not
32 // obligated to do so. If you do not wish to do so, delete this exception
33 // statement from your version.
34 //
35 // A copy of the GNU General Public License is provided in the file gpl.txt. You
36 // may also obtain a copy of the GNU General Public License on the World Wide
37 // Web at http://www.gnu.org/licenses/gpl.html.
38 //
39 //******************************************************************************
40 package edu.rit.pj;
41
42 /**
43 * Class ParallelSection is the abstract base class for a section of code to be
44 * executed in parallel.
45 * <P>
46 * A group of parallel sections may be executed concurrently by calling a
47 * {@linkplain ParallelRegion}'s <code>execute()</code> method. Each section in the
48 * group is executed by a different thread in the parallel thread team. Here is
49 * one way to code a parallel section group with two parallel sections:
50 * <PRE>
51 * new ParallelTeam(2).execute (new ParallelRegion()
52 * {
53 * public void run() throws Exception
54 * {
55 * execute
56 * (new ParallelSection()
57 * {
58 * public void run()
59 * {
60 * // Code for first concurrent parallel section
61 * . . .
62 * }
63 * },
64 * new ParallelSection()
65 * {
66 * public void run()
67 * {
68 * // Code for second concurrent parallel section
69 * . . .
70 * }
71 * });
72 * }
73 * });
74 * </PRE> Here is another way to code a parallel section group with two parallel
75 * sections:
76 * <PRE>
77 * ParallelSection section_1 = new ParallelSection()
78 * {
79 * public void run()
80 * {
81 * // Code for first concurrent parallel section
82 * . . .
83 * }
84 * };
85 * ParallelSection section_2 = new ParallelSection()
86 * {
87 * public void run()
88 * {
89 * // Code for second concurrent parallel section
90 * . . .
91 * }
92 * };
93 * new ParallelTeam(2).execute (new ParallelRegion()
94 * {
95 * public void run() throws Exception
96 * {
97 * execute (section_1, section_2);
98 * }
99 * });
100 * </PRE> A parallel section group may contain any number of parallel sections.
101 * There are overloaded <code>execute()</code> methods that take one, two, or three
102 * parallel section arguments. If there are four or more parallel sections, put
103 * them in an array (type <code>ParallelSection[]</code>) and pass the array to the
104 * <code>execute()</code> method.
105 * <P>
106 * Normally, at the end of the parallel section group, the parallel team threads
107 * wait for each other at a barrier. To eliminate this barrier wait, include
108 * {@link edu.rit.pj.BarrierAction#NO_WAIT BarrierAction.NO_WAIT} in the <code>execute()</code>
109 * method call:
110 * <PRE>
111 * new ParallelTeam(2).execute (new ParallelRegion()
112 * {
113 * public void run() throws Exception
114 * {
115 * execute (section_1, section_2, BarrierAction.NO_WAIT);
116 * }
117 * });
118 * </PRE> To execute a section of code in a single thread as part of the barrier
119 * synchronization, include an instance of class {@linkplain BarrierAction} in
120 * the <code>execute()</code> method call. The barrier action object's
121 * <code>run()</code> method contains the code to be executed in a single thread
122 * while the other threads wait:
123 * <PRE>
124 * new ParallelTeam(2).execute (new ParallelRegion()
125 * {
126 * public void run() throws Exception
127 * {
128 * execute (section_1, section_2, new BarrierAction()
129 * {
130 * public void run()
131 * {
132 * // Single-threaded code goes here
133 * . . .
134 * }
135 * });
136 * }
137 * });
138 * </PRE> For further information, see class {@linkplain BarrierAction}.
139 * <P>
140 * A parallel section may be executed by one thread in the parallel thread team
141 * by executing a parallel section group consisting of the one parallel section,
142 * as shown above:
143 * <PRE>
144 * new ParallelTeam().execute (new ParallelRegion()
145 * {
146 * public void run() throws Exception
147 * {
148 * . . .
149 * execute (new ParallelSection()
150 * {
151 * public void run()
152 * {
153 * // Code to be executed by one parallel team thread
154 * . . .
155 * }
156 * });
157 * . . .
158 * }
159 * });
160 * </PRE>
161 * <P>
162 * A parallel section may be executed in a mutually exclusive fashion by calling
163 * a {@linkplain ParallelRegion}'s <code>critical()</code> or
164 * <code>criticalNonexclusive()</code> method. For example:
165 * <PRE>
166 * new ParallelTeam().execute (new ParallelRegion()
167 * {
168 * public void run() throws Exception
169 * {
170 * . . .
171 * critical (new ParallelSection()
172 * {
173 * public void run()
174 * {
175 * // Mutually exclusive code
176 * . . .
177 * }
178 * });
179 * . . .
180 * }
181 * });
182 * </PRE>
183 * <P>
184 * By calling a {@linkplain ParallelForLoop}'s <code>ordered()</code> method, a
185 * parallel section may be executed in the order of the loop indexes within a
186 * parallel for loop body, while the rest of the parallel for loop body executes
187 * concurrently. See classes {@linkplain IntegerForLoop}, {@linkplain
188 * IntegerStrideForLoop}, {@linkplain LongForLoop}, and {@linkplain
189 * LongStrideForLoop} for further information.
190 * <P>
191 * By calling a {@linkplain ParallelIteration}'s <code>ordered()</code> method, a
192 * parallel section may be executed in the order of the items within a parallel
193 * iteration body, while the rest of the parallel iteration body executes
194 * concurrently. See class {@linkplain ParallelIteration} for further
195 * information.
196 *
197 * @author Alan Kaminsky
198 * @version 11-Nov-2007
199 */
200 public abstract class ParallelSection
201 extends ParallelConstruct {
202
203 // Exported constructors.
204 /**
205 * Construct a new parallel section.
206 */
207 public ParallelSection() {
208 super();
209 }
210
211 // Exported operations.
212 /**
213 * Execute this parallel section.
214 * <P>
215 * The <code>run()</code> method must be implemented in a subclass.
216 *
217 * @exception Exception The <code>run()</code> method may throw any exception.
218 * @throws java.lang.Exception if any.
219 */
220 public abstract void run()
221 throws Exception;
222
223 }