From ef5cfee5ac9a7e789e177dfbd3c16a182beacf15 Mon Sep 17 00:00:00 2001 From: Simon Byrne Date: Sat, 21 Dec 2019 21:16:04 -0800 Subject: [PATCH] More docs cleanup --- docs/make.jl | 9 ++-- docs/src/advanced.md | 30 ++++++++++++++ docs/src/environment.md | 3 +- docs/src/functions.md | 75 ---------------------------------- docs/src/onesided.md | 7 ++++ docs/src/pointtopoint.md | 21 ++++++---- docs/src/refindex.md | 4 ++ docs/src/topology.md | 6 +++ src/MPI.jl | 2 +- src/collective.jl | 8 +++- src/datatypes.jl | 25 ++++++++---- src/handle.jl | 9 ++++ src/{window.jl => onesided.jl} | 0 src/operators.jl | 10 ++++- 14 files changed, 108 insertions(+), 101 deletions(-) create mode 100644 docs/src/advanced.md delete mode 100644 docs/src/functions.md create mode 100644 docs/src/onesided.md create mode 100644 docs/src/refindex.md create mode 100644 docs/src/topology.md rename src/{window.jl => onesided.jl} (100%) diff --git a/docs/make.jl b/docs/make.jl index b680ecf4b..9383badbc 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -50,9 +50,12 @@ makedocs( "comm.md", "pointtopoint.md", "collective.md", - ], - "functions.md", - ] + "onesided.md", + "topology.md", + "advanced.md", + ], + "refindex.md", + ] ) deploydocs( diff --git a/docs/src/advanced.md b/docs/src/advanced.md new file mode 100644 index 000000000..2b56ffcd5 --- /dev/null +++ b/docs/src/advanced.md @@ -0,0 +1,30 @@ +# Advanced + +## Object handling + +```@docs +MPI.free +MPI.refcount_inc +MPI.refcount_dec +``` + +## Datatype objects + +```@docs +MPI.mpitype +MPI.Type_Create_Subarray +``` + +## Operator objects + +```@docs +MPI.Op +``` + +## Info objects + +```@docs +MPI.Info +MPI.infoval +``` + diff --git a/docs/src/environment.md b/docs/src/environment.md index c09b4f2ac..d0d0d742b 100644 --- a/docs/src/environment.md +++ b/docs/src/environment.md @@ -8,8 +8,7 @@ MPI.Init MPI.Initialized MPI.Finalize MPI.Finalized -MPI.refcount_inc -MPI.refcount_dec +MPI.universe_size ``` diff --git a/docs/src/functions.md b/docs/src/functions.md deleted file mode 100644 index dacb4b741..000000000 --- a/docs/src/functions.md +++ /dev/null @@ -1,75 +0,0 @@ -# Function reference - -The following functions are currently wrapped, with the convention: `MPI_Fun => MPI.Fun` - -Constants like `MPI_SUM` are wrapped as `MPI.SUM`. Note also that -arbitrary Julia functions `f(x,y)` can be passed as reduction operations -to the MPI `Allreduce` and `Reduce` functions. - -## Datatype functions - -Julia Function (assuming `import MPI`) | C Function ----------------------------------------|-------------------------------------------------------- - [`MPI.Get_address`](@ref) | [`MPI_Get_address`](https://www.open-mpi.org/doc/v3.0/man3/MPI_Get_address.3.php) - [`MPI.mpitype`](@ref) | [`MPI_Type_create_struct`](https://www.open-mpi.org/doc/v1.10/man3/MPI_Type_create_struct.3.php)/[`MPI_Type_commit`](https://www.open-mpi.org/doc/v1.10/man3/MPI_Type_commit.3.php) - -!!! note - `mpitype` is not strictly a wrapper for - `MPI_Type_create_struct` and `MPI_Type_commit`, it also is an accessor for - previously created types. - - -```@docs -MPI.Get_address -MPI.mpitype -``` - -## One-sided communication - -Julia Function (assuming `import MPI`) | C Function ----------------------------------------|-------------------------------------------------------- - [`MPI.Win_create`](@ref) | [`MPI_Win_create`](https://www.open-mpi.org/doc/v3.0/man3/MPI_Win_create.3.php) - [`MPI.Win_create_dynamic`](@ref) | [`MPI_Win_create_dynamic`](https://www.open-mpi.org/doc/v3.0/man3/MPI_Win_create_dynamic.3.php) - [`MPI.Win_allocate_shared`](@ref) | [`MPI_Win_allocate_shared`](https://www.open-mpi.org/doc/v3.0/man3/MPI_Win_allocate_shared.3.php) - [`MPI.Win_shared_query`](@ref) | [`MPI_Win_shared_query`](https://www.open-mpi.org/doc/v3.0/man3/MPI_Win_shared_query.3.php) - [`MPI.Win_attach`](@ref) | [`MPI_Win_attach`](https://www.open-mpi.org/doc/v3.0/man3/MPI_Win_attach.3.php) - [`MPI.Win_detach`](@ref) | [`MPI_Win_detach`](https://www.open-mpi.org/doc/v3.0/man3/MPI_Win_detach.3.php) - [`MPI.Win_fence`](@ref) | [`MPI_Win_fence`](https://www.open-mpi.org/doc/v3.0/man3/MPI_Win_fence.3.php) - [`MPI.Win_flush`](@ref) | [`MPI_Win_flush`](https://www.open-mpi.org/doc/v3.0/man3/MPI_Win_flush.3.php) - [`MPI.Win_free`](@ref) | [`MPI_Win_free`](https://www.open-mpi.org/doc/v3.0/man3/MPI_Win_free.3.php) - [`MPI.Win_sync`](@ref) | [`MPI_Win_sync`](https://www.open-mpi.org/doc/v3.0/man3/MPI_Win_sync.3.php) - [`MPI.Win_lock`](@ref) | [`MPI_Win_lock`](https://www.open-mpi.org/doc/v3.0/man3/MPI_Win_lock.3.php) - [`MPI.Win_unlock`](@ref) | [`MPI_Win_unlock`](https://www.open-mpi.org/doc/v3.0/man3/MPI_Win_unlock.3.php) - [`MPI.Get`](@ref) | [`MPI_Get`](https://www.open-mpi.org/doc/v3.0/man3/MPI_Get.3.php) - [`MPI.Put`](@ref) | [`MPI_Put`](https://www.open-mpi.org/doc/v3.0/man3/MPI_Put.3.php) - [`MPI.Fetch_and_op`](@ref) | [`MPI_Fetch_and_op`](https://www.open-mpi.org/doc/v3.0/man3/MPI_Fetch_and_op.3.php) - [`MPI.Accumulate`](@ref) | [`MPI_Accumulate`](https://www.open-mpi.org/doc/v3.0/man3/MPI_Accumulate.3.php) - [`MPI.Get_accumulate`](@ref) | [`MPI_Get_accumulate`](https://www.open-mpi.org/doc/v3.0/man3/MPI_Get_accumulate.3.php) - - -```@docs -MPI.Win_create -MPI.Win_create_dynamic -MPI.Win_allocate_shared -MPI.Win_shared_query -MPI.Win_attach -MPI.Win_detach -MPI.Win_fence -MPI.Win_flush -MPI.Win_free -MPI.Win_sync -MPI.Win_lock -MPI.Win_unlock -MPI.Get -MPI.Put -MPI.Fetch_and_op -MPI.Accumulate -MPI.Get_accumulate -``` - -# Info objects - -```@docs -MPI.Info -MPI.infoval -``` diff --git a/docs/src/onesided.md b/docs/src/onesided.md new file mode 100644 index 000000000..2047b0c01 --- /dev/null +++ b/docs/src/onesided.md @@ -0,0 +1,7 @@ +# One-sided communication + +```@docs +MPI.Win_create +MPI.Win_create_dynamic +MPI.Win_allocate_shared +``` diff --git a/docs/src/pointtopoint.md b/docs/src/pointtopoint.md index 8362a49f9..dcee69db2 100644 --- a/docs/src/pointtopoint.md +++ b/docs/src/pointtopoint.md @@ -7,15 +7,13 @@ MPI.Request MPI.Status ``` -## Functions - -### Accessor +### Accessors ```@docs MPI.Get_count ``` -### Blocking +## Blocking communication ```@docs MPI.Send @@ -26,12 +24,19 @@ MPI.recv MPI.Sendrecv! ``` -### Non-blocking +## Non-blocking communication + +### Initiation ```@docs MPI.Isend MPI.isend MPI.Irecv! +``` + +### Completion + +```@docs MPI.Test! MPI.Testall! MPI.Testany! @@ -42,10 +47,10 @@ MPI.Waitany! MPI.Waitsome! ``` -### Probe and cancel +### Probe/Cancel ```@docs +MPI.Cancel! MPI.Iprobe MPI.Probe -MPI.Cancel! -``` +``` \ No newline at end of file diff --git a/docs/src/refindex.md b/docs/src/refindex.md new file mode 100644 index 000000000..93896448e --- /dev/null +++ b/docs/src/refindex.md @@ -0,0 +1,4 @@ +# Index + +```@index +``` \ No newline at end of file diff --git a/docs/src/topology.md b/docs/src/topology.md new file mode 100644 index 000000000..754109df3 --- /dev/null +++ b/docs/src/topology.md @@ -0,0 +1,6 @@ +# Topology + +```@docs +MPI.Cartdim_get +MPI.Cart_get +``` \ No newline at end of file diff --git a/src/MPI.jl b/src/MPI.jl index 1bb1dcf11..5d9802837 100644 --- a/src/MPI.jl +++ b/src/MPI.jl @@ -47,7 +47,7 @@ include("operators.jl") include("pointtopoint.jl") include("collective.jl") include("topology.jl") -include("window.jl") +include("onesided.jl") include("deprecated.jl") diff --git a/src/collective.jl b/src/collective.jl index 8a05f3f1d..114911251 100644 --- a/src/collective.jl +++ b/src/collective.jl @@ -684,7 +684,7 @@ If only one `sendrecvbuf` buffer is provided, then the operation is performed in # See also - [`Allreduce`](@ref), to handle allocation of the output buffer. -- [`Reduce!`](@ref)/[`Rreduce`](@ref) to send reduction to a single rank. +- [`Reduce!`](@ref)/[`Reduce`](@ref) to send reduction to a single rank. - [`Op`](@ref) for details on reduction operators. # External links @@ -726,7 +726,7 @@ the result in the `recvbuf` of all processes in the group. # See also - [`Allreduce!`](@ref) for mutating or in-place operations. -- [`Reduce!`](@ref)/[`Rreduce`](@ref) to send reduction to a single rank. +- [`Reduce!`](@ref)/[`Reduce`](@ref) to send reduction to a single rank. - [`Op`](@ref) for details on reduction operators. # External links @@ -754,6 +754,7 @@ If only a single buffer is provided, then operations will be performed in-place # See also - [`Scan`](@ref) to handle allocation of the output buffer - [`Exscan!`](@ref)/[`Exscan`](@ref) for exclusive scan +- [`Op`](@ref) for details on reduction operators. # External links $(_doc_external("MPI_Scan")) @@ -796,6 +797,7 @@ type. # See also - [`Scan!`](@ref) for mutating or in-place operations - [`Exscan!`](@ref)/[`Exscan`](@ref) for exclusive scan +- [`Op`](@ref) for details on reduction operators. # External links $(_doc_external("MPI_Scan")) @@ -826,6 +828,7 @@ rank 0 will remain unchanged. # See also - [`Exscan`](@ref) to handle allocation of the output buffer - [`Scan!`](@ref)/[`Scan`](@ref) for inclusive scan +- [`Op`](@ref) for details on reduction operators. # External links $(_doc_external("MPI_Exscan")) @@ -868,6 +871,7 @@ of `sendbuf` on rank `0`. # See also - [`Exscan!`](@ref) for mutating and in-place operations - [`Scan!`](@ref)/[`Scan`](@ref) for inclusive scan +- [`Op`](@ref) for details on reduction operators. # External links $(_doc_external("MPI_Scan")) diff --git a/src/datatypes.jl b/src/datatypes.jl index f56b48b48..315105751 100644 --- a/src/datatypes.jl +++ b/src/datatypes.jl @@ -3,6 +3,16 @@ const DATATYPE_NULL = _Datatype(MPI_DATATYPE_NULL) Datatype() = Datatype(DATATYPE_NULL.val) +function free(dt::Datatype) + if dt.val != DATATYPE_NULL.val + @mpichk ccall((:MPI_Datatype_free, libmpi), Cint, (Ptr{MPI_Datatype},), dt) + refcount_dec() + end + return nothing +end + + + macro assert_minlength(buffer, count) quote if $(esc(buffer)) isa AbstractArray @@ -40,12 +50,13 @@ end fieldoffsets(::Type{T}) where {T} = Int[fieldoffset(T, i) for i in 1:length(fieldnames(T))] -# Define a function mpitype(T) that returns the MPI datatype code for -# a given type T. In the case the the type does not exist, it is created and -# then returned. The dictonary is defined in __init__ so the module can be -# precompiled +""" + mpitype(T) -# accessor and creation function for getting MPI datatypes +Returns the MPI `Datatype` code for a given type `T`. In the case the the type does not +exist, it is created and then returned. The dictonary is defined in `__init__` so the +module can be precompiled +""" function mpitype(::Type{T}) where T get!(mpitype_dict, T) do if !isbitstype(T) @@ -174,9 +185,7 @@ function Type_Commit!(newtype::Datatype) end -""" - Setter function for mpitype_dict and mpitype_dict_inverse -""" +# Setter function for mpitype_dict and mpitype_dict_inverse function recordDataType(T::DataType, mpiT::MPI_Datatype) if !haskey(mpitype_dict, T) diff --git a/src/handle.jl b/src/handle.jl index 556985035..a829b5f0b 100644 --- a/src/handle.jl +++ b/src/handle.jl @@ -33,3 +33,12 @@ macro mpi_handle(def, extrafields...) end end end + + +""" + MPI.free(obj) + +Free the MPI object handle `obj`. This is typically used as the finalizer, and so need not be called directly unless otherwise noted. +""" +function free +end diff --git a/src/window.jl b/src/onesided.jl similarity index 100% rename from src/window.jl rename to src/onesided.jl diff --git a/src/operators.jl b/src/operators.jl index 60d8d22cf..88ee80a65 100644 --- a/src/operators.jl +++ b/src/operators.jl @@ -1,8 +1,7 @@ """ Op -An MPI reduction operator, for use with [`Reduce!`](@ref)/[`Reduce`](@ref), -[`Reduce_in_place!`](@ref), [`Allreduce!`](@ref)/[`Allreduce`](@ref), [`Scan`](@ref) or [`Exscan`](@ref). +An MPI reduction operator, for use with [Reduce/Scan collective operations](@ref Reduce/Scan) to wrap binary operators. MPI.jl will perform this conversion automatically. ## Usage @@ -10,6 +9,13 @@ An MPI reduction operator, for use with [`Reduce!`](@ref)/[`Reduce`](@ref), Wrap the Julia reduction function `op` for arguments of type `T`. `op` is assumed to be associative, and if `iscommutative` is true, assumed to be commutative as well. + +## See also + +- [`Reduce!`](@ref)/[`Reduce`](@ref) +- [`Allreduce!`](@ref)/[`Allreduce`](@ref) +- [`Scan!`](@ref)/[`Scan`](@ref) +- [`Exscan!`](@ref)/[`Exscan`](@ref) """ @mpi_handle Op fptr