Wrap MPI_Comm_compare (#374)

Co-authored-by: Simon Byrne <[email protected]>

Author: jipolanco

deps/gen_consts.jl

@@ -115,6 +115,10 @@ MPI_Cints = [
     :MPI_MODE_UNIQUE_OPEN,
     :MPI_MODE_SEQUENTIAL,
     :MPI_MODE_APPEND,
+    :MPI_IDENT,
+    :MPI_CONGRUENT,
+    :MPI_SIMILAR,
+    :MPI_UNEQUAL,
 ]
 
 MPI_pointers = [

docs/src/comm.md

@@ -6,10 +6,11 @@ each process a unique *rank* (see [`MPI.Comm_rank`](@ref)) taking an integer val
 `0:n-1`, where `n` is the number of processes in the communicator (see
 [`MPI.Comm_size`](@ref).
 
-## Types
+## Types and enums
 
 ```@docs
 MPI.Comm
+MPI.Comparison
 ```
 
 ## Constants
@@ -21,11 +22,12 @@ MPI.COMM_SELF
 
 ## Functions
 
-### Accessors
+### Operations
 
 ```@docs
 MPI.Comm_size
 MPI.Comm_rank
+MPI.Comm_compare
 ```
 
 ### Constructors

src/comm.jl

@@ -179,3 +179,40 @@ function universe_size()
     end
     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.
+
+# External links
+$(_doc_external("MPI_Comm_compare"))
+"""
+function Comm_compare(comm1::Comm, comm2::Comm)
+    result = Ref{Comparison}()
+    @mpichk ccall((:MPI_Comm_compare, libmpi), Cint,
+                  (MPI_Comm, MPI_Comm, Ptr{Comparison}), comm1, comm2, result)
+    result[]
+end

src/consts/microsoftmpi.jl

@@ -102,6 +102,11 @@ const MPI_IN_PLACE = reinterpret(SentinelPtr, -1)
 const MPI_STATUS_IGNORE = reinterpret(SentinelPtr, 1)
 const MPI_STATUSES_IGNORE = reinterpret(SentinelPtr, 1)
 
+const MPI_IDENT = Cint(0)
+const MPI_CONGRUENT = Cint(1)
+const MPI_SIMILAR = Cint(2)
+const MPI_UNEQUAL = Cint(3)
+
 struct Status
     _pad1::Cint
     _pad2::Cint

src/consts/mpich.jl

@@ -105,3 +105,8 @@ const MPI_BOTTOM = reinterpret(SentinelPtr, 0)
 const MPI_IN_PLACE = reinterpret(SentinelPtr, -1)
 const MPI_STATUS_IGNORE = reinterpret(SentinelPtr, 1)
 const MPI_STATUSES_IGNORE = reinterpret(SentinelPtr, 1)
+
+const MPI_IDENT = Cint(0)
+const MPI_CONGRUENT = Cint(1)
+const MPI_SIMILAR = Cint(2)
+const MPI_UNEQUAL = Cint(3)

src/consts/openmpi.jl

@@ -111,3 +111,8 @@ const MPI_BOTTOM = reinterpret(SentinelPtr, 0)
 const MPI_IN_PLACE = reinterpret(SentinelPtr, 1)
 const MPI_STATUS_IGNORE = reinterpret(SentinelPtr, 0)
 const MPI_STATUSES_IGNORE = reinterpret(SentinelPtr, 0)
+
+const MPI_IDENT = Cint(0)
+const MPI_CONGRUENT = Cint(1)
+const MPI_SIMILAR = Cint(2)
+const MPI_UNEQUAL = Cint(3)

test/test_comm.jl

@@ -4,10 +4,14 @@ using MPI
 MPI.Init()
 
 comm = MPI.COMM_WORLD
+@test MPI.Comm_compare(comm, comm) === MPI.IDENT
+@test MPI.Comm_compare(comm, MPI.COMM_SELF) == (MPI.Comm_size(comm) == 1 ? MPI.CONGRUENT : MPI.UNEQUAL)
 MPI.Barrier(comm)
 comm2 = MPI.Comm_dup(comm)
+@test MPI.Comm_compare(comm, comm2) === MPI.CONGRUENT
 MPI.Barrier(comm2)
 comm3 = MPI.Comm_dup(comm2)
+@test MPI.Comm_compare(comm, comm3) === MPI.CONGRUENT
 MPI.Barrier(comm3)
 MPI.free(comm2)
 MPI.Barrier(comm3)