changeset 729:cade54734d47

Moved documentation of program counter attribute.
author Martin Geisler <mg@daimi.au.dk>
date Thu, 24 Apr 2008 14:40:09 +0200
parents fa33d8c71256
children 1e9b0d1ad897
files doc/runtime.txt viff/runtime.py
diffstat 2 files changed, 43 insertions(+), 40 deletions(-) [+]
line wrap: on
line diff
--- a/doc/runtime.txt	Thu Apr 24 13:21:09 2008 +0200
+++ b/doc/runtime.txt	Thu Apr 24 14:40:09 2008 +0200
@@ -21,6 +21,49 @@
    .. autoclass:: viff.runtime.BasicRuntime
       :members:
 
+      .. attribute:: BasicRuntime.program_counter
+
+         Whenever a share is sent over the network, it must be
+         uniquely identified so that the receiving player known what
+         operation the share is a result of. This is done by
+         associating a *program counter* with each operation.
+
+         Keeping the program counter synchronized between all players
+         ought to be easy, but because of the asynchronous nature of
+         network protocols, all players might not reach the same parts
+         of the program at the same time.
+
+         Consider two players *A* and *B* who are both waiting on the
+         variables *a* and *b*. Callbacks have been added to *a* and
+         *b*, and the question is what program counter the callbacks
+         should use when sending data out over the network.
+
+         Let *A* receive input for *a* and then for *b* a little
+         later, and let *B* receive the inputs in reversed order so
+         that the input for *b* arrives first. The goal is to keep the
+         program counters synchronized so that program counter *x*
+         refers to the same operation on all players. Because the
+         inputs arrive in different order at different players,
+         incrementing a simple global counter is not enough.
+
+         Instead, a *tree* is made, which follows the tree of
+         execution. At the top level the program counter starts at
+         ``[0]``. At the next operation it becomes ``[1]``, and so on.
+         If a callback is scheduled (see :meth:`schedule_callback`) at
+         program counter ``[x, y, z]``, any calls it makes will be
+         numbered ``[x, y, z, 1]``, then ``[x, y, z, 2]``, and so on.
+
+         Maintaining such a tree of program counters ensures that
+         different parts of the program execution never reuses the
+         same program counter for different variables.
+
+         The :func:`increment_pc` decorator is responsible for
+         dynamically building the tree as the execution unfolds and
+         :meth:`schedule_callback` is responsible for scheduling
+         callbacks with the correct program counter.
+
+         See :ref:`program-counters` for more background information.
+
    .. autoclass:: viff.runtime.Runtime
       :members:
 
--- a/viff/runtime.py	Thu Apr 24 13:21:09 2008 +0200
+++ b/viff/runtime.py	Thu Apr 24 14:40:09 2008 +0200
@@ -450,46 +450,6 @@
         self._needed_data = {}
 
         #: Current program counter.
-        #:
-        #: Whenever a share is sent over the network, it must be
-        #: uniquely identified so that the receiving player known what
-        #: operation the share is a result of. This is done by
-        #: associating a :term:`program counter` with each operation.
-        #:
-        #: Keeping the program counter synchronized between all
-        #: players ought to be easy, but because of the asynchronous
-        #: nature of network protocols, all players might not reach
-        #: the same parts of the program at the same time.
-        #:
-        #: Consider two players *A* and *B* who are both waiting on
-        #: the variables *a* and *b*. Callbacks have been added to
-        #: *a* and *b*, and the question is what program counter the
-        #: callbacks should use when sending data out over the
-        #: network.
-        #:
-        #: Let *A* receive input for *a* and then for *b* a little
-        #: later, and let *B* receive the inputs in reversed order so
-        #: that the input for *b* arrives first. The goal is to keep
-        #: the program counters synchronized so that program counter
-        #: *x* refers to the same operation on all players. Because
-        #: the inputs arrive in different order at different players,
-        #: incrementing a simple global counter is not enough.
-        #:
-        #: Instead, a *tree* is made, which follows the tree of
-        #: execution. At the top level the program counter starts at
-        #: ``[0]``. At the next operation it becomes ``[1]``, and so on.
-        #: If a callback is scheduled (see :meth:`schedule_callback`) at
-        #: program counter ``[x, y, z]``, any calls it makes will be
-        #: numbered ``[x, y, z, 1]``, then ``[x, y, z, 2]``, and so on.
-        #:
-        #: Maintaining such a tree of program counters ensures that
-        #: different parts of the program execution never reuses the
-        #: same program counter for different variables.
-        #:
-        #: The :func:`increment_pc` decorator is responsible for
-        #: dynamically building the tree as the execution unfolds and
-        #: :meth:`schedule_callback` is responsible for scheduling
-        #: callbacks with the correct program counter.
         self.program_counter = [0]
 
         #: Connections to the other players.