Skip to content

Commit

Permalink
generated parallel.rst
Browse files Browse the repository at this point in the history
  • Loading branch information
@amitmurthy
amitmurthy committed Nov 12, 2015
1 parent 66fbab6 commit 49f8580
Show file tree
Hide file tree
Showing 2 changed files with 15 additions and 51 deletions.
16 changes: 8 additions & 8 deletions doc/manual/parallel-computing.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -499,15 +499,15 @@ the backing store on the remote process.
example of this is provided in ``examples/dictchannel.jl`` which uses a dictionary as its remote store.


Remote References and Distrubuted Garbage Collection
Remote References and Distributed Garbage Collection
----------------------------------------------------

Objects referred to by remote references can be freed only when *all* held references in the cluster
are deleted.

The node where the value is stored keeps tracks of which of the workers have a reference to it.
Everytime a ``RemoteChannel`` or a (unfetched) ``Future`` is serialized to a worker, the node pointed
to by the reference is notified. And everytime a ``RemoteChannel`` or a (unfetched) ``Future``
The node where the value is stored keeps track of which of the workers have a reference to it.
Every time a ``RemoteChannel`` or a (unfetched) ``Future`` is serialized to a worker, the node pointed
to by the reference is notified. And every time a ``RemoteChannel`` or a (unfetched) ``Future``
is garbage collected locally, the node owning the value is again notified.

The notifications are done via sending of "tracking" messages - an "add reference" message when
Expand All @@ -525,11 +525,11 @@ since the original remote store may have collected the value by this time.
It is important to note that *when* an object is locally garbage collected is dependent
upon the size of the object and the current memory pressure in the system.

In case of remote references, the size of the local reference object is quite small, while the remote value
stored on the remote node may be quite large. Since the local object may not be colected immediately, it is
a good practice to explictly call ``finalize`` on local instances of a ``RemoteChannel``, or on unfetched
In case of remote references, the size of the local reference object is quite small, while the value
stored on the remote node may be quite large. Since the local object may not be collected immediately, it is
a good practice to explicitly call ``finalize`` on local instances of a ``RemoteChannel``, or on unfetched
``Future``\ s. Since calling ``fetch`` on a ``Future`` also removes its reference from the remote store, this
is not required on fetched ``Future``\ s. Explicitly calling ``finalize`` immediately sends a message to
is not required on fetched ``Future``\ s. Explicitly calling ``finalize`` results in an immediate message sent to
the remote node to go ahead and remove its reference to the value.


Expand Down
50 changes: 7 additions & 43 deletions doc/stdlib/parallel.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -268,15 +268,16 @@ General Parallel Computing Support

.. Docstring generated from Julia source
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``\ .

.. function:: wait([x])

.. Docstring generated from Julia source
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.
Expand All @@ -293,7 +294,8 @@ General Parallel Computing Support
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.

.. function:: remotecall_wait(func, id, args...)
Expand All @@ -308,44 +310,18 @@ General Parallel Computing Support
Perform ``fetch(remotecall(...))`` in one message. Any remote exceptions are captured in a ``RemoteException`` and thrown.

.. function:: put!(RemoteRef, value)

.. Docstring generated from Julia source
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.

.. function:: put!(Channel, value)

.. Docstring generated from Julia source
Appends an item to the channel. Blocks if the channel is full.

.. function:: take!(RemoteRef)

.. Docstring generated from Julia source
Fetch the value of a remote reference, removing it so that the reference is empty again.

.. function:: take!(Channel)

.. Docstring generated from Julia source
Removes and returns a value from a ``Channel``\ . Blocks till data is available.

.. function:: isready(r::RemoteRef)

.. Docstring generated from Julia source
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.

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:

.. code-block:: julia
rr = RemoteRef()
@async put!(rr, remotecall_fetch(long_computation, p))
isready(rr) # will not block
.. function:: close(Channel)

.. Docstring generated from Julia source
Expand All @@ -355,18 +331,6 @@ General Parallel Computing Support
* ``put!`` on a closed channel.
* ``take!`` and ``fetch`` on an empty, closed channel.

.. function:: RemoteRef()

.. Docstring generated from Julia source
Make an uninitialized remote reference on the local machine.

.. function:: RemoteRef(n)

.. Docstring generated from Julia source
Make an uninitialized remote reference on process ``n``\ .

.. function:: timedwait(testcb::Function, secs::Float64; pollint::Float64=0.1)

.. Docstring generated from Julia source
Expand All @@ -377,13 +341,13 @@ General Parallel Computing Support

.. Docstring generated from Julia source
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.

.. function:: @spawnat

.. Docstring generated from Julia source
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.

.. function:: @fetch

Expand Down

0 comments on commit 49f8580

Please sign in to comment.