Implemented Futures

base/docs/helpdb.jl

@@ -1155,18 +1155,29 @@ Return a tuple `(I, J, V)` where `I` and `J` are the row and column indexes of t
 findnz
 
 doc"""
-    RemoteRef()
+    RemoteChannel()
 
-Make an uninitialized remote reference on the local machine.
+Make an reference to a `Channel{Any}(1)` on the local machine.
 """
-RemoteRef()
+RemoteChannel()
 
 doc"""
-    RemoteRef(n)
+    RemoteChannel(n)
 
-Make an uninitialized remote reference on process `n`.
+Make an reference to a `Channel{Any}(1)` on process `n`.
 """
-RemoteRef(::Integer)
+RemoteChannel(::Integer)
+
+doc"""
+    RemoteChannel(f::Function, pid)
+
+Create references to remote channels of a specific size and type. `f()` is a function that when
+executed on `pid` must return an implementation of an `AbstractChannel`.
+
+For example, `RemoteChannel(()->Channel{Int}(10), pid)`, will return a reference to a channel of type `Int`
+and size 10 on `pid`.
+"""
+RemoteChannel(f::Function, pid)
 
 doc"""
 ```rst
@@ -2468,7 +2479,7 @@ display
 doc"""
     @spawnat
 
-Accepts two arguments, `p` and an expression. A closure is created around the expression and run asynchronously on process `p`. Returns a `RemoteRef` to the result.
+Accepts two arguments, `p` and an expression. A closure is created around the expression and run asynchronously on process `p`. Returns a `Future` to the result.
 """
 :@spawnat
 
@@ -4840,11 +4851,11 @@ Optional argument `msg` is a descriptive error string.
 DimensionMismatch
 
 doc"""
-    take!(RemoteRef)
+    take!(RemoteChannel)
 
-Fetch the value of a remote reference, removing it so that the reference is empty again.
+Fetch a value from a remote channel, also removing it in the processs.
 """
-take!(::RemoteRef)
+take!(::RemoteChannel)
 
 doc"""
     take!(Channel)
@@ -6639,7 +6650,8 @@ doc"""
 Block the current task until some event occurs, depending on the type
 of the argument:
 
-* `RemoteRef`: Wait for a value to become available for the specified remote reference.
+* `RemoteChannel` : Wait for a value to become available on the specified remote channel.
+* `Future` : Wait for a value to become available for the specified future.
 * `Channel`: Wait for a value to be appended to the channel.
 * `Condition`: Wait for `notify` on a condition.
 * `Process`: Wait for a process or process chain to exit. The `exitcode` field of a process can be used to determine success or failure.
@@ -7029,17 +7041,25 @@ Return the minimum of the arguments. Operates elementwise over arrays.
 min
 
 doc"""
-    isready(r::RemoteRef)
+    isready(r::RemoteChannel)
 
-Determine whether a `RemoteRef` has a value stored to it. Note that this function can cause race conditions, since by the time you receive its result it may no longer be true. It is recommended that this function only be used on a `RemoteRef` that is assigned once.
+Determine whether a `RemoteChannel` has a value stored to it. Note that this function can cause race conditions, since by the time you receive its result it may no longer be true.
+However, it can be safely used on a `Future` since they are assigned only once.
+"""
+isready
 
-If the argument `RemoteRef` is owned by a different node, this call will block to wait for the answer. It is recommended to wait for `r` in a separate task instead, or to use a local `RemoteRef` as a proxy:
+doc"""
+    isready(r::Future)
 
-    rr = RemoteRef()
-    @async put!(rr, remotecall_fetch(long_computation, p))
-    isready(rr)  # will not block
+Determine whether a `Future` has a value stored to it.
+
+If the argument `Future` is owned by a different node, this call will block to wait for the answer. It is recommended to wait for `r` in a separate task instead, or to use a local `Channel` as a proxy:
+
+    c = Channel(1)
+    @async put!(c, remotecall_fetch(long_computation, p))
+    isready(c)  # will not block
 """
-isready
+    isready(r::Future)
 
 doc"""
     InexactError()
@@ -8109,11 +8129,19 @@ An iterator that cycles through `iter` forever.
 cycle
 
 doc"""
-    put!(RemoteRef, value)
+    put!(RemoteChannel, value)
+
+Store a value to the remote channel. If the channel is full, blocks until space is available. Returns its first argument.
+"""
+put!(::RemoteChannel, value)
+
+doc"""
+    put!(Future, value)
 
-Store a value to a remote reference. Implements "shared queue of length 1" semantics: if a value is already present, blocks until the value is removed with `take!`. Returns its first argument.
+Store a value to a future. Future's are write-once remote references. A `put!` on an already set `Future` throws an Exception.
+All asynchronous remote calls return `Future`s and set the value to the return value of the call upon completion.
 """
-put!(::RemoteRef, value)
+put!(::Future, value)
 
 doc"""
     put!(Channel, value)
@@ -8860,7 +8888,7 @@ Base.(:(!=))
 doc"""
     @spawn
 
-Creates a closure around an expression and runs it on an automatically-chosen process, returning a `RemoteRef` to the result.
+Creates a closure around an expression and runs it on an automatically-chosen process, returning a `Future` to the result.
 """
 :@spawn
 
@@ -9114,7 +9142,7 @@ readavailable
 doc"""
     remotecall(func, id, args...)
 
-Call a function asynchronously on the given arguments on the specified process. Returns a `RemoteRef`.
+Call a function asynchronously on the given arguments on the specified process. Returns a `Future`.
 """
 remotecall
 
@@ -9510,7 +9538,10 @@ doc"""
 
 Waits and fetches a value from `x` depending on the type of `x`. Does not remove the item fetched:
 
-* `RemoteRef`: Wait for and get the value of a remote reference. If the remote value is an exception, throws a `RemoteException` which captures the remote exception and backtrace.
+* `Future`: Wait for and get the value of a Future. The fetched value is cached locally. Further calls to `fetch` on the same reference
+returns the cached value.
+If the remote value is an exception, throws a `RemoteException` which captures the remote exception and backtrace.
+* `RemoteChannel`: Wait for and get the value of a remote reference. Exceptions raised are same as for a `Future` .
 * `Channel` : Wait for and get the first available item from the channel.
 """
 fetch

base/exports.jl

@@ -61,6 +61,7 @@ export
     FileOffset,
     Filter,
     FloatRange,
+    Future,
     Hermitian,
     UniformScaling,
     InsertionSort,
@@ -87,7 +88,7 @@ export
     Rational,
     Regex,
     RegexMatch,
-    RemoteRef,
+    RemoteChannel,
     RepString,
     RevString,
     RoundFromZero,