revamp Info object (#258)

* Make MPI.Info a subtype of AbstractDict
* Allocated buffer correctly for strings

Author: simonbyrne

deps/build.jl

@@ -60,6 +60,8 @@ MPI_constants = [
     "MPI_REQUEST_NULL",
 
     # info
+    "MPI_MAX_INFO_KEY",
+    "MPI_MAX_INFO_VAL",
     "MPI_INFO_NULL",
 
     # proc
@@ -120,6 +122,8 @@ MPI_functions = [
     "MPI_INFO_DELETE",
     "MPI_INFO_FREE",
     "MPI_INFO_GET",
+    "MPI_INFO_GET_NKEYS",
+    "MPI_INFO_GET_NTHKEY",
     "MPI_INFO_GET_VALUELEN",
     "MPI_INFO_SET",
     "MPI_INIT",

docs/src/functions.md

@@ -204,4 +204,11 @@ MPI.Put
 MPI.Fetch_and_op
 MPI.Accumulate
 MPI.Get_accumulate
+```
+
+# Info objects
+
+```@docs
+MPI.Info
+MPI.infoval
 ```

src/MPI.jl

@@ -19,6 +19,7 @@ include(depfile)
 
 include("mpi-base.jl")
 include("cman.jl")
+include("deprecated.jl")
 
 const mpitype_dict = Dict{DataType, Cint}()
 const mpitype_dict_inverse = Dict{Cint, DataType}()

src/deprecated.jl

@@ -0,0 +1,13 @@
+import Base: @deprecate
+
+# to be deprecated
+const FINALIZE_ATEXIT = Ref(true)
+@deprecate finalize_atexit() true false
+
+@deprecate Info(::Cint) Info() false
+@deprecate Info_set(info::Info,key::AbstractString,value::AbstractString) info[Symbol(key)] = value false
+@deprecate Info_get(info::Info,key::AbstractString) info[Symbol(key)] false
+@deprecate Info_delete(info::Info,key::AbstractString) delete!(info, Symbol(key)) false
+@deprecate Info_free(info::Info) free(info) false
+
+

src/mpi-base.jl

@@ -129,62 +129,7 @@ mutable struct Request
 end
 const REQUEST_NULL = Request(MPI_REQUEST_NULL, nothing)
 
-mutable struct Info
-    val::Cint
-    function Info()
-        newinfo = Ref{Cint}()
-        ccall(MPI_INFO_CREATE, Nothing, (Ptr{Cint}, Ref{Cint}), newinfo, 0)
-        info = new(newinfo[])        
-        refcount_inc()        
-        finalizer(info) do x
-            ccall(MPI_INFO_FREE, Nothing, (Ref{Cint}, Ref{Cint}), x.val, 0)
-            x.val = MPI_INFO_NULL
-            refcount_dec()
-        end
-        info
-    end
-
-    function Info(val::Cint)
-        if val != MPI_INFO_NULL
-            error("Info can only be created using Info()")
-        end
-        return new(MPI_INFO_NULL)
-    end
-end
-const INFO_NULL = Info(MPI_INFO_NULL)
-
-# the info functions assume that Fortran hidden arguments are placed at the end of the argument list
-function Info_set(info::Info,key::AbstractString,value::AbstractString)
-    @assert isascii(key) && isascii(value)
-    ccall(MPI_INFO_SET, Nothing,
-          (Ref{Cint}, Ptr{UInt8}, Ptr{UInt8}, Ref{Cint}, Csize_t, Csize_t),
-           info.val, key, value, 0, sizeof(key), sizeof(value))
-end
-
-function Info_get(info::Info,key::AbstractString)
-    @assert isascii(key)
-    keyexists=Ref{Bool}()
-    len=Ref{Cint}()
-    ccall(MPI_INFO_GET_VALUELEN, Nothing,
-          (Ref{Cint}, Ptr{UInt8}, Ptr{Cint}, Ptr{Bool}, Ref{Cint}, Csize_t),
-           info.val, key, len, keyexists, 0, sizeof(key))
-    if keyexists[]
-        value=" "^(len[])
-        ccall(MPI_INFO_GET, Nothing,
-              (Ref{Cint}, Ptr{UInt8}, Ptr{Cint}, Ptr{UInt8}, Ptr{Bool}, Ref{Cint}, Csize_t, Csize_t),
-               info.val, key, len, value, keyexists, 0, sizeof(key), sizeof(value))
-    else
-        value=""
-    end
-    value
-end
-
-function Info_delete(info::Info,key::AbstractString)
-    @assert isascii(key)
-    ccall(MPI_INFO_DELETE, Nothing,
-          (Ref{Cint}, Ptr{UInt8}, Ref{Cint}, Csize_t), info.val, key, 0, sizeof(key))
-end
-Info_free(info::Info) = finalize(info)
+include("mpi-info.jl")
 
 mutable struct Status
     val::Array{Cint,1}
@@ -310,10 +255,6 @@ function _Finalize()
     ccall(MPI_FINALIZE, Nothing, (Ref{Cint},), 0)
 end
 
-# to be deprecated
-const FINALIZE_ATEXIT = Ref(true)
-Base.@deprecate finalize_atexit() true
-
 """
     Abort(comm::Comm, errcode::Integer)
 
@@ -398,11 +339,11 @@ function Comm_split(comm::Comm,color::Integer,key::Integer)
     MPI.Comm(newcomm[])
 end
 
-function Comm_split_type(comm::Comm,split_type::Integer,key::Integer;info::Info=INFO_NULL)
+function Comm_split_type(comm::Comm,split_type::Integer,key::Integer; kwargs...)
     newcomm = Ref{Cint}()
     ccall(MPI_COMM_SPLIT_TYPE, Nothing,
           (Ref{Cint}, Ref{Cint}, Ref{Cint}, Ref{Cint}, Ptr{Cint}, Ref{Cint}),
-          comm.val, split_type, key, info.val, newcomm, 0)
+          comm.val, split_type, key, Info(kwargs...), newcomm, 0)
     MPI.Comm(newcomm[])
 end
 

src/mpi-info.jl

@@ -0,0 +1,157 @@
+"""
+    Info <: AbstractDict{Symbol,String}
+
+`MPI.Info` objects store key-value pairs, and are typically used for passing optional
+arguments to MPI functions.
+
+# Usage
+
+These will typically be hidden from user-facing APIs by splatting keywords, e.g.
+```julia
+function f(args...; kwargs...)
+    info = Info(kwargs...)
+    # pass `info` object to `ccall`
+end
+```
+
+For manual usage, `Info` objects act like Julia `Dict` objects:
+```julia
+info = Info(init=true) # keyword argument is required
+info[key] = value
+x = info[key]
+delete!(info, key)
+```
+
+If `init=false` is used in the costructor (the default), a "null" `Info` object will be
+returned: no keys can be added to such an object.
+"""
+mutable struct Info <: AbstractDict{Symbol,String}
+    val::Cint
+    function Info(;init=false)
+        info = new(MPI_INFO_NULL)
+        if init
+            ccall(MPI_INFO_CREATE, Nothing, (Ptr{Cint}, Ref{Cint}), info, 0)
+            refcount_inc()
+            finalizer(free, info)
+        end
+        return info
+    end
+end
+
+# allows us to pass Info objects directly into Ptr{Cint} ccall signatures
+function Base.unsafe_convert(::Type{Ptr{Cint}}, info::Info)
+    convert(Ptr{Cint}, pointer_from_objref(info))
+end
+
+function free(info::Info)
+    if info.val != MPI_INFO_NULL
+        ccall(MPI_INFO_FREE, Nothing, (Ptr{Cint}, Ref{Cint}), info, 0)
+        refcount_dec()
+    end
+    return nothing
+end
+
+const INFO_NULL = Info(init=false)
+
+# the info functions assume that Fortran hidden arguments are placed at the end of the argument list
+function Base.setindex!(info::Info, value::AbstractString, key::Symbol)
+    skey = String(key)
+    @assert isascii(skey) && isascii(value) &&
+        length(skey) <= MPI_MAX_INFO_KEY && length(value) <= MPI_MAX_INFO_VAL
+    ccall(MPI_INFO_SET, Nothing,
+          (Ptr{Cint}, Ptr{UInt8}, Ptr{UInt8}, Ref{Cint}, Csize_t, Csize_t),
+          info, skey, value, 0, sizeof(skey), sizeof(value))
+end
+
+Base.setindex!(info::Info, value::Any, key::Symbol) = info[key] = infoval(value)
+
+"""
+    infoval(x)
+
+Convert Julia object `x` to a string representation for storing in an [`Info`](@ref) object.
+
+The MPI specification allows passing strings, Boolean values, integers, and lists.
+"""
+infoval(x::String) = x
+infoval(x::Bool) = string(x) # "true"/"false"
+infoval(x::Integer) = string(x) # decimal values
+infoval(xs::AbstractVector) = join(map(infoval, xs), ',') # separated by commas
+infoval(xs::Tuple) = join(map(infoval, xs), ',') # separated by commas
+
+function Info(kvs::Pair...)
+    info = Info(;init=true)
+    for (k,v) in kvs
+        info[k] = v
+    end
+    return info
+end
+
+
+function Base.getindex(info::Info, key::Symbol)
+    skey = String(key)
+    @assert isascii(skey) && length(skey) <= MPI_MAX_INFO_KEY
+    keyexists = Ref{Cint}()
+    len       = Ref{Cint}()
+    ccall(MPI_INFO_GET_VALUELEN, Nothing,
+          (Ptr{Cint}, Ptr{UInt8}, Ptr{Cint}, Ptr{Cint}, Ref{Cint}, Csize_t),
+          info, skey, len, keyexists, 0, sizeof(skey))
+
+    if keyexists[] == 0
+        throw(KeyError(key))
+    end
+
+    buffer = Vector{UInt8}(undef, len[])
+    ccall(MPI_INFO_GET, Nothing,
+          (Ptr{Cint}, Ptr{UInt8}, Ptr{Cint}, Ptr{UInt8}, Ptr{Cint}, Ref{Cint}, Csize_t, Csize_t),
+          info, skey, len, buffer, keyexists, 0, sizeof(skey), sizeof(buffer))
+    return String(buffer)
+end
+
+function Base.delete!(info::Info,key::Symbol)
+    skey = String(key)
+    @assert isascii(skey) && length(skey) <= MPI_MAX_INFO_KEY
+    ccall(MPI_INFO_DELETE, Nothing,
+          (Ptr{Cint}, Ptr{UInt8}, Ref{Cint}, Csize_t),
+          info, skey, 0, sizeof(skey))
+end
+
+function Base.length(info::Info)
+    if info.val == MPI_INFO_NULL
+        return 0
+    end
+    nkeys = Ref{Cint}()
+    ccall(MPI_INFO_GET_NKEYS, Nothing,
+          (Ptr{Cint}, Ptr{Cint}, Ref{Cint}),
+          info, nkeys, 0)
+    return Int(nkeys[])
+end
+
+function nthkey(info::Info, n::Integer)
+    buffer = Vector{UInt8}(undef, MPI_MAX_INFO_KEY)
+    ccall(MPI_INFO_GET_NTHKEY, Nothing,
+          (Ptr{Cint}, Ref{Cint}, Ptr{UInt8}, Ref{Cint}, Csize_t),
+          info, n, buffer, 0, length(buffer))
+    i = findlast(!isequal(UInt8(' ')), buffer)
+    resize!(buffer, i)
+    Symbol(buffer)
+end
+
+function Base.iterate(infokeys::Base.KeySet{Symbol,Info}, i=0)
+    info = infokeys.dict
+    if i < length(info)
+        key = nthkey(info, i)
+        return key, i+1
+    else
+        return nothing
+    end
+end
+
+function Base.iterate(info::Info, i=0)
+    if i < length(info)
+        key = nthkey(info, i)
+        val = info[key]
+        return key=>val, i+1
+    else
+        return nothing
+    end
+end

src/win_mpiconstants.jl

@@ -32,6 +32,8 @@ const MPI_LOCK_EXCLUSIVE = Int32(234)
 const MPI_LOCK_SHARED = Int32(235)
 const MPI_LOR = Int32(1476395015)
 const MPI_LXOR = Int32(1476395017)
+const MPI_MAX_INFO_KEY = Int32(254)
+const MPI_MAX_INFO_VAL = Int32(1023)
 const MPI_MAX = Int32(1476395009)
 const MPI_MAXLOC = Int32(1476395020)
 const MPI_MIN = Int32(1476395010)
@@ -88,6 +90,8 @@ const MPI_INFO_CREATE = (:MPI_INFO_CREATE, libmpi)
 const MPI_INFO_DELETE = (:MPI_INFO_DELETE, libmpi)
 const MPI_INFO_FREE = (:MPI_INFO_FREE, libmpi)
 const MPI_INFO_GET = (:MPI_INFO_GET, libmpi)
+const MPI_INFO_GET_NKEYS = (:MPI_INFO_GET_NKEYS, libmpi)
+const MPI_INFO_GET_NTHKEY = (:MPI_INFO_GET_NTHKEY, libmpi)
 const MPI_INFO_GET_VALUELEN = (:MPI_INFO_GET_VALUELEN, libmpi)
 const MPI_INFO_SET = (:MPI_INFO_SET, libmpi)
 const MPI_INITIALIZED = (:MPI_INITIALIZED, libmpi)

test/test_info.jl

@@ -5,13 +5,23 @@ MPI.Init()
 
 info = MPI.Info()
 @test typeof(info) == MPI.Info
-@test info.val != MPI.Info
-MPI.Info_set(info, "foo", "fast")
-MPI.Info_set(info, "bar", "evenfaster")
-@test MPI.Info_get(info, "foo" ) == "fast"
-MPI.Info_delete(info, "bar")
-@test MPI.Info_get(info, "bar" ) == ""
-finalize(info)
+@test info.val == MPI.MPI_INFO_NULL
+
+testinfo(;kwargs...) = MPI.Info(kwargs...)
+
+info = testinfo(foo="fast", bar=true, baz=[10, -2])
+@test info.val != MPI.MPI_INFO_NULL
+
+@test length(info) == 3
+@test info[:foo] == "fast"
+
+@test sort!(collect(keys(info))) == [:bar, :baz, :foo]
+@test sort!(collect(info)) == [:bar=>"true", :baz=>"10,-2", :foo=>"fast"]
+
+delete!(info, :bar)
+@test_throws KeyError info[:bar]
+
+MPI.free(info)
 @test info.val == MPI.MPI_INFO_NULL
 
 MPI.Finalize()