Deprecation leading into v0.8 (#4)

* deprecate exports

* deprecate showprogress

* fix docstrings, deprecate nelements(ps, dim)

Author: jishnub

docs/src/index.md

@@ -5,5 +5,5 @@ CurrentModule = ParallelUtilities
 # ParallelUtilities.jl
 
 ```@autodocs
-Modules = [ParallelUtilities]
+Modules = [ParallelUtilities, ParallelUtilities.ClusterQueryUtils]
 ```

src/ParallelUtilities.jl

@@ -1,31 +1,32 @@
 module ParallelUtilities
 using ProgressMeter
-using DataStructures
 using Reexport
 using OffsetArrays
+
 @reexport using Distributed
 
-export  ProductSplit,
-	ntasks,
-	whichproc,
-	procrange_recast,
-	localindex,
-	whichproc_localindex,
-	extremadims,
-	extrema_commonlastdim,
-	nodenames,
-	gethostnames,
-	nprocs_node,
-	pmapbatch,
-	pmapbatch_elementwise,
-	pmapsum,
-	pmapsum_elementwise,
-	pmapreduce,
-	pmapreduce_commutative,
-	pmapreduce_commutative_elementwise
+export ProductSplit,
+    ntasks,
+    whichproc,
+    procrange_recast,
+    localindex,
+    whichproc_localindex,
+    extremadims,
+    extrema_commonlastdim,
+    pmapbatch,
+    pmapbatch_elementwise,
+    pmapsum,
+    pmapsum_elementwise,
+    pmapreduce,
+    pmapreduce_commutative,
+    pmapreduce_commutative_elementwise
 
 include("errors.jl")
 include("productsplit.jl")
+
+include("clusterquery.jl")
+@reexport using .ClusterQueryUtils
+
 include("utils.jl")
 include("trees.jl")
 include("mapreduce.jl")

src/clusterquery.jl

@@ -0,0 +1,105 @@
+module ClusterQueryUtils
+
+using Distributed
+using DataStructures
+
+@deprecate gethostnames hostnames
+export hostnames
+export nodenames
+export procs_node
+export nprocs_node
+
+"""
+    gethostnames(procs = workers())
+
+Return the hostname of each worker in `procs`. This is obtained by evaluating 
+`Libc.gethostname()` on each worker asynchronously.
+
+!!! warn
+    `gethostnames` is deprecated in favor of `hostnames`    
+"""
+gethostnames
+
+"""
+    hostnames(procs = workers())
+
+Return the hostname of each worker in `procs`. This is obtained by evaluating 
+`Libc.gethostname()` on each worker asynchronously.
+"""
+function hostnames(procs = workers())
+    Base.depwarn("hostnames will not be exported in a future release. "*
+    "It may be imported from the module ClusterQueryUtils", :hostnames)
+
+    hostnames = Vector{String}(undef, length(procs))
+
+    @sync for (ind,p) in enumerate(procs)
+        @async hostnames[ind] = @fetchfrom p Libc.gethostname()
+    end
+    return hostnames
+end
+
+
+"""
+    nodenames(procs = workers())
+
+Return the unique hostnames that the workers in `procs` lie on. 
+On an HPC system these are usually the hostnames of the nodes involved.
+"""
+nodenames(procs = workers()) = nodenames(hostnames(procs))
+
+function nodenames(hostnames::AbstractVector{String})
+   Base.depwarn("nodenames will not be exported in a future release. "*
+    "It may be imported from the module ClusterQueryUtils", :nodenames)
+    
+    unique(hostnames)
+end
+
+"""
+    procs_node(procs = workers())
+
+Return the worker ids on each host of the cluster.
+On an HPC system this would return the workers on each node.
+"""
+function procs_node(procs = workers())
+    hosts = hostnames(procs)
+    nodes = nodenames(hosts)
+    procs_node(procs, hosts, nodes)
+end
+
+function procs_node(procs, hosts, nodes)
+    Base.depwarn("procs_node will not be exported in a future release. "*
+        "It may be imported from the module ClusterQueryUtils", :procs_node)
+    
+    OrderedDict(node => procs[findall(isequal(node),hosts)] for node in nodes)
+end
+
+"""
+    nprocs_node(procs = workers())
+
+Return the number of workers on each host.
+On an HPC system this would return the number of workers on each node.
+"""
+function nprocs_node(procs = workers())
+    nprocs_node(hostnames(procs))
+end
+
+function nprocs_node(hostnames::AbstractVector{String})
+    nodes = nodenames(hostnames)
+    nprocs_node(hostnames, nodes)
+end
+
+function nprocs_node(hostnames::AbstractVector, nodes::AbstractVector)
+    Base.depwarn("nprocs_node will not be exported in a future release. "*
+        "It may be imported from the module ClusterQueryUtils", :nprocs_node)
+
+    OrderedDict(node => count(isequal(node), hostnames) for node in nodes)
+end
+
+function nprocs_node(d::AbstractDict)
+    Base.depwarn("nprocs_node will not be exported in a future release. "*
+        "It may be imported from the module ClusterQueryUtils", :nprocs_node)
+
+    OrderedDict(node => length(procs) for (node, procs) in d)
+end
+
+end