1 /*
2 * Copyright (c) 2004-2007 The Trustees of Indiana University and Indiana
3 * University Research and Technology
4 * Corporation. All rights reserved.
5 * Copyright (c) 2004-2005 The University of Tennessee and The University
6 * of Tennessee Research Foundation. All rights
7 * reserved.
8 * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
9 * University of Stuttgart. All rights reserved.
10 * Copyright (c) 2004-2005 The Regents of the University of California.
11 * All rights reserved.
12 * Copyright (c) 2015 Los Alamos National Security, LLC. All rights
13 * reserved.
14 * $COPYRIGHT$
15 *
16 * Additional copyrights may follow
17 *
18 * $HEADER$
19 *
20 *
21 * This file is almost a complete re-write for Open MPI compared to the
22 * original mpiJava package. Its license and copyright are listed below.
23 * See <path to ompi/mpi/java/README> for more information.
24 *
25 *
26 * Licensed under the Apache License, Version 2.0 (the "License");
27 * you may not use this file except in compliance with the License.
28 * You may obtain a copy of the License at
29 *
30 * http://www.apache.org/licenses/LICENSE-2.0
31 *
32 * Unless required by applicable law or agreed to in writing, software
33 * distributed under the License is distributed on an "AS IS" BASIS,
34 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
35 * See the License for the specific language governing permissions and
36 * limitations under the License.
37 *
38 *
39 * File : Group.java
40 * Author : Xinying Li, Bryan Carpenter
41 * Created : Thu Apr 9 12:22:15 1998
42 * Revision : $Revision: 1.8 $
43 * Updated : $Date: 2003/01/16 16:39:34 $
44 * Copyright: Northeast Parallel Architectures Center
45 * at Syracuse University 1998
46 */
47
48 package mpi;
49
50 /**
51 * This class represents {@code MPI_Group}.
52 */
53 public final class Group implements Freeable
54 {
55 protected long handle;
56 private static long nullHandle;
57
58 static
59 {
60 init();
61 }
62
63 private static native void init();
64
65 protected static native long getEmpty();
66
67 protected Group(long handle)
68 {
69 this.handle = handle;
70 }
71
72 /**
73 * Java binding of the MPI operation {@code MPI_GROUP_SIZE}.
74 * @return number of processes in the group
75 * @throws MPIException Signals that an MPI exception of some sort has occurred.
76 */
77 public int getSize() throws MPIException
78 {
79 MPI.check();
80 return getSize(handle);
81 }
82
83 private native int getSize(long group) throws MPIException;
84
85 /**
86 * Rank of this process in the group.
87 * <p>Java binding of the MPI operation {@code MPI_GROUP_RANK}.
88 * @return rank of this process in the group, or {@code MPI.UNDEFINED}
89 * if this process is not a member of the group.
90 * @throws MPIException Signals that an MPI exception of some sort has occurred.
91 */
92 public int getRank() throws MPIException
93 {
94 MPI.check();
95 return getRank(handle);
96 }
97
98 private native int getRank(long group) throws MPIException;
99
100 /**
101 * Java binding of the MPI operation {@code MPI_GROUP_FREE}.
102 */
103 @Override public void free() throws MPIException
104 {
105 MPI.check();
106 handle = free(handle);
107 }
108
109 private native long free(long group);
110
111 /**
112 * Test if group object is null.
113 * @return true if the group object is null.
114 */
115 public boolean isNull()
116 {
117 return handle == nullHandle;
118 }
119
120 /**
121 * Translate ranks within one group to ranks within another.
122 * <p>Java binding of the MPI operation {@code MPI_GROUP_TRANSLATE_RANKS}.
123 * <p>Result elements are {@code MPI.UNDEFINED} where no correspondence exists.
124 * @param group1 a group
125 * @param ranks1 array of valid ranks in group1
126 * @param group2 another group
127 * @return array of corresponding ranks in group2
128 * @throws MPIException Signals that an MPI exception of some sort has occurred.
129 */
130 public static int[] translateRanks(Group group1, int[] ranks1, Group group2)
131 throws MPIException
132 {
133 MPI.check();
134 return translateRanks(group1.handle, ranks1, group2.handle);
135 }
136
137 private static native int[] translateRanks(
138 long group1, int[] ranks1, long group2) throws MPIException;
139
140 /**
141 * Compare two groups.
142 * <p>Java binding of the MPI operation {@code MPI_GROUP_COMPARE}.
143 * @param group1 first group
144 * @param group2 second group
145 * @return {@code MPI.IDENT} if the group members and group order are exactly
146 * the same in both groups, {@code MPI.SIMILAR} if the group members are
147 * the same but the order is different, {@code MPI.UNEQUAL} otherwise.
148 * @throws MPIException Signals that an MPI exception of some sort has occurred.
149 */
150 public static int compare(Group group1, Group group2) throws MPIException
151 {
152 MPI.check();
153 return compare(group1.handle, group2.handle);
154 }
155
156 private static native int compare(long group1, long group2) throws MPIException;
157
158 /**
159 * Set union of two groups.
160 * <p>Java binding of the MPI operation {@code MPI_GROUP_UNION}.
161 * @param group1 first group
162 * @param group2 second group
163 * @return union group
164 * @throws MPIException Signals that an MPI exception of some sort has occurred.
165 */
166 public static Group union(Group group1, Group group2) throws MPIException
167 {
168 MPI.check();
169 return new Group(union(group1.handle, group2.handle));
170 }
171
172 private static native long union(long group1, long group2);
173
174 /**
175 * Set intersection of two groups.
176 * Java binding of the MPI operation {@code MPI_GROUP_INTERSECTION}.
177 * @param group1 first group
178 * @param group2 second group
179 * @return intersection group
180 * @throws MPIException Signals that an MPI exception of some sort has occurred.
181 */
182 public static Group intersection(Group group1, Group group2) throws MPIException
183 {
184 MPI.check();
185 return new Group(intersection(group1.handle, group2.handle));
186 }
187
188 private static native long intersection(long group1, long group2);
189
190 /**
191 * Set difference of two groups.
192 * Java binding of the MPI operation {@code MPI_GROUP_DIFFERENCE}.
193 * @param group1 first group
194 * @param group2 second group
195 * @return difference group
196 * @throws MPIException Signals that an MPI exception of some sort has occurred.
197 */
198 public static Group difference(Group group1, Group group2) throws MPIException
199 {
200 MPI.check();
201 return new Group(difference(group1.handle, group2.handle));
202 }
203
204 private static native long difference(long group1, long group2);
205
206 /**
207 * Create a subset group including specified processes.
208 * <p>Java binding of the MPI operation {@code MPI_GROUP_INCL}.
209 * @param ranks ranks from this group to appear in new group
210 * @return new group
211 * @throws MPIException Signals that an MPI exception of some sort has occurred.
212 */
213 public Group incl(int[] ranks) throws MPIException
214 {
215 MPI.check();
216 return new Group(incl(handle, ranks));
217 }
218
219 private native long incl(long group, int[] ranks);
220
221 /**
222 * Create a subset group excluding specified processes.
223 * <p>Java binding of the MPI operation {@code MPI_GROUP_EXCL}.
224 * @param ranks ranks from this group <em>not</em> to appear in new group
225 * @return new group
226 * @throws MPIException Signals that an MPI exception of some sort has occurred.
227 */
228 public Group excl(int[] ranks) throws MPIException
229 {
230 MPI.check();
231 return new Group(excl(handle, ranks));
232 }
233
234 private native long excl(long group, int[] ranks);
235
236 /**
237 * Create a subset group including processes specified
238 * by strided intervals of ranks.
239 * <p>Java binding of the MPI operation {@code MPI_GROUP_RANGE_INCL}.
240 * <p>The triplets are of the form (first rank, last rank, stride)
241 * indicating ranks in this group to be included in the new group.
242 * The size of the first dimension of {@code ranges} is the number
243 * of triplets. The size of the second dimension is 3.
244 * @param ranges array of integer triplets
245 * @return new group
246 * @throws MPIException Signals that an MPI exception of some sort has occurred.
247 */
248 public Group rangeIncl(int[][] ranges) throws MPIException
249 {
250 MPI.check();
251 return new Group(rangeIncl(handle, ranges));
252 }
253
254 private native long rangeIncl(long group, int[][] ranges);
255
256 /**
257 * Create a subset group excluding processes specified
258 * by strided intervals of ranks.
259 * <p>Java binding of the MPI operation {@code MPI_GROUP_RANGE_EXCL}.
260 * <p>Triplet array is defined as for {@code rangeIncl}, the ranges
261 * indicating ranks in this group to be excluded from the new group.
262 * @param ranges array of integer triplets
263 * @return new group
264 * @throws MPIException Signals that an MPI exception of some sort has occurred.
265 */
266 public Group rangeExcl(int[][] ranges) throws MPIException
267 {
268 MPI.check();
269 return new Group(rangeExcl(handle, ranges));
270 }
271
272 private native long rangeExcl(long group, int[][] ranges);
273
274 } // Group