Future doc (#31737)

Author: matbesancon

stdlib/Distributed/src/remotecall.jl

@@ -13,10 +13,12 @@ const client_refs = WeakKeyDict{Any, Nothing}() # used as a WeakKeySet
 abstract type AbstractRemoteRef end
 
 """
-    Future(pid::Integer=myid())
+    Future(w::Int, rrid::RRID, v::Union{Some, Nothing}=nothing)
 
-Create a `Future` on process `pid`.
-The default `pid` is the current process.
+A `Future` is a placeholder for a single computation
+of unknown termination status and time.
+For multiple potential computations, see `RemoteChannel`.
+See `remoteref_id` for identifying an `AbstractRemoteRef`.
 """
 mutable struct Future <: AbstractRemoteRef
     where::Int
@@ -98,9 +100,15 @@ function finalize_ref(r::AbstractRemoteRef)
     nothing
 end
 
+"""
+    Future(pid::Integer=myid())
+
+Create a `Future` on process `pid`.
+The default `pid` is the current process.
+"""
+Future(pid::Integer=myid()) = Future(pid, RRID())
 Future(w::LocalProcess) = Future(w.id)
 Future(w::Worker) = Future(w.id)
-Future(pid::Integer=myid()) = Future(pid, RRID())
 
 RemoteChannel(pid::Integer=myid()) = RemoteChannel{Channel{Any}}(pid, RRID())
 
@@ -177,9 +185,12 @@ If the argument `Future` is owned by a different node, this call will block to w
 It is recommended to wait for `rr` in a separate task instead
 or to use a local [`Channel`](@ref) as a proxy:
 
-    c = Channel(1)
-    @async put!(c, remotecall_fetch(long_computation, p))
-    isready(c)  # will not block
+```julia
+p = 1
+f = Future(p)
+@async put!(f, remotecall_fetch(long_computation, p))
+isready(f)  # will not block
+```
 """
 function isready(rr::Future)
     rr.v === nothing || return true
@@ -232,7 +243,7 @@ function del_clients(pairs::Vector)
     end
 end
 
-any_gc_flag = Condition()
+const any_gc_flag = Condition()
 function start_gc_msgs_task()
     @async while true
         wait(any_gc_flag)