View Javadoc
1   //******************************************************************************
2   //
3   // File:    BarrierAction.java
4   // Package: edu.rit.pj
5   // Unit:    Class edu.rit.pj.BarrierAction
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 BarrierAction is the abstract base class for an object containing code
44   * that is executed as part of a barrier wait. A barrier wait occurs in these
45   * situations within a {@linkplain ParallelRegion}:
46   * <UL>
47   * <LI>
48   * When the {@linkplain ParallelTeam} threads finish executing all the
49   * iterations of a parallel for loop.
50   * </LI>
51   * <LI>
52   * When the {@linkplain ParallelTeam} threads finish executing all the
53   * {@linkplain ParallelSection}s in a group of parallel sections.
54   * </LI>
55   * <LI>
56   * When the {@linkplain ParallelTeam} threads call the {@linkplain
57   * ParallelRegion}'s <code>barrier()</code> method explicitly.
58   * </LI>
59   * </UL>
60   * As each thread finishes executing one of the above constructs, each thread
61   * encounters a barrier. What happens next depends on the barrier action
62   * specified for that construct. There are three possibilities:
63   * <UL>
64   * <LI>
65   * If the barrier action is omitted, or if the barrier action is {@link #WAIT
66   * BarrierAction.WAIT}, each thread stops and waits at the barrier. When all
67   * threads have arrived at the barrier, each thread resumes and proceeds to
68   * execute whatever comes after the construct.
69   * </LI>
70   * <LI>
71   * If the barrier action is {@link #NO_WAIT BarrierAction.NO_WAIT}, nothing
72   * happens. The threads do not wait for each other. Each thread immediately
73   * proceeds to execute whatever comes after the construct.
74   * </LI>
75   * <LI>
76   * If the barrier action is an instance of class BarrierAction with the
77   * <code>run()</code> method overridden, each thread stops and waits at the barrier.
78   * When all threads have arrived at the barrier, <I>one</I> thread calls the
79   * BarrierAction object's <code>run()</code> method. The particular thread that
80   * calls the <code>run()</code> method is not specified. During this time the other
81   * threads remain stopped. When the <code>run()</code> method returns, each thread
82   * resumes and proceeds to execute whatever comes after the construct.
83   * </LI>
84   * </UL>
85   * <p>
86   * Thus, the barrier serves to synchronize all the threads at the end of a
87   * parallel construct and possibly to execute a section of code in a single
88   * thread.
89   *
90   * @author Alan Kaminsky
91   * @version 11-Nov-2007
92   */
93  public abstract class BarrierAction
94          extends ParallelConstruct {
95  
96  // Exported constructors.
97  
98      /**
99       * Construct a new barrier action.
100      */
101     public BarrierAction() {
102     }
103 
104 // Exported operations.
105 
106     /**
107      * Execute this barrier action. The <code>run()</code> method is called by a
108      * single thread after all threads have arrived at the barrier.
109      * <p>
110      * The <code>run()</code> method must be implemented in a subclass.
111      *
112      * @throws java.lang.Exception           The <code>run()</code> method may throw any exception.
113      * @throws java.lang.Exception if any.
114      */
115     public abstract void run()
116             throws Exception;
117 
118 // Hidden operations.
119 
120     /**
121      * Execute a barrier.
122      *
123      * @param currentThread Parallel team thread calling <code>doBarrier()</code>.
124      * @throws Exception The <code>run()</code> method may throw any exception.
125      */
126     void doBarrier(ParallelTeamThread currentThread)
127             throws Exception {
128         // Default is to do a barrier wait with this as the barrier action.
129         currentThread.barrier(this);
130     }
131 
132 // Exported constants.
133     /**
134      * Do a barrier wait, without executing any code in a single thread.
135      */
136     public static final BarrierAction WAIT = new BarrierAction() {
137         public void run() {
138         }
139 
140         void doBarrier(ParallelTeamThread currentThread)
141                 throws Exception {
142             currentThread.barrier();
143         }
144     };
145 
146     /**
147      * Do not do a barrier wait.
148      */
149     public static final BarrierAction NO_WAIT = new BarrierAction() {
150         public void run() {
151         }
152 
153         void doBarrier(ParallelTeamThread currentThread)
154                 throws Exception {
155         }
156     };
157 
158 }