Skip to content

Commit 8ae9dd5

Browse files
authored
Distributed: Update documentation for addprocs(...). (#44331)
1 parent 6850940 commit 8ae9dd5

File tree

1 file changed

+31
-30
lines changed

1 file changed

+31
-30
lines changed

stdlib/Distributed/src/managers.jl

Lines changed: 31 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -51,19 +51,30 @@ end
5151
"""
5252
addprocs(machines; tunnel=false, sshflags=\`\`, max_parallel=10, kwargs...) -> List of process identifiers
5353
54-
Add processes on remote machines via SSH. See `exename` to set the path to the `julia` installation on remote machines.
55-
56-
`machines` is a vector of machine specifications. Workers are started for each specification.
57-
58-
A machine specification is either a string `machine_spec` or a tuple - `(machine_spec, count)`.
59-
60-
`machine_spec` is a string of the form `[user@]host[:port] [bind_addr[:port]]`. `user`
61-
defaults to current user, `port` to the standard ssh port. If `[bind_addr[:port]]` is
62-
specified, other workers will connect to this worker at the specified `bind_addr` and
63-
`port`.
64-
65-
`count` is the number of workers to be launched on the specified host. If specified as
66-
`:auto` it will launch as many workers as the number of CPU threads on the specific host.
54+
Add worker processes on remote machines via SSH. Configuration is done with keyword
55+
arguments (see below). In particular, the `exename` keyword can be used to specify
56+
the path to the `julia` binary on the remote machine(s).
57+
58+
`machines` is a vector of "machine specifications" which are given as strings of
59+
the form `[user@]host[:port] [bind_addr[:port]]`. `user` defaults to current user and `port`
60+
to the standard SSH port. If `[bind_addr[:port]]` is specified, other workers will connect
61+
to this worker at the specified `bind_addr` and `port`.
62+
63+
It is possible to launch multiple processes on a remote host by using a tuple in the
64+
`machines` vector or the form `(machine_spec, count)`, where `count` is the number of
65+
workers to be launched on the specified host. Passing `:auto` as the worker count will
66+
launch as many workers as the number of CPU threads on the remote host.
67+
68+
Examples:
69+
```julia
70+
addprocs([
71+
"remote1", # one worker on 'remote1' logging in with the current username
72+
"user@remote2", # one worker on 'remote2' logging in with the 'user' username
73+
"user@remote3:2222", # specifying SSH port to '2222' for 'remote3'
74+
("user@remote4", 4), # launch 4 workers on 'remote4'
75+
("user@remote5", :auto), # launch as many workers as CPU threads on 'remote5'
76+
])
77+
```
6778
6879
Keyword arguments:
6980
@@ -430,26 +441,16 @@ struct LocalManager <: ClusterManager
430441
end
431442

432443
"""
433-
addprocs(; kwargs...) -> List of process identifiers
444+
addprocs(np::Integer=Sys.CPU_THREADS; restrict=true, kwargs...) -> List of process identifiers
434445
435-
Equivalent to `addprocs(Sys.CPU_THREADS; kwargs...)`
436-
437-
Note that workers do not run a `.julia/config/startup.jl` startup script, nor do they synchronize
438-
their global state (such as global variables, new method definitions, and loaded modules) with any
439-
of the other running processes.
440-
"""
441-
addprocs(; kwargs...) = addprocs(Sys.CPU_THREADS; kwargs...)
442-
443-
"""
444-
addprocs(np::Integer; restrict=true, kwargs...) -> List of process identifiers
446+
Launch `np` workers on the local host using the in-built `LocalManager`.
445447
446-
Launches workers using the in-built `LocalManager` which only launches workers on the
447-
local host. This can be used to take advantage of multiple cores. `addprocs(4)` will add 4
448-
processes on the local machine. If `restrict` is `true`, binding is restricted to
449-
`127.0.0.1`. Keyword args `dir`, `exename`, `exeflags`, `topology`, `lazy` and
450-
`enable_threaded_blas` have the same effect as documented for `addprocs(machines)`.
448+
*Keyword arguments:*
449+
- `restrict::Bool`: if `true` (default) binding is restricted to `127.0.0.1`.
450+
- `dir`, `exename`, `exeflags`, `topology`, `lazy`, `enable_threaded_blas`: same effect
451+
as for `SSHManager`, see documentation for [`addprocs(machines::AbstractVector)`](@ref).
451452
"""
452-
function addprocs(np::Integer; restrict=true, kwargs...)
453+
function addprocs(np::Integer=Sys.CPU_THREADS; restrict=true, kwargs...)
453454
manager = LocalManager(np, restrict)
454455
check_addprocs_args(manager, kwargs)
455456
addprocs(manager; kwargs...)

0 commit comments

Comments
 (0)