Document external MPI initialization (#748)

* Document external MPI initialization
* Add newly documented functions to reference docs

docs/src/external.md

@@ -60,3 +60,11 @@ There are two typical solutions to this problem:
    end
    REFS[obj] = nothing
    ```
+
+## Externally initialized MPI
+
+When working with non-Julia libraries or tools, `MPI_Init` may be invoked in another part
+of the execution flow and not via MPI.jl's [`MPI.Init`](@ref) function. This leaves some
+package-internal settings uninitialized. In this case, you need to call
+[`MPI.run_init_hooks()`)(@ref) manually to fully initialize MPI.jl. You may also want to
+consider calling [`MPI.set_default_error_handler_return()`](@ref).

docs/src/reference/advanced.md

@@ -41,6 +41,7 @@ MPI.infoval
 MPI.Errhandler
 MPI.get_errorhandler
 MPI.set_errorhandler!
+MPI.set_default_error_handler_return
 ```
 
 ## Miscellaneous

docs/src/reference/environment.md

@@ -24,6 +24,7 @@ MPI.Initialized
 MPI.Finalize
 MPI.Finalized
 MPI.add_init_hook!
+MPI.run_init_hooks
 MPI.add_finalize_hook!
 ```
 

src/environment.jl

@@ -50,6 +50,16 @@ Register a function `f` that will be called as `f()` when `MPI.Init` is
 called. These are invoked in a first-in, first-out (FIFO) order.
 """
 add_init_hook!(f) = push!(mpi_init_hooks, f)
+
+"""
+    MPI.run_init_hooks()
+
+Execute all functions that have been registered using [`MPI.add_init_hook!()`](@ref).
+
+This function is executed automatically by [`MPI.Init()`](@ref) but *must* be invoked
+manually if MPI has been initialized externally by a direct call to `MPI_Init()`. It is safe
+to call this function multiple times (subsequent runs will be a no-op).
+"""
 function run_init_hooks()
     while !isempty(mpi_init_hooks)
         f = popfirst!(mpi_init_hooks) # FIFO

src/errhandler.jl

@@ -31,6 +31,16 @@ function free(errh::Errhandler)
     return nothing
 end
 
+"""
+    MPI.set_default_error_handler_return()
+
+Set the error handler for `MPI_COMM_SELF` and `MPI_COMM_WORLD` to `MPI_ERRORS_RETURN`. This
+will cause certain MPI errors to appear as Julia exceptions.
+
+This function is executed automatically by [`MPI.Init()`](@ref) but *may* be invoked
+manually if MPI has been initialized externally by a direct call to `MPI_Init()`. It is safe
+to call this function multiple times.
+"""
 function set_default_error_handler_return()
     set_errorhandler!(COMM_SELF, ERRORS_RETURN)
     set_errorhandler!(COMM_WORLD, ERRORS_RETURN)