More docs cleanup

mmesiti · Dec 22, 2019 · ef5cfee · ef5cfee
1 parent 1d55b4c
commit ef5cfee
Show file tree

Hide file tree

Showing 14 changed files with 108 additions and 101 deletions.
diff --git 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
@@ -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
@@ -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
diff --git a/docs/src/onesided.md 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
@@ -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!
-```
+```
diff --git a/docs/src/refindex.md b/docs/src/refindex.md
@@ -0,0 +1,4 @@
+# Index
+
+```@index
+```
diff --git a/docs/src/topology.md b/docs/src/topology.md
@@ -0,0 +1,6 @@
+# Topology
+
+```@docs
+MPI.Cartdim_get
+MPI.Cart_get
+```
diff --git 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
@@ -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
@@ -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
@@ -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 → src/onesided.jl b/src/window.jl → src/onesided.jl
diff --git a/src/operators.jl b/src/operators.jl
@@ -1,15 +1,21 @@
 """
     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
 
     Op(op, T=Any; iscommutative=false)
 
 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