add version errors (#602)

Author: simonbyrne

docs/src/reference/environment.md

@@ -24,3 +24,10 @@ MPI.Initialized
 MPI.Finalize
 MPI.Finalized
 ```
+
+## Errors
+
+```@docs
+MPI.MPIError
+MPI.FeatureLevelError
+```

lib/MPIPreferences/src/MPIPreferences.jl

@@ -41,13 +41,8 @@ else
     error("Unknown binary: $binary")
 end
 
-module System
-    export libmpi, mpiexec
-    using Preferences
-    const libmpi = @load_preference("libmpi")
-    const mpiexec_path = @load_preference("mpiexec")
-    mpiexec(;adjust_PATH=true, adjust_LIBPATH=true) = `$mpiexec_path`
-    mpiexec(f;adjust_PATH=true, adjust_LIBPATH=true) = f(`$mpiexec_path`)
+@static if binary == "system"
+    include("system.jl")
 end
 
 """

lib/MPIPreferences/src/system.jl

@@ -0,0 +1,13 @@
+module System
+    export libmpi, mpiexec
+    using Preferences, Libdl
+    const libmpi = @load_preference("libmpi")
+    const mpiexec_path = @load_preference("mpiexec")
+    mpiexec(;adjust_PATH=true, adjust_LIBPATH=true) = `$mpiexec_path`
+    mpiexec(f;adjust_PATH=true, adjust_LIBPATH=true) = f(`$mpiexec_path`)
+
+    libmpi_handle = C_NULL
+    function __init__()
+        global libmpi_handle = Libdl.dlopen(libmpi, Libdl.RTLD_LAZY | Libdl.RTLD_GLOBAL)
+    end
+end

src/MPI.jl

@@ -37,19 +37,19 @@ end
 import MPIPreferences
 
 if MPIPreferences.binary == "MPICH_jll"
-    import MPICH_jll: libmpi, mpiexec
+    import MPICH_jll: libmpi, libmpi_handle, mpiexec
     const libmpiconstants = nothing
 elseif MPIPreferences.binary == "OpenMPI_jll"
-    import OpenMPI_jll: libmpi, mpiexec
+    import OpenMPI_jll: libmpi, libmpi_handle, mpiexec
     const libmpiconstants = nothing
 elseif MPIPreferences.binary == "MicrosoftMPI_jll"
-    import MicrosoftMPI_jll: libmpi, mpiexec
+    import MicrosoftMPI_jll: libmpi, libmpi_handle, mpiexec
     const libmpiconstants = nothing
 elseif MPIPreferences.binary == "MPItrampoline_jll"
-    import MPItrampoline_jll: MPItrampoline_jll, libmpi, mpiexec
+    import MPItrampoline_jll: MPItrampoline_jll, libmpi, libmpi_handle, mpiexec
     const libmpiconstants = MPItrampoline_jll.libload_time_mpi_constants_path
 elseif MPIPreferences.binary == "system"
-    import MPIPreferences.System: libmpi, mpiexec
+    import MPIPreferences.System: libmpi, libmpi_handle, mpiexec
     const libmpiconstants = nothing
 else
     error("Unknown MPI binary: $(MPIPreferences.binary)")

src/error.jl

@@ -1,14 +1,43 @@
+"""
+    MPIError
+
+Error thrown when an MPI function returns an error code. The `code` field contains the MPI error code.
+"""
 struct MPIError <: Exception
     code::Cint
 end
+function Base.show(io::IO, err::MPIError)
+    print(io, "MPIError(", err.code, "): ", error_string(err))
+end
+
+"""
+    FeatureLevelError
+
+Error thrown if a feature is not implemented in the current MPI backend.
+"""
+struct FeatureLevelError <: Exception
+    function_name::Symbol
+    min_version::VersionNumber # minimal MPI version required for this feature to be available
+end
+function Base.show(io::IO, err::FeatureLevelError)
+    print(io, "FeatureLevelError($(err.function_name)): Minimum MPI version is $(err.min_version)")
+end
+
+macro mpichk(expr, min_version=nothing)
+    if !isnothing(min_version) && expr.args[2].head == :tuple
+        fn = expr.args[2].args[1].value
+        if isnothing(dlsym(libmpi_handle, fn; throw_error=false))
+            return quote
+                throw(FeatureLevelError($fn, $min_version))
+            end
+        end
+    end
 
-macro mpichk(expr)
     expr = macroexpand(@__MODULE__, :(@mpicall($expr)))
     # MPI_SUCCESS is defined to be 0
     :((errcode = $(esc(expr))) == 0 || throw(MPIError(errcode)))
 end
 
-
 function error_string(err::MPIError)
     len_ref = Ref{Cint}()
     str_buf = Vector{UInt8}(undef, Consts.MPI_MAX_ERROR_STRING)
@@ -18,7 +47,3 @@ function error_string(err::MPIError)
     resize!(str_buf, len_ref[])
     return String(str_buf)
 end
-
-function Base.show(io::IO, err::MPIError)
-    print(io, "MPIError(", err.code, "): ", error_string(err))
-end