viff

changeset 712:040e559b06a0

Started documenting runtime.py. Still needs a lot of work.
author Mikkel Krøigård <mk@daimi.au.dk>
date Tue, 22 Apr 2008 16:09:12 +0200
parents adbbc93b4622
children 1f813a287ec5
files doc/implementation.txt doc/runtime.txt viff/runtime.py
diffstat 3 files changed, 65 insertions(+), 45 deletions(-) [+]
line diff
     1.1 --- a/doc/implementation.txt	Tue Apr 22 14:32:26 2008 +0200
     1.2 +++ b/doc/implementation.txt	Tue Apr 22 16:09:12 2008 +0200
     1.3 @@ -9,5 +9,7 @@
     1.4     field
     1.5     shamir
     1.6     matrix
     1.7 +   runtime
     1.8     prss
     1.9     config
    1.10 +
     2.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.2 +++ b/doc/runtime.txt	Tue Apr 22 16:09:12 2008 +0200
     2.3 @@ -0,0 +1,18 @@
     2.4 +
     2.5 +Runtime Module
     2.6 +==============
     2.7 +
     2.8 +.. automodule:: viff.runtime
     2.9 +
    2.10 +   .. autoclass:: viff.runtime.Share
    2.11 +      :members: clone
    2.12 +
    2.13 +   .. autoclass:: viff.runtime.ShareList
    2.14 +
    2.15 +   .. autofunction viff.runtime.gather_shares
    2.16 +
    2.17 +   .. autoclass:: viff.runtime.ShareExchanger
    2.18 +      :members: sendShare, sendData, loseConnection
    2.19 +
    2.20 +   .. autoclass:: viff.runtime.Runtime
    2.21 +
     3.1 --- a/viff/runtime.py	Tue Apr 22 14:32:26 2008 +0200
     3.2 +++ b/viff/runtime.py	Tue Apr 22 16:09:12 2008 +0200
     3.3 @@ -24,10 +24,10 @@
     3.4  the calculations.
     3.5  
     3.6  Each player participating in the protocol will instantiate a
     3.7 -L{Runtime} object and use it for the calculations.
     3.8 +:class:`Runtime` object and use it for the calculations.
     3.9  
    3.10 -The Runtime returns L{Share} objects for most operations, and these
    3.11 -can be added, subtracted, and multiplied as normal thanks to
    3.12 +The Runtime returns :class:`Share` objects for most operations, and
    3.13 +these can be added, subtracted, and multiplied as normal thanks to
    3.14  overloaded arithmetic operators. The runtime will take care of
    3.15  scheduling things correctly behind the scenes.
    3.16  """
    3.17 @@ -53,14 +53,15 @@
    3.18  class Share(Deferred):
    3.19      """A shared number.
    3.20  
    3.21 -    The L{Runtime} operates on shares, represented by this class.
    3.22 +    The :class:`Runtime` operates on shares, represented by this class.
    3.23      Shares are asynchronous in the sense that they promise to attain a
    3.24      value at some point in the future.
    3.25  
    3.26 -    Shares overload the arithmetic operations so that C{x = a + b}
    3.27 -    will create a new share C{x}, which will eventually contain the
    3.28 -    sum of C{a} and C{b}. Each share is associated with a L{Runtime}
    3.29 -    and the arithmetic operations simply call back to that runtime.
    3.30 +    Shares overload the arithmetic operations so that ``x = a + b``
    3.31 +    will create a new share *x*, which will eventually contain the
    3.32 +    sum of *a* and *b*. Each share is associated with a
    3.33 +    :class:`Runtime` and the arithmetic operations simply call back to
    3.34 +    that runtime.
    3.35      """
    3.36  
    3.37      def __init__(self, runtime, field, value=None):
    3.38 @@ -134,8 +135,8 @@
    3.39      def clone(self):
    3.40          """Clone a share.
    3.41  
    3.42 -        Works like L{util.clone_deferred} except that it returns a new
    3.43 -        Share instead of a Deferred.
    3.44 +        Works like :meth:`util.clone_deferred` except that it returns a new
    3.45 +        :class:`Share` instead of a :class:`Deferred`.
    3.46          """
    3.47  
    3.48          def split_result(result):
    3.49 @@ -149,11 +150,12 @@
    3.50  class ShareList(Share):
    3.51      """Create a share that waits on a number of other shares.
    3.52  
    3.53 -    Roughly modelled after the Twisted C{DeferredList} class. The
    3.54 -    advantage of this class is that it is a L{Share} (not just a
    3.55 -    C{Deferred}) and that it can be made to trigger when a certain
    3.56 -    threshold of the shares are ready. This example shows how the
    3.57 -    C{pprint} callback is triggered when C{a} and C{c} are ready:
    3.58 +    Roughly modelled after the Twisted :class:`DeferredList`
    3.59 +    class. The advantage of this class is that it is a :class:`Share`
    3.60 +    (not just a :class:`Deferred`) and that it can be made to trigger
    3.61 +    when a certain threshold of the shares are ready. This example
    3.62 +    shows how the :meth:`pprint` callback is triggered when *a* and
    3.63 +    *c* are ready:
    3.64  
    3.65      >>> from pprint import pprint
    3.66      >>> from viff.field import GF256
    3.67 @@ -167,17 +169,16 @@
    3.68      >>> c.callback(20)
    3.69      [(True, 10), None, (True, 20)]
    3.70  
    3.71 -    The C{pprint} function is called with a list of pairs. The first
    3.72 +    The :meth:`pprint` function is called with a list of pairs. The first
    3.73      component of each pair is a boolean indicating if the callback or
    3.74 -    errback method was called on the corresponding L{Share}, and the
    3.75 -    second component is the value given to the callback/errback.
    3.76 +    errback method was called on the corresponding :class:`Share`, and
    3.77 +    the second component is the value given to the callback/errback.
    3.78  
    3.79      If a threshold less than the full number of shares is used, some
    3.80 -    of the pairs may be missing and C{None} is used instead. In the
    3.81 -    example above the C{c} Share arrived later than C{a} and C{b}, and
    3.82 -    so the list contains a C{None} on its place.
    3.83 +    of the pairs may be missing and :const:`None` is used instead. In
    3.84 +    the example above the *c* share arrived later than *a* and *b*,
    3.85 +    and so the list contains a :const:`None` on its place.
    3.86      """
    3.87 -
    3.88      def __init__(self, shares, threshold=None):
    3.89          """Initialize a share list.
    3.90  
    3.91 @@ -214,10 +215,10 @@
    3.92  def gather_shares(shares):
    3.93      """Gather shares.
    3.94  
    3.95 -    Roughly modelled after the Twisted C{gatherResults} function. It
    3.96 -    takes a list of shares and returns a new L{Share} which will be
    3.97 -    triggered with a list of values, namely the values from the
    3.98 -    initial shares:
    3.99 +    Roughly modelled after the Twisted :meth:`gatherResults`
   3.100 +    function. It takes a list of shares and returns a new
   3.101 +    :class:`Share` which will be triggered with a list of values,
   3.102 +    namely the values from the initial shares:
   3.103  
   3.104      >>> from pprint import pprint
   3.105      >>> from viff.field import GF256
   3.106 @@ -231,7 +232,7 @@
   3.107      [10, 20]
   3.108  
   3.109      @param shares: the shares.
   3.110 -    @type shares: C{list} of L{Share} objects
   3.111 +    @type shares: :class:`list` of :class:`Share` objects
   3.112      """
   3.113  
   3.114      def filter_results(results):
   3.115 @@ -248,8 +249,8 @@
   3.116      Twisted protocol is one such connection. It is used to send and
   3.117      receive shares from one other player.
   3.118  
   3.119 -    The C{marshal} module is used for converting the data to bytes for
   3.120 -    the network and to convert back again to structured data.
   3.121 +    The :mod:`marshal` module is used for converting the data to bytes
   3.122 +    for the network and to convert back again to structured data.
   3.123      """
   3.124  
   3.125      def __init__(self):
   3.126 @@ -278,10 +279,10 @@
   3.127  
   3.128          The string received is unmarshalled into the program counter,
   3.129          and a data part. The data is passed the appropriate Deferred
   3.130 -        in L{self.incoming_data}.
   3.131 +        in :class:`self.incoming_data`.
   3.132  
   3.133          @param string: bytes from the network.
   3.134 -        @type string: C{(program_counter, data)} in
   3.135 +        @type string: `(program_counter, data)` in
   3.136          marshalled form
   3.137          """
   3.138          if self.peer_id is None:
   3.139 @@ -320,9 +321,6 @@
   3.140  
   3.141          The program counter and the share are marshalled and sent to
   3.142          the peer.
   3.143 -
   3.144 -        @param program_counter: the program counter associated with
   3.145 -        the share.
   3.146          """
   3.147          self.sendData(program_counter, "share", share.value)
   3.148  
   3.149 @@ -715,18 +713,20 @@
   3.150  class Runtime(BasicRuntime):
   3.151      """The VIFF runtime.
   3.152  
   3.153 -    The runtime is used for sharing values (L{shamir_share} or
   3.154 -    L{prss_share}) into L{Share} object and opening such shares
   3.155 -    (L{open}) again. Calculations on shares is normally done through
   3.156 -    overloaded arithmetic operations, but it is also possible to call
   3.157 -    L{add}, L{mul}, etc. directly if one prefers.
   3.158 +    The runtime is used for sharing values (:meth:`shamir_share` or
   3.159 +    :meth:`prss_share`) into :class:`Share` object and opening such
   3.160 +    shares (:meth:`open`) again. Calculations on shares is normally
   3.161 +    done through overloaded arithmetic operations, but it is also
   3.162 +    possible to call :meth:`add`, :meth:`mul`, etc. directly if one
   3.163 +    prefers.
   3.164  
   3.165 -    Each player in the protocol uses a Runtime object. To create an
   3.166 -    instance and connect it correctly with the other players, please
   3.167 -    use the L{create_runtime} function instead of instantiating a
   3.168 -    Runtime directly. The L{create_runtime} function will take care of
   3.169 -    setting up network connections and return a Deferred which
   3.170 -    triggers with the Runtime object when it is ready.
   3.171 +    Each player in the protocol uses a :class:`Runtime` object. To
   3.172 +    create an instance and connect it correctly with the other
   3.173 +    players, please use the :func:`create_runtime` function instead of
   3.174 +    instantiating a Runtime directly. The :func:`create_runtime`
   3.175 +    function will take care of setting up network connections and
   3.176 +    return a :class:`Deferred` which triggers with the
   3.177 +    :class:`Runtime` object when it is ready.
   3.178      """
   3.179  
   3.180      def __init__(self, player, threshold, options=None):