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