viff

changeset 721:6d64bb9dfc50

Remove remaining epytext format from viff.runtime.
author Martin Geisler <mg@daimi.au.dk>
date Thu, 24 Apr 2008 11:48:47 +0200
parents 7761dc383cd5
children 459290cb7812
files viff/runtime.py
diffstat 1 files changed, 49 insertions(+), 95 deletions(-) [+]
line diff
     1.1 --- a/viff/runtime.py	Thu Apr 24 11:26:42 2008 +0200
     1.2 +++ b/viff/runtime.py	Thu Apr 24 11:48:47 2008 +0200
     1.3 @@ -67,9 +67,8 @@
     1.4      def __init__(self, runtime, field, value=None):
     1.5          """Initialize a share.
     1.6  
     1.7 -        @param runtime: The L{Runtime} to use.
     1.8 -        @param field: The field where the value lies.
     1.9 -        @param value: The initial value of the share (if known).
    1.10 +        If an initial value is given, it will be passed to
    1.11 +        :meth:`callback` right away.
    1.12          """
    1.13          assert field is not None, "Cannot construct share without a field."
    1.14          assert callable(field), "The field is not callable, wrong argument?"
    1.15 @@ -182,10 +181,9 @@
    1.16      def __init__(self, shares, threshold=None):
    1.17          """Initialize a share list.
    1.18  
    1.19 -        @param shares: non-empty list of L{Share} objects.
    1.20 -        @param threshold: number of shares to wait for. This is either
    1.21 -        a number such that C{0 < threshold <= len(shares)} or C{None}
    1.22 -        if all shares should be waited for.
    1.23 +        The list of shares must be non-empty and if a threshold is
    1.24 +        given, it must hold that ``0 < threshold <= len(shares)``. The
    1.25 +        default threshold is ``len(shares)``.
    1.26          """
    1.27          assert len(shares) > 0, "Cannot create empty ShareList"
    1.28          assert threshold is None or 0 < threshold <= len(shares), \
    1.29 @@ -230,9 +228,6 @@
    1.30      >>> a.callback(10)
    1.31      >>> b.callback(20)
    1.32      [10, 20]
    1.33 -
    1.34 -    @param shares: the shares.
    1.35 -    @type shares: :class:`list` of :class:`Share` objects
    1.36      """
    1.37  
    1.38      def filter_results(results):
    1.39 @@ -262,9 +257,6 @@
    1.40          #: if we are waiting on input from the player, or the data
    1.41          #: itself if data is received from the other player before we
    1.42          #: are ready to use it.
    1.43 -        #:
    1.44 -        #: @type: C{dict} from C{(program_counter, data_type)} to
    1.45 -        #: deferred data.
    1.46          self.incoming_data = {}
    1.47  
    1.48      def connectionMade(self):
    1.49 @@ -280,10 +272,6 @@
    1.50          The string received is unmarshalled into the program counter,
    1.51          and a data part. The data is passed the appropriate Deferred
    1.52          in :class:`self.incoming_data`.
    1.53 -
    1.54 -        @param string: bytes from the network.
    1.55 -        @type string: `(program_counter, data)` in
    1.56 -        marshalled form
    1.57          """
    1.58          if self.peer_id is None:
    1.59              # TODO: Handle ValueError if the string cannot be decoded.
    1.60 @@ -464,60 +452,59 @@
    1.61          #: Whenever a share is sent over the network, it must be
    1.62          #: uniquely identified so that the receiving player known what
    1.63          #: operation the share is a result of. This is done by
    1.64 -        #: associating a X{program counter} with each operation.
    1.65 +        #: associating a :term:`program counter` with each operation.
    1.66          #:
    1.67          #: Keeping the program counter synchronized between all
    1.68          #: players ought to be easy, but because of the asynchronous
    1.69          #: nature of network protocols, all players might not reach
    1.70          #: the same parts of the program at the same time.
    1.71          #:
    1.72 -        #: Consider two players M{A} and M{B} who are both waiting on
    1.73 -        #: the variables C{a} and C{b}. Callbacks have been added to
    1.74 -        #: C{a} and C{b}, and the question is what program counter the
    1.75 +        #: Consider two players *A* and *B* who are both waiting on
    1.76 +        #: the variables *a* and *b*. Callbacks have been added to
    1.77 +        #: *a* and *b*, and the question is what program counter the
    1.78          #: callbacks should use when sending data out over the
    1.79          #: network.
    1.80          #:
    1.81 -        #: Let M{A} receive input for C{a} and then for C{b} a little
    1.82 -        #: later, and let M{B} receive the inputs in reversed order so
    1.83 -        #: that the input for C{b} arrives first. The goal is to keep
    1.84 +        #: Let *A* receive input for *a* and then for *b* a little
    1.85 +        #: later, and let *B* receive the inputs in reversed order so
    1.86 +        #: that the input for *b* arrives first. The goal is to keep
    1.87          #: the program counters synchronized so that program counter
    1.88 -        #: M{x} refers to the same operation on all players. Because
    1.89 +        #: *x* refers to the same operation on all players. Because
    1.90          #: the inputs arrive in different order at different players,
    1.91          #: incrementing a simple global counter is not enough.
    1.92          #:
    1.93 -        #: Instead, a I{tree} is made, which follows the tree of
    1.94 +        #: Instead, a *tree* is made, which follows the tree of
    1.95          #: execution. At the top level the program counter starts at
    1.96 -        #: C{[0]}. At the next operation it becomes C{[1]}, and so on.
    1.97 -        #: If a callback is scheduled (see L{schedule_callback}) at
    1.98 -        #: program counter C{[x, y, z]}, any calls it makes will be
    1.99 -        #: numbered C{[x, y, z, 1]}, then C{[x, y, z, 2]}, and so on.
   1.100 +        #: ``[0]``. At the next operation it becomes ``[1]``, and so on.
   1.101 +        #: If a callback is scheduled (see :meth:`schedule_callback`) at
   1.102 +        #: program counter ``[x, y, z]``, any calls it makes will be
   1.103 +        #: numbered ``[x, y, z, 1]``, then ``[x, y, z, 2]``, and so on.
   1.104          #:
   1.105          #: Maintaining such a tree of program counters ensures that
   1.106          #: different parts of the program execution never reuses the
   1.107          #: same program counter for different variables.
   1.108          #:
   1.109 -        #: The L{increment_pc} decorator is responsible for
   1.110 +        #: The :func:`increment_pc` decorator is responsible for
   1.111          #: dynamically building the tree as the execution unfolds and
   1.112 -        #: L{schedule_callback} is responsible for scheduling
   1.113 +        #: :meth:`schedule_callback` is responsible for scheduling
   1.114          #: callbacks with the correct program counter.
   1.115 -        #:
   1.116 -        #: @type: C{list} of integers.
   1.117          self.program_counter = [0]
   1.118  
   1.119          #: Connections to the other players.
   1.120          #:
   1.121 -        #: @type: C{dict} from Player ID to L{ShareExchanger} objects.
   1.122 +        #: Mapping from from Player ID to :class:`ShareExchanger`
   1.123 +        #: objects.
   1.124          self.protocols = {}
   1.125  
   1.126          #: Number of known players.
   1.127          #:
   1.128 -        #: Equal to C{len(players)}, but storing it here is more
   1.129 +        #: Equal to ``len(self.players)``, but storing it here is more
   1.130          #: direct.
   1.131          self.num_players = 0
   1.132  
   1.133          #: Information on players.
   1.134          #:
   1.135 -        #: @type: C{dict} from player_id to L{Player} objects.
   1.136 +        #: Mapping from Player ID to :class:`Player` objects.
   1.137          self.players = {}
   1.138          # Add ourselves, but with no protocol since we wont be
   1.139          # communicating with ourselves.
   1.140 @@ -722,24 +709,13 @@
   1.141      def open(self, share, receivers=None, threshold=None):
   1.142          """Open a secret sharing.
   1.143  
   1.144 +        The *receivers* are the players that will eventually obtain
   1.145 +        the opened result. The default is to let everybody know the
   1.146 +        result. By default the :attr:`threshold` + 1 shares are
   1.147 +        reconstructed, but *threshold* can be used to override this.
   1.148 +
   1.149          Communication cost: every player sends one share to each
   1.150          receiving player.
   1.151 -
   1.152 -        @param share: the player's private part of the sharing to open.
   1.153 -        @type share: Share
   1.154 -
   1.155 -        @param receivers: the IDs of the players that will eventually
   1.156 -            obtain the opened result or None if all players should
   1.157 -            obtain the opened result.
   1.158 -        @type receivers: None or a C{list} of integers
   1.159 -
   1.160 -        @param threshold: the threshold used to open the sharing or None
   1.161 -            if the runtime default should be used.
   1.162 -        @type threshold: integer or None
   1.163 -
   1.164 -        @return: the result of the opened sharing if the player's ID
   1.165 -            is in C{receivers}, otherwise None.
   1.166 -        @returntype: Share or None
   1.167          """
   1.168          assert isinstance(share, Share)
   1.169          # all players receive result by default
   1.170 @@ -851,30 +827,20 @@
   1.171      @increment_pc
   1.172      def prss_share(self, inputters, field, element=None):
   1.173          u"""Creates pseudo-random secret sharings.
   1.174 +        
   1.175 +        This protocol creates a secret sharing for each player in the
   1.176 +        subset of players specified in *inputters*. Each inputter
   1.177 +        provides an integer. The result is a list of shares, one for
   1.178 +        each inputter.
   1.179  
   1.180 -        This protocol creates a secret sharing for each player in the
   1.181 -        subset of players specified in C{inputters}. The protocol uses the
   1.182 -        pseudo-random secret sharing technique described in the paper "Share
   1.183 -        Conversion, Pseudorandom Secret-Sharing and Applications to Secure
   1.184 -        Computation" by Ronald Cramer, Ivan Damgård, and Yuval Ishai in Proc.
   1.185 -        of TCC 2005, LNCS 3378.
   1.186 -        U{Download <http://www.cs.technion.ac.il/~yuvali/pubs/CDI05.ps>}.
   1.187 +        The protocol uses the pseudo-random secret sharing technique
   1.188 +        described in the paper "Share Conversion, Pseudorandom
   1.189 +        Secret-Sharing and Applications to Secure Computation" by
   1.190 +        Ronald Cramer, Ivan Damgård, and Yuval Ishai in Proc. of TCC
   1.191 +        2005, LNCS 3378. `Download
   1.192 +        <http://www.cs.technion.ac.il/~yuvali/pubs/CDI05.ps>`__
   1.193  
   1.194          Communication cost: Each inputter does one broadcast.
   1.195 -
   1.196 -        @param inputters: The IDs of the players that will share a secret.
   1.197 -        @type inputters: C{list} of integers
   1.198 -
   1.199 -        @param field: The field over which to share all the secrets.
   1.200 -        @type field: L{FieldElement}
   1.201 -
   1.202 -        @param element: The secret that this player shares or C{None} if this
   1.203 -            player is not in C{inputters}.
   1.204 -        @type element: int, long, or None
   1.205 -
   1.206 -        @return: A list of shares corresponding to the secrets submitted by
   1.207 -            the players in C{inputters}.
   1.208 -        @returntype: C{List} of C{Shares}
   1.209          """
   1.210          # Verifying parameters.
   1.211          if element is None:
   1.212 @@ -985,10 +951,10 @@
   1.213  
   1.214      @increment_pc
   1.215      def shamir_share(self, inputters, field, number=None, threshold=None):
   1.216 -        """Secret share C{number} over C{field} using Shamir's method.
   1.217 +        """Secret share *number* over *field* using Shamir's method.
   1.218  
   1.219 -        The number is shared using polynomial of degree C{threshold}
   1.220 -        (defaults to L{self.threshold}). Returns a list of shares
   1.221 +        The number is shared using polynomial of degree *threshold*
   1.222 +        (defaults to :attr:`threshold`). Returns a list of shares
   1.223          unless unless there is only one inputter in which case the
   1.224          share is returned directly.
   1.225  
   1.226 @@ -1047,9 +1013,9 @@
   1.227  
   1.228          #: A hyper-invertible matrix.
   1.229          #:
   1.230 -        #: It should be suitable for L{self.num_players} players, but
   1.231 +        #: It should be suitable for :attr:`num_players` players, but
   1.232          #: since we don't know the total number of players yet, we set
   1.233 -        #: it to C{None} here and update it as necessary.
   1.234 +        #: it to :const:`None` here and update it as necessary.
   1.235          self._hyper = None
   1.236          Runtime.__init__(self, player, threshold, options)
   1.237  
   1.238 @@ -1192,14 +1158,9 @@
   1.239          """Double-share a random secret using two polynomials.
   1.240  
   1.241          The guarantee is that a number of shares are made and out of
   1.242 -        those, the T that are returned by this method will be correct
   1.243 -        double-sharings of a random number using d1 and d2 as the
   1.244 +        those, the *T* that are returned by this method will be correct
   1.245 +        double-sharings of a random number using *d1* and *d2* as the
   1.246          polynomial degrees.
   1.247 -
   1.248 -        @param T: The number of double-shares output.
   1.249 -        @param d1: The degree of the first polynomial.
   1.250 -        @param d2: The degree of the second polynomial.
   1.251 -        @param field: The field over which to share the secret.
   1.252          """
   1.253          inputters = range(1, self.num_players + 1)
   1.254          if self._hyper is None:
   1.255 @@ -1345,9 +1306,6 @@
   1.256          the paper "An asynchronous [(n-1)/3]-resilient consensus
   1.257          protocol" by G. Bracha in Proc. 3rd ACM Symposium on
   1.258          Principles of Distributed Computing, 1984, pages 154-162.
   1.259 -
   1.260 -        @param sender: the sender of the broadcast message.
   1.261 -        @param message: the broadcast message, used only by the sender.
   1.262          """
   1.263  
   1.264          result = Deferred()
   1.265 @@ -1441,10 +1399,10 @@
   1.266      def broadcast(self, senders, message=None):
   1.267          """Perform one or more Bracha broadcast(s).
   1.268  
   1.269 -        The list of senders given will determine the subset of players
   1.270 +        The list of *senders* given will determine the subset of players
   1.271          who wish to broadcast a message. If this player wishes to
   1.272          broadcast, its ID must be in the list of senders and the
   1.273 -        optional message parameter must be used.
   1.274 +        optional *message* parameter must be used.
   1.275  
   1.276          If the list of senders consists only of a single sender, the
   1.277          result will be a single element, otherwise it will be a list.
   1.278 @@ -1454,10 +1412,6 @@
   1.279          the paper "An asynchronous [(n-1)/3]-resilient consensus
   1.280          protocol" by G. Bracha in Proc. 3rd ACM Symposium on
   1.281          Principles of Distributed Computing, 1984, pages 154-162.
   1.282 -
   1.283 -        @param senders: the list of senders.
   1.284 -        @param message: the broadcast message, used if this player is
   1.285 -        a sender.
   1.286          """
   1.287          assert message is None or self.id in senders
   1.288