Add group functions (v2.0) (#521)

* add MPI_Group consts

* add group APIs

* add group docs

* added MPI.Group-related functions to MPI.Comm interface

* tests added for groups

* fixes part of #514

* terminate group

Co-authored-by: Carlo Castoldi <[email protected]>

Author: carlocastoldi

deps/consts_microsoftmpi.jl

@@ -9,12 +9,20 @@ const MPI_COMM_NULL  = reinterpret(Cint, 0x04000000)
 const MPI_COMM_SELF  = reinterpret(Cint, 0x44000001)
 const MPI_COMM_WORLD = reinterpret(Cint, 0x44000000)
 
+const MPI_Group = Cint
+const MPI_GROUP_NULL  = reinterpret(Cint, 0x08000000)
+const MPI_GROUP_EMPTY = reinterpret(Cint, 0x48000000)
+
 const MPI_Info = Cint
 const MPI_INFO_NULL = reinterpret(Cint, 0x1c000000)
 
 const MPI_Win = Cint
 const MPI_WIN_NULL = reinterpret(Cint, 0x20000000)
 
+const MPI_Group = Cint
+const MPI_GROUP_NULL  = reinterpret(Cint, 0x08000000)
+const MPI_GROUP_EMPTY = reinterpret(Cint, 0x48000000)
+
 const MPI_Op = Cint
 const MPI_OP_NULL = reinterpret(Cint, 0x18000000)
 const MPI_MAX     = reinterpret(Cint, 0x58000001)

deps/consts_mpich.jl

@@ -20,6 +20,10 @@ const MPI_COMM_NULL = Cint(67108864)
 const MPI_COMM_SELF = Cint(1140850689)
 const MPI_COMM_WORLD = Cint(1140850688)
 
+const MPI_Group = Cint
+const MPI_GROUP_NULL  = Cint(134217728)
+const MPI_GROUP_EMPTY = Cint(1207959552)
+
 const MPI_Errhandler = Cint
 const MPI_ERRORS_ARE_FATAL = Cint(0x54000000)
 const MPI_ERRORS_RETURN = Cint(0x54000001)

deps/consts_openmpi.jl

@@ -23,6 +23,11 @@ const MPI_COMM_NULL = Cint(2)
 const MPI_COMM_SELF = Cint(1)
 const MPI_COMM_WORLD = Cint(0)
 
+const MPI_Group = Ptr{Cvoid}
+MPI_Group_f2c(c::Cint) = ccall((:MPI_Group_f2c,libmpi),MPI_Group,(Cint,),c)
+const MPI_GROUP_NULL  = Cint(0)
+const MPI_GROUP_EMPTY = Cint(1)
+
 const MPI_Errhandler = Ptr{Cvoid}
 MPI_Errhandler_f2c(c::Cint) = ccall((:MPI_Errhandler_f2c,libmpi),MPI_Errhandler,(Cint,),c)
 const MPI_ERRORS_ARE_FATAL = Cint(1)

deps/gen_consts.jl

@@ -108,6 +108,10 @@ MPI_handle = [
     :MPI_File => [
         :MPI_FILE_NULL,
     ],
+    :MPI_Group => [
+        :MPI_GROUP_NULL,
+        :MPI_GROUP_EMPTY
+    ],
     :MPI_Op => MPI_op_consts,
     :MPI_Datatype => MPI_datatype_consts
 ]

docs/src/comm.md

@@ -10,7 +10,6 @@ each process a unique *rank* (see [`MPI.Comm_rank`](@ref)) taking an integer val
 
 ```@docs
 MPI.Comm
-MPI.Comparison
 ```
 
 ## Constants
@@ -28,11 +27,15 @@ MPI.COMM_SELF
 MPI.Comm_size
 MPI.Comm_rank
 MPI.Comm_compare
+MPI.Comm_group
+MPI.Comm_remote_group
 ```
 
 ### Constructors
 
 ```@docs
+MPI.Comm_create
+MPI.Comm_create_group
 MPI.Comm_dup
 MPI.Comm_get_parent
 MPI.Comm_spawn

docs/src/group.md

@@ -0,0 +1,39 @@
+# Groups
+
+An MPI group is a set of process identifiers identified by their *rank* (see 
+[`MPI.Comm_rank`](@ref) and [`MPI.Group_rank`](@ref)). They are used within a 
+communicator to describe the participants in a communication *universe*.
+
+## Types and enums
+
+```@docs
+MPI.Group
+MPI.Comparison
+```
+
+## Constants
+
+```@docs
+MPI.GROUP_NULL
+MPI.GROUP_EMPTY
+```
+
+## Functions
+
+### Operations
+
+```@docs
+MPI.Group_size
+MPI.Group_rank
+MPI.Group_compare
+```
+
+### Constructors
+
+```@docs
+MPI.Group_difference
+MPI.Group_intersection
+MPI.Group_union
+MPI.Group_excl
+MPI.Group_incl
+```

src/MPI.jl

@@ -41,6 +41,7 @@ include("implementations.jl")
 include("error.jl")
 include("handle.jl")
 include("info.jl")
+include("group.jl")
 include("comm.jl")
 include("environment.jl")
 include("datatypes.jl")

src/comm.jl

@@ -68,6 +68,77 @@ function Comm_size(comm::Comm)
     Int(size[])
 end
 
+"""
+    Comm_group(comm::Comm)
+
+Accesses the group associated with given communicator.
+
+# External links
+$(_doc_external("MPI_Comm_group"))
+"""
+function Comm_group(comm::Comm)
+    newgroup = Group()
+    @mpichk ccall((:MPI_Comm_group, libmpi), Cint,
+        (MPI_Comm, Ptr{MPI_Group}), comm, newgroup)
+    finalizer(free, newgroup)
+    newgroup
+end
+
+"""
+Comm_remote_group(comm::Comm)
+
+Accesses the remote group associated with the given inter-communicator.
+
+# External links
+$(_doc_external("MPI_Comm_remote_group"))
+"""
+function Comm_remote_group(comm::Comm)
+    newgroup = Group()
+    @mpichk ccall((:MPI_Comm_remote_group, libmpi), Cint,
+        (MPI_Comm, Ptr{MPI_Group}), comm, newgroup)
+    finalizer(free, newgroup)
+    newgroup
+end
+
+"""
+    Comm_create(comm::Comm, group::Group)
+
+Collectively creates a new communicator.
+
+# See also
+- [`MPI.Comm_create_group`](@ref) for the noncollective operation
+
+# External links
+$(_doc_external("MPI_Comm_create"))
+"""
+function Comm_create(comm::Comm, group::Group)
+    newcomm = Comm()
+    @mpichk ccall((:MPI_Comm_create, libmpi), Cint,
+          (MPI_Comm, MPI_Group, Ptr{MPI_Comm}),
+          comm, group, newcomm)
+    finalizer(free, newcomm)
+    newcomm
+end
+
+"""
+    Comm_create_group(comm::Comm, group::Group, tag::Integer)
+
+Noncollectively creates a new communicator.
+
+# See also
+- [`MPI.Comm_create`](@ref) for the noncollective operation
+
+# External links
+$(_doc_external("MPI_Comm_create_group"))
+"""
+function Comm_create_group(comm::Comm, group::Group, tag::Integer)
+    newcomm = Comm()
+    @mpichk ccall((:MPI_Comm_create_group, libmpi), Cint,
+        (MPI_Comm, MPI_Group, Cint, Ptr{MPI_Comm}), comm, group, tag, newcomm)
+    finalizer(free, newcomm)
+    newcomm
+end
+
 """
     Comm_dup(comm::Comm)
 
@@ -174,32 +245,10 @@ function universe_size()
     Int(unsafe_load(result[]))
 end
 
-
-"""
-    Comparison
-
-An enum denoting the result of [`Comm_compare`](@ref):
-
- - `MPI.IDENT`: the objects are handles for the same object (identical groups and same contexts).
-
- - `MPI.CONGRUENT`: the underlying groups are identical in constituents and rank order; these communicators differ only by context.
-
- - `MPI.SIMILAR`: members of both objects are the same but the rank order differs.
-
- - `MPI.UNEQUAL`: otherwise
-"""
-@enum Comparison begin
-    IDENT     = MPI_IDENT
-    CONGRUENT = MPI_CONGRUENT
-    SIMILAR   = MPI_SIMILAR
-    UNEQUAL   = MPI_UNEQUAL
-end
-
-
 """
     Comm_compare(comm1::Comm, comm2::Comm)::MPI.Comparison
 
-Compare two communicators, returning an element of the [`Comparison`](@ref) enum.
+Compare two communicators and their underlying groups, returning an element of the [`Comparison`](@ref) enum.
 
 # External links
 $(_doc_external("MPI_Comm_compare"))

src/group.jl

@@ -0,0 +1,114 @@
+@mpi_handle Group
+
+const GROUP_NULL = _Group(MPI_GROUP_NULL)
+const GROUP_EMPTY = _Group(MPI_GROUP_EMPTY)
+
+Group() = Group(GROUP_NULL.val)
+
+# int MPI_Group_range_excl(MPI_Group group, int n, int ranges[][3], MPI_Group *newgroup)
+# int MPI_Group_range_incl(MPI_Group group, int n, int ranges[][3], MPI_Group *newgroup)
+# int MPI_Group_translate_ranks(MPI_Group group1, int n, const int ranks1[], MPI_Group group2, int ranks2[])
+
+function free(group::Group)
+    if group.val != GROUP_NULL.val && !Finalized()
+        @mpichk ccall((:MPI_Group_free, libmpi), Cint, (Ptr{MPI_Group},), group)
+    end
+    return nothing
+end
+
+"""
+    Group_size(group::Group)
+
+The number of processes involved in group.
+
+# External links
+$(_doc_external("MPI_Group_size"))
+"""
+function Group_size(group::Group)
+    size = Ref{Cint}()
+    @mpichk ccall((:MPI_Group_size, libmpi), Cint, (MPI_Group, Ptr{Cint}), group, size)
+    Int(size[])
+end
+
+"""
+    Group_rank(group::Group)
+
+The rank of the process in the particular group.
+
+Returns an integer in the range `0:MPI.Group_size()-1`.
+
+# External links
+$(_doc_external("MPI_Group_rank"))
+"""
+function Group_rank(group::Group)
+    rank = Ref{Cint}()
+    @mpichk ccall((:MPI_Group_rank, libmpi), Cint, (MPI_Group, Ptr{Cint}), group, rank)
+    Int(rank[])
+end
+
+"""
+    Comparison
+
+An enum denoting the result of [`Group_compare`](@ref) (and [`Comm_compare`](@ref)):
+
+ - `MPI.IDENT`: the objects are handles for the same object (identical groups and same contexts).
+
+ - `MPI.CONGRUENT`: the groups are identical in constituents and rank order; these ommunicators differ only by context.
+
+ - `MPI.SIMILAR`: members of both objects are the same but the rank order differs.
+
+ - `MPI.UNEQUAL`: otherwise
+"""
+@enum Comparison begin
+    IDENT     = MPI_IDENT
+    CONGRUENT = MPI_CONGRUENT
+    SIMILAR   = MPI_SIMILAR
+    UNEQUAL   = MPI_UNEQUAL
+end
+
+function Group_compare(group1::Group, group2::Group)
+    result = Ref{Comparison}()
+    @mpichk ccall((:MPI_Group_compare, libmpi), Cint,
+        (MPI_Group, MPI_Group, Ptr{Comparison}), group1, group2, result)
+    result[]
+end
+
+function Group_difference(group1::Group, group2::Group)
+    newgroup = Group()
+    @mpichk ccall((:MPI_Group_difference, libmpi), Cint,
+        (MPI_Group, MPI_Group, Ptr{MPI_Group}), group1, group2, newgroup)
+    finalizer(free, newgroup)
+    return newgroup
+end
+
+function Group_intersection(group1::Group, group2::Group)
+    newgroup = Group()
+    @mpichk ccall((:MPI_Group_intersection, libmpi), Cint,
+        (MPI_Group, MPI_Group, Ptr{MPI_Group}), group1, group2, newgroup)
+    finalizer(free, newgroup)
+    return newgroup
+end
+
+function Group_union(group1::Group, group2::Group)
+    newgroup = Group()
+    @mpichk ccall((:MPI_Group_union, libmpi), Cint,
+        (MPI_Group, MPI_Group, Ptr{MPI_Group}), group1, group2, newgroup)
+    finalizer(free, newgroup)
+    return newgroup
+end
+
+function Group_excl(group::Group, ranks::Vector{Cint})
+    newgroup = Group()
+    @mpichk ccall((:MPI_Group_excl, libmpi), Cint,
+        (MPI_Group, Cint, Ptr{Cint}, Ptr{MPI_Group}), group, length(ranks), ranks, newgroup)
+    finalizer(free, newgroup)
+    return newgroup
+end
+
+function Group_incl(group::Group, ranks::Vector{Cint})
+    newgroup = Group()
+    @mpichk ccall((:MPI_Group_incl, libmpi), Cint,
+        (MPI_Group, Cint, Ptr{Cint}, Ptr{MPI_Group}), group, length(ranks), ranks, newgroup)
+    finalizer(free, newgroup)
+    return newgroup
+end

src/io.jl

@@ -361,7 +361,7 @@ Writes to `file` using the shared file pointer from `data`. `data` can be a
 [`Buffer`](@ref), or any object for which `Buffer(data)` is defined.
 
 # See also
-- [`MPI.File.write_ordered`](@ref) for the noncollective operation
+- [`MPI.File.write_ordered`](@ref) for the collective operation
 
 # External links
 $(_doc_external("MPI_File_write_shared"))
@@ -387,7 +387,7 @@ is a collective operation, so must be called on all ranks in the communicator on
 `file` was opened.
 
 # See also
-- [`MPI.File.read_shared!`](@ref) for the non-collective operation
+- [`MPI.File.read_shared!`](@ref) for the noncollective operation
 
 # External links
 $(_doc_external("MPI_File_read_ordered"))

test/test_group.jl

@@ -0,0 +1,26 @@
+using Test
+using MPI
+
+MPI.Init()
+
+comm = MPI.COMM_WORLD
+grp = MPI.Comm_group(comm)
+@test MPI.Comm_size(comm) == MPI.Group_size(grp)
+@test MPI.Comm_rank(comm) == MPI.Group_rank(grp)
+@test MPI.Group_compare(grp, grp) === MPI.IDENT
+grp2 = MPI.Group_union(grp, MPI.GROUP_EMPTY)
+@test MPI.Group_compare(grp, grp2) === MPI.IDENT
+grp3 = MPI.Group_difference(grp, grp2)
+@test MPI.Group_compare(grp3, MPI.GROUP_EMPTY) === MPI.IDENT
+grp4 = MPI.Group_intersection(grp, grp2)
+@test MPI.Group_compare(grp4, MPI.GROUP_EMPTY) === MPI.UNEQUAL
+grp5 = MPI.Group_excl(grp, Int32[0])
+@test MPI.Group_size(grp5) == (MPI.Group_size(grp)-1)
+grp6 = MPI.Group_incl(grp, Int32[0])
+@test MPI.Group_size(grp6) == 1
+
+# Don't free the other groups
+MPI.free(grp)
+
+MPI.Finalize()
+@test MPI.Finalized()