changeset 38:a93c7113945e

Renamed /docs/ to /doc/. Redirection has been put in place via a .htaccess file, so no URLs should break because of this.
author Martin Geisler <mg@daimi.au.dk>
date Wed, 20 Feb 2008 22:26:38 +0100
parents 0c5cba5e53d8
children c5cde5d82c72
files .htaccess doc/bibliography.txt doc/coding-style.txt doc/design-talk.pdf doc/index.txt doc/layout.rst doc/unit-testing.txt docs/bibliography.txt docs/coding-style.txt docs/design-talk.pdf docs/index.txt docs/layout.rst docs/unit-testing.txt
diffstat 13 files changed, 461 insertions(+), 452 deletions(-) [+]
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/.htaccess	Wed Feb 20 22:26:38 2008 +0100
@@ -0,0 +1,9 @@
+
+RewriteEngine on
+
+# Unfortunately this path only works on places like DreamHost where
+# the website is in the root of the domain.
+RewriteBase  /
+
+# Rewrite /docs/ to /doc/.
+RewriteRule  ^docs(.*)$  doc$1 [R]
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/bibliography.txt	Wed Feb 20 22:26:38 2008 +0100
@@ -0,0 +1,59 @@
+.. -*- coding: utf-8 -*-
+
+==============
+ Bibliography
+==============
+
+.. note::
+
+   This list is far from complete. If you find more relevant
+   references then please `send us a mail`__ with the information.
+
+   .. __: mailto:viff-devel@viff.dk
+
+The algorighms used by VIFF are published in various academic papers.
+Here we will try to point out which parts of the code uses which
+papers.
+
+* The ``viff.shamir`` module is obviously based on [Shamir79]_.
+
+*  ``apps/millionaires.py``: Inspired by [Yao82]_.
+
+* The default comparison operation (``Runtime.greater_than_equal``) is
+  based on the comparison protocol from [Toft05]_.
+
+* Broadcast (``Runtime.broadcast``) is based on the original paper by
+  [Bracha84]_ and on the explanation by [Cachin05]_.
+
+* The pseudo-random secret sharing (PRSS) in ``viff.prss`` is
+  described in [CDI05]_.
+
+
+.. [Bracha84] G. Bracha, *An asynchronous [(n-1)/3]-resilient
+   consensus protocol*, Proc 3rd ACM Symposium on Principles of
+   Distributed Computing (PODC), 1984, 154-162.
+
+.. [Cachin05] Christian Cachin, *Security and Fault-tolerance in
+   Distributed Systems*, ETHZ, 2005, PDF__.
+
+   .. __: http://www.zurich.ibm.com/~cca/sft05/agreement.pdf
+
+.. [CDI05] Ronald Cramer, Ivan Damgård, and Yuval Ishai, *Share
+   Conversion, Pseudorandom Secret-Sharing and Applications to Secure
+   Computation*, Proc of TCC 2005, LNCS 3378, PS__.
+
+   .. __:  http://www.cs.technion.ac.il/~yuvali/pubs/CDI05.ps
+
+.. [Shamir79] Adi Shamir, *How to share a secret*, Communications of
+   the ACM, 22 (11): 612-613.
+
+.. [Toft05] Tomas Toft, *Secure Integer Computation with Applications
+   in Economics*, PhD Progress Report, July 2005, PDF__.
+
+   .. __: http://www.daimi.au.dk/~tomas/publications/progress.pdf
+
+.. [Yao82] Andrew Chi-Chih Yao, *Protocols for Secure Computations*,
+   FOCS 1982, 160-164.
+
+
+.. include:: layout.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/coding-style.txt	Wed Feb 20 22:26:38 2008 +0100
@@ -0,0 +1,56 @@
+.. -*- coding: utf-8 -*-
+
+===================
+ VIFF Coding Style
+===================
+
+The VIFF code tries to follow the coding style laid out in :PEP:`8`,
+which you should read or at least skim over. You can check your code
+against by running the pep8.py_ checker.
+
+.. _pep8.py: http://svn.browsershots.org/trunk/devtools/pep8/pep8.py
+
+
+The VIFF Coding Style in Short
+------------------------------
+
+A summary of the rules:
+
+* Use four spaces for indention, never tabs.
+
+* Use a single space around binary operators.
+
+* Name classes using ``CamelCase``.
+
+* Name variables, function, and methods using lowercase words like
+  ``foo_bar``.
+
+* Write docstrings for your functions and methods. Include test for
+  doctest_ if possible.
+
+  .. _doctest: http://docs.python.org/lib/module-doctest.html
+
+* Try to be consistent.
+
+These rules are there to make the source code more readable for both
+old and new people.
+
+The Twisted Coding Style
+------------------------
+
+VIFF uses Twisted_ and their code follows a slightly different coding
+style. Their style is closer to the style used in Java where functions
+and methods are named ``fooBar`` instead of ``foo_bar``.
+
+When writing code which is close to Twisted code, you might want to
+follow that style too. If you subclass a Twisted class to override
+some behavior, you might be forced to follow their style.
+
+If you have a choice, then you should only use the Twisted style if
+you expect people to call both your code and the Twisted code — if
+people will only call your code, then please follow the standard VIFF
+coding style.
+
+.. _Twisted: http://twistedmatrix.com/
+
+.. include:: layout.rst
Binary file doc/design-talk.pdf has changed
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/index.txt	Wed Feb 20 22:26:38 2008 +0100
@@ -0,0 +1,42 @@
+
+====================
+ VIFF Documentation
+====================
+
+Here you will find some resources about VIFF.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+* The API documentation not only describes the API, but also tries to
+  give a overview of the VIFF architecture.
+
+  Available `online`__.
+
+  .. __: http://viff.dk/api/
+
+* The code examples includes in the ``apps/`` directory also contains
+  many hints on best practices with VIFF. The ``apps/millionaires.py``
+  example is particularly well commented and may serve as a template
+  for new programs.
+
+* The unit tests in the ``viff/test/`` directory will show you many
+  small programs using all of VIFF.
+
+Presentations
+~~~~~~~~~~~~~
+
+* VIFF Design Talk given by Martin Geisler on September 20th, 2007 at
+  a SIMAP_ meeting. The talk describes some of the goals of the VIFF
+  design. It is current to version 0.2 of VIFF.
+
+  Available as PDF__.
+
+  .. _SIMAP: http://simap.dk/
+  .. __: design-talk.pdf
+
+Please `send us`__ any presentations or programs you make.
+
+.. __: mailto:viff-devel@viff.dk
+
+.. include:: layout.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/layout.rst	Wed Feb 20 22:26:38 2008 +0100
@@ -0,0 +1,11 @@
+
+.. header::
+   [ `VIFF Documentation <index.html>`__ ]
+   [ `Coding Style <coding-style.html>`__ ]
+   [ `Unit Testing <unit-testing.html>`__ ]
+   [ `Bibliography <bibliography.html>`__ ]
+
+.. footer::
+   `Return to the VIFF homepage <../index.html>`__.
+
+   .. include:: ../copyright.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/unit-testing.txt	Wed Feb 20 22:26:38 2008 +0100
@@ -0,0 +1,284 @@
+.. -*- coding: utf-8 -*-
+
+==============
+ Unit Testing
+==============
+
+VIFF employs a set of unit tests to help developers catch regressions
+and to ensure the correctness of the implementation. VIFF uses the
+Trial_ testing framework, which is part of Twisted. Using Trial has
+the big advantage that it understands Twisted's Deferreds_ — if a unit
+test returns a Deferred, Trial waits for it to trigger before it
+declares the test a success or failure. Please refer to this
+tutorial_ for more information.
+
+.. _Trial: http://twistedmatrix.com/trac/wiki/TwistedTrial
+.. _Deferreds: http://twistedmatrix.com/projects/core/
+               documentation/howto/defer.html
+.. _tutorial: http://twistedmatrix.com/trac/browser/branches/
+              trial-tutorial-2443/doc/core/howto/trial.xhtml?format=raw
+
+Running the Unit Tests
+----------------------
+
+To run the VIFF unit tests you must make sure that ``import viff``
+works correctly in Python. In other words, you must make sure that
+VIFF is installed or that the root of your source tree is in
+``PYTHONPATH``. You can test this by changing to some unrelated
+directory, starting an interactive Python session and run:
+
+.. sourcecode:: pycon
+
+  >>> import viff
+  >>> print viff.__version__
+  0.3
+
+If it fails with an ImportError, then please double-check that your
+``PYTHONPATH`` is setup correctly.
+
+Now simply execute ``trial viff`` to run the unit tests. You should
+get output similar to this:
+
+.. sourcecode:: text
+
+  % trial viff
+  Seeding random generator with random seed 4658
+  Running 65 tests.
+  viff.test.test_active_runtime
+    ActiveRuntimeTest
+      test_broadcast ...                                           [OK]
+  viff.test.test_basic_runtime
+    ProgramCounterTest
+      test_callback ...                                            [OK]
+      test_complex_operation ...                                   [OK]
+      test_initial_value ...                                       [OK]
+      test_multiple_callbacks ...                             [SKIPPED]
+      test_nested_calls ...                                        [OK]
+      test_simple_operation ...                                    [OK]
+  viff.test.test_field
+    GF256TestCase
+      test_add ...                                                 [OK]
+      test_construct ...                                           [OK]
+      test_div ...                                                 [OK]
+      test_field ...                                               [OK]
+      test_invert ...                                              [OK]
+      test_mul ...                                                 [OK]
+      test_neg ...                                                 [OK]
+      test_pow ...                                                 [OK]
+      test_str ...                                                 [OK]
+      test_sub ...                                                 [OK]
+      test_xor ...                                                 [OK]
+    GFpElementTestCase
+      test_add ...                                                 [OK]
+      test_bit ...                                                 [OK]
+      test_div ...                                                 [OK]
+      test_field ...                                               [OK]
+      test_invert ...                                              [OK]
+      test_mul ...                                                 [OK]
+      test_neg ...                                                 [OK]
+      test_sqrt ...                                                [OK]
+      test_str ...                                                 [OK]
+      test_sub ...                                                 [OK]
+  doctest
+    DocTestCase
+      field ...                                                    [OK]
+      GF ...                                                       [OK]
+      __eq__ ...                                                   [OK]
+      __init__ ...                                                 [OK]
+      __nonzero__ ...                                              [OK]
+      __radd__ ...                                                 [OK]
+      __rmul__ ...                                                 [OK]
+  viff.test.test_prss
+    PRSSTestCase
+      test_generate_subsets ...                                    [OK]
+  doctest
+    DocTestCase
+      PRF ...                                                      [OK]
+      __call__ ...                                                 [OK]
+      __init__ ...                                                 [OK]
+      generate_subsets ...                                         [OK]
+      prss ...                                                     [OK]
+  viff.test.test_runtime
+    RuntimeTest
+      test_add ...                                                 [OK]
+      test_add_coerce ...                                          [OK]
+      test_convert_bit_share ...                                   [OK]
+      test_greater_than ...                                        [OK]
+      test_greater_than_equal ...                                  [OK]
+      test_greater_than_equalII ...                                [OK]
+      test_less_than ...                                           [OK]
+      test_less_than_equal ...                                     [OK]
+      test_mul ...                                                 [OK]
+      test_open ...                                                [OK]
+      test_open_no_mutate ...                                      [OK]
+      test_prss_share_bit ...                                      [OK]
+      test_prss_share_int ...                                      [OK]
+      test_prss_share_random_bit ...                               [OK]
+      test_prss_share_random_int ...                               [OK]
+      test_shamir_share ...                                        [OK]
+      test_shamir_share_asymmetric ...                             [OK]
+      test_sub ...                                                 [OK]
+      test_sub_coerce ...                                          [OK]
+      test_xor ...                                                 [OK]
+  doctest
+    DocTestCase
+      share ...                                                    [OK]
+      clone_deferred ...                                           [OK]
+      dlift ...                                                    [OK]
+      find_prime ...                                               [OK]
+
+  =====================================================================
+  [SKIPPED]: viff.test.test_basic_runtime.ProgramCounterTest.
+  test_multiple_callbacks
+
+  TODO: Scheduling callbacks fails to increment program counter!
+  ---------------------------------------------------------------------
+  Ran 65 tests in 18.305s
+
+  PASSED (skips=1, successes=64)
+
+Lots of success! But one of the tests was skipped — we do this when we
+have a test which represents a known problem. Otherwise every test run
+would be cluttered with long of traceback messages, making it
+difficult to notice new *unexpected* failures.
+
+
+Writing Unit Tests
+------------------
+
+The unit tests live in the ``viff.test`` package. There you will find
+a number of modules, which in turn contain classes inheriting from
+``twisted.trial.unittest.TestCase``. Trial recognizes these classes
+and will execute methods starting with ``test``.
+
+Simple Tests
+~~~~~~~~~~~~
+
+Adding a new unit test can be as simple as defining a new method in a
+suitable class. The method will want to assert certain things during
+the test, and for that Trial offers a large number of convenient
+methods such as ``assertEqual``, ``assertTrue``, and so on. The full
+reference is available `online`__. Notice that they describe the
+methods under names like ``failUnlessSomething`` which is aliased to
+``assertSomething``. So far all the VIFF unit tests use the
+``assertSomething`` style, but you are welcome to use the other if you
+prefer.
+
+.. __: http://twistedmatrix.com/documents/current/api/
+       twisted.trial.unittest._Assertions.html
+
+A simple example of a unit test is ``viff.test.test_field`` which
+looks like this (heavily abbreviated):
+
+.. sourcecode:: python
+
+  """Tests for viff.field."""
+
+  from viff.field import GF, GF256
+  from twisted.trial.unittest import TestCase
+
+  #: Declare doctests for Trial.
+  __doctests__ = ['viff.field']
+
+  class GFpElementTestCase(TestCase):
+      """Tests for elements from a Zp field."""
+
+      def setUp(self):
+          """Initialize Zp to Z31."""
+          self.field = GF(31)
+
+      def test_invert(self):
+          """Test inverse operation, including inverting zero."""
+          self.assertRaises(ZeroDivisionError, lambda: ~self.field(0))
+          self.assertEquals(~self.field(1), self.field(1))
+
+      def test_sqrt(self):
+          """Test extraction of square roots."""
+          square = self.field(4)**2
+          root = square.sqrt()
+          self.assertEquals(root**2, square)
+
+This demonstrates the most important features in a simple unit test:
+
+* First the needed definitions are imported as normal.
+
+* Setting the ``__doctest__`` field makes Trial run the doctests_ in
+  the named module.
+
+* A class is defined which inherit from ``TestCase``.
+
+* A ``setUp`` method is used to collect preperations that are needed
+  for every test.
+
+* Several test methods are defined. They make use of the assertions
+  offered by Trial.
+
+.. _doctests: http://docs.python.org/lib/module-doctest.html
+
+
+Tests Involving a VIFF Runtime
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Trial really shines when it comes to testing that involves networking.
+First, it allows us to forget about the networking — the network
+connections are replaced by direct method calls on the receiver's
+transport. This makes the test repeatable unlike if real network
+connections were used since they may fail if they cannot bind to the
+wanted port number.
+
+In VIFF the ``util.py`` file contains the logic needed to connect a
+number of Runtime instances in this way. All you need to do is to
+create a subclass of RuntimeTestCase and decorate the test methods
+with ``protocol`` like this example (abbreviated from
+``viff.test.test_active_runtime``):
+
+.. sourcecode:: python
+
+  from viff.test.util import RuntimeTestCase, protocol
+
+  class ActiveRuntimeTest(RuntimeTestCase):
+      """Test for active security."""
+
+      #: Number of players.
+      num_players = 4
+
+      @protocol
+      def test_broadcast(self, runtime):
+          """Test Bracha broadcast."""
+          if runtime.id == 1:
+              x = runtime.broadcast([1], "Hello world!")
+          else:
+              x = runtime.broadcast([1])
+          x.addCallback(self.assertEquals, "Hello world!")
+          return x
+
+By decorating ``test_broadcast`` with ``protocol`` we ensure that the
+method will be called with a Runtime instance. Furthermore, the method
+will be called ``num_player`` times, each time with another Runtime
+instance. The net result is that the test behaves just like if four
+players had started four programs containing the method body.
+
+In the method you can branch on ``runtime.id``. This is needed in the
+typical case where you want only one of the parties to input something
+to a calculation.
+
+In this example all four parties get an ``x`` which will eventually
+contain the string "Hello World". Using Trial we can return ``x`` and
+Trial will then wait for ``x`` to trigger before declaring the test a
+success or failure. We have attached ``self.assertEquals`` as a
+callback on ``x`` with an extra argument of "Hello World". This means
+that when ``x`` eventually triggers, the assertion is run and the test
+finishes.
+
+This is the real power of Trial. You can do some calculations and
+finish by returning a Deferred (and remember that Shares are Deferreds
+in VIFF). The value of this Deferred is not important, it is only
+important that it triggers when the test is done. You will often need
+to use ``twisted.internet.defer.gatherResults`` to combine several
+Deferreds into one that you can return to Trial. Just make sure that
+your final Deferred depends on all other Deferreds so that you do not
+leave lingering Deferreds behind. Trial will complain loudly if you
+do, so it should be easy to spot.
+
+
+.. include:: layout.rst
--- a/docs/bibliography.txt	Tue Feb 19 22:00:59 2008 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,59 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-==============
- Bibliography
-==============
-
-.. note::
-
-   This list is far from complete. If you find more relevant
-   references then please `send us a mail`__ with the information.
-
-   .. __: mailto:viff-devel@viff.dk
-
-The algorighms used by VIFF are published in various academic papers.
-Here we will try to point out which parts of the code uses which
-papers.
-
-* The ``viff.shamir`` module is obviously based on [Shamir79]_.
-
-*  ``apps/millionaires.py``: Inspired by [Yao82]_.
-
-* The default comparison operation (``Runtime.greater_than_equal``) is
-  based on the comparison protocol from [Toft05]_.
-
-* Broadcast (``Runtime.broadcast``) is based on the original paper by
-  [Bracha84]_ and on the explanation by [Cachin05]_.
-
-* The pseudo-random secret sharing (PRSS) in ``viff.prss`` is
-  described in [CDI05]_.
-
-
-.. [Bracha84] G. Bracha, *An asynchronous [(n-1)/3]-resilient
-   consensus protocol*, Proc 3rd ACM Symposium on Principles of
-   Distributed Computing (PODC), 1984, 154-162.
-
-.. [Cachin05] Christian Cachin, *Security and Fault-tolerance in
-   Distributed Systems*, ETHZ, 2005, PDF__.
-
-   .. __: http://www.zurich.ibm.com/~cca/sft05/agreement.pdf
-
-.. [CDI05] Ronald Cramer, Ivan Damgård, and Yuval Ishai, *Share
-   Conversion, Pseudorandom Secret-Sharing and Applications to Secure
-   Computation*, Proc of TCC 2005, LNCS 3378, PS__.
-
-   .. __:  http://www.cs.technion.ac.il/~yuvali/pubs/CDI05.ps
-
-.. [Shamir79] Adi Shamir, *How to share a secret*, Communications of
-   the ACM, 22 (11): 612-613.
-
-.. [Toft05] Tomas Toft, *Secure Integer Computation with Applications
-   in Economics*, PhD Progress Report, July 2005, PDF__.
-
-   .. __: http://www.daimi.au.dk/~tomas/publications/progress.pdf
-
-.. [Yao82] Andrew Chi-Chih Yao, *Protocols for Secure Computations*,
-   FOCS 1982, 160-164.
-
-
-.. include:: layout.rst
--- a/docs/coding-style.txt	Tue Feb 19 22:00:59 2008 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,56 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-===================
- VIFF Coding Style
-===================
-
-The VIFF code tries to follow the coding style laid out in :PEP:`8`,
-which you should read or at least skim over. You can check your code
-against by running the pep8.py_ checker.
-
-.. _pep8.py: http://svn.browsershots.org/trunk/devtools/pep8/pep8.py
-
-
-The VIFF Coding Style in Short
-------------------------------
-
-A summary of the rules:
-
-* Use four spaces for indention, never tabs.
-
-* Use a single space around binary operators.
-
-* Name classes using ``CamelCase``.
-
-* Name variables, function, and methods using lowercase words like
-  ``foo_bar``.
-
-* Write docstrings for your functions and methods. Include test for
-  doctest_ if possible.
-
-  .. _doctest: http://docs.python.org/lib/module-doctest.html
-
-* Try to be consistent.
-
-These rules are there to make the source code more readable for both
-old and new people.
-
-The Twisted Coding Style
-------------------------
-
-VIFF uses Twisted_ and their code follows a slightly different coding
-style. Their style is closer to the style used in Java where functions
-and methods are named ``fooBar`` instead of ``foo_bar``.
-
-When writing code which is close to Twisted code, you might want to
-follow that style too. If you subclass a Twisted class to override
-some behavior, you might be forced to follow their style.
-
-If you have a choice, then you should only use the Twisted style if
-you expect people to call both your code and the Twisted code — if
-people will only call your code, then please follow the standard VIFF
-coding style.
-
-.. _Twisted: http://twistedmatrix.com/
-
-.. include:: layout.rst
Binary file docs/design-talk.pdf has changed
--- a/docs/index.txt	Tue Feb 19 22:00:59 2008 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,42 +0,0 @@
-
-====================
- VIFF Documentation
-====================
-
-Here you will find some resources about VIFF.
-
-API Documentation
-~~~~~~~~~~~~~~~~~
-
-* The API documentation not only describes the API, but also tries to
-  give a overview of the VIFF architecture.
-
-  Available `online`__.
-
-  .. __: http://viff.dk/api/
-
-* The code examples includes in the ``apps/`` directory also contains
-  many hints on best practices with VIFF. The ``apps/millionaires.py``
-  example is particularly well commented and may serve as a template
-  for new programs.
-
-* The unit tests in the ``viff/test/`` directory will show you many
-  small programs using all of VIFF.
-
-Presentations
-~~~~~~~~~~~~~
-
-* VIFF Design Talk given by Martin Geisler on September 20th, 2007 at
-  a SIMAP_ meeting. The talk describes some of the goals of the VIFF
-  design. It is current to version 0.2 of VIFF.
-
-  Available as PDF__.
-
-  .. _SIMAP: http://simap.dk/
-  .. __: design-talk.pdf
-
-Please `send us`__ any presentations or programs you make.
-
-.. __: mailto:viff-devel@viff.dk
-
-.. include:: layout.rst
--- a/docs/layout.rst	Tue Feb 19 22:00:59 2008 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,11 +0,0 @@
-
-.. header::
-   [ `VIFF Documentation <index.html>`__ ]
-   [ `Coding Style <coding-style.html>`__ ]
-   [ `Unit Testing <unit-testing.html>`__ ]
-   [ `Bibliography <bibliography.html>`__ ]
-
-.. footer::
-   `Return to the VIFF homepage <../index.html>`__.
-
-   .. include:: ../copyright.rst
--- a/docs/unit-testing.txt	Tue Feb 19 22:00:59 2008 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,284 +0,0 @@
-.. -*- coding: utf-8 -*-
-
-==============
- Unit Testing
-==============
-
-VIFF employs a set of unit tests to help developers catch regressions
-and to ensure the correctness of the implementation. VIFF uses the
-Trial_ testing framework, which is part of Twisted. Using Trial has
-the big advantage that it understands Twisted's Deferreds_ — if a unit
-test returns a Deferred, Trial waits for it to trigger before it
-declares the test a success or failure. Please refer to this
-tutorial_ for more information.
-
-.. _Trial: http://twistedmatrix.com/trac/wiki/TwistedTrial
-.. _Deferreds: http://twistedmatrix.com/projects/core/
-               documentation/howto/defer.html
-.. _tutorial: http://twistedmatrix.com/trac/browser/branches/
-              trial-tutorial-2443/doc/core/howto/trial.xhtml?format=raw
-
-Running the Unit Tests
-----------------------
-
-To run the VIFF unit tests you must make sure that ``import viff``
-works correctly in Python. In other words, you must make sure that
-VIFF is installed or that the root of your source tree is in
-``PYTHONPATH``. You can test this by changing to some unrelated
-directory, starting an interactive Python session and run:
-
-.. sourcecode:: pycon
-
-  >>> import viff
-  >>> print viff.__version__
-  0.3
-
-If it fails with an ImportError, then please double-check that your
-``PYTHONPATH`` is setup correctly.
-
-Now simply execute ``trial viff`` to run the unit tests. You should
-get output similar to this:
-
-.. sourcecode:: text
-
-  % trial viff
-  Seeding random generator with random seed 4658
-  Running 65 tests.
-  viff.test.test_active_runtime
-    ActiveRuntimeTest
-      test_broadcast ...                                           [OK]
-  viff.test.test_basic_runtime
-    ProgramCounterTest
-      test_callback ...                                            [OK]
-      test_complex_operation ...                                   [OK]
-      test_initial_value ...                                       [OK]
-      test_multiple_callbacks ...                             [SKIPPED]
-      test_nested_calls ...                                        [OK]
-      test_simple_operation ...                                    [OK]
-  viff.test.test_field
-    GF256TestCase
-      test_add ...                                                 [OK]
-      test_construct ...                                           [OK]
-      test_div ...                                                 [OK]
-      test_field ...                                               [OK]
-      test_invert ...                                              [OK]
-      test_mul ...                                                 [OK]
-      test_neg ...                                                 [OK]
-      test_pow ...                                                 [OK]
-      test_str ...                                                 [OK]
-      test_sub ...                                                 [OK]
-      test_xor ...                                                 [OK]
-    GFpElementTestCase
-      test_add ...                                                 [OK]
-      test_bit ...                                                 [OK]
-      test_div ...                                                 [OK]
-      test_field ...                                               [OK]
-      test_invert ...                                              [OK]
-      test_mul ...                                                 [OK]
-      test_neg ...                                                 [OK]
-      test_sqrt ...                                                [OK]
-      test_str ...                                                 [OK]
-      test_sub ...                                                 [OK]
-  doctest
-    DocTestCase
-      field ...                                                    [OK]
-      GF ...                                                       [OK]
-      __eq__ ...                                                   [OK]
-      __init__ ...                                                 [OK]
-      __nonzero__ ...                                              [OK]
-      __radd__ ...                                                 [OK]
-      __rmul__ ...                                                 [OK]
-  viff.test.test_prss
-    PRSSTestCase
-      test_generate_subsets ...                                    [OK]
-  doctest
-    DocTestCase
-      PRF ...                                                      [OK]
-      __call__ ...                                                 [OK]
-      __init__ ...                                                 [OK]
-      generate_subsets ...                                         [OK]
-      prss ...                                                     [OK]
-  viff.test.test_runtime
-    RuntimeTest
-      test_add ...                                                 [OK]
-      test_add_coerce ...                                          [OK]
-      test_convert_bit_share ...                                   [OK]
-      test_greater_than ...                                        [OK]
-      test_greater_than_equal ...                                  [OK]
-      test_greater_than_equalII ...                                [OK]
-      test_less_than ...                                           [OK]
-      test_less_than_equal ...                                     [OK]
-      test_mul ...                                                 [OK]
-      test_open ...                                                [OK]
-      test_open_no_mutate ...                                      [OK]
-      test_prss_share_bit ...                                      [OK]
-      test_prss_share_int ...                                      [OK]
-      test_prss_share_random_bit ...                               [OK]
-      test_prss_share_random_int ...                               [OK]
-      test_shamir_share ...                                        [OK]
-      test_shamir_share_asymmetric ...                             [OK]
-      test_sub ...                                                 [OK]
-      test_sub_coerce ...                                          [OK]
-      test_xor ...                                                 [OK]
-  doctest
-    DocTestCase
-      share ...                                                    [OK]
-      clone_deferred ...                                           [OK]
-      dlift ...                                                    [OK]
-      find_prime ...                                               [OK]
-
-  =====================================================================
-  [SKIPPED]: viff.test.test_basic_runtime.ProgramCounterTest.
-  test_multiple_callbacks
-
-  TODO: Scheduling callbacks fails to increment program counter!
-  ---------------------------------------------------------------------
-  Ran 65 tests in 18.305s
-
-  PASSED (skips=1, successes=64)
-
-Lots of success! But one of the tests was skipped — we do this when we
-have a test which represents a known problem. Otherwise every test run
-would be cluttered with long of traceback messages, making it
-difficult to notice new *unexpected* failures.
-
-
-Writing Unit Tests
-------------------
-
-The unit tests live in the ``viff.test`` package. There you will find
-a number of modules, which in turn contain classes inheriting from
-``twisted.trial.unittest.TestCase``. Trial recognizes these classes
-and will execute methods starting with ``test``.
-
-Simple Tests
-~~~~~~~~~~~~
-
-Adding a new unit test can be as simple as defining a new method in a
-suitable class. The method will want to assert certain things during
-the test, and for that Trial offers a large number of convenient
-methods such as ``assertEqual``, ``assertTrue``, and so on. The full
-reference is available `online`__. Notice that they describe the
-methods under names like ``failUnlessSomething`` which is aliased to
-``assertSomething``. So far all the VIFF unit tests use the
-``assertSomething`` style, but you are welcome to use the other if you
-prefer.
-
-.. __: http://twistedmatrix.com/documents/current/api/
-       twisted.trial.unittest._Assertions.html
-
-A simple example of a unit test is ``viff.test.test_field`` which
-looks like this (heavily abbreviated):
-
-.. sourcecode:: python
-
-  """Tests for viff.field."""
-
-  from viff.field import GF, GF256
-  from twisted.trial.unittest import TestCase
-
-  #: Declare doctests for Trial.
-  __doctests__ = ['viff.field']
-
-  class GFpElementTestCase(TestCase):
-      """Tests for elements from a Zp field."""
-
-      def setUp(self):
-          """Initialize Zp to Z31."""
-          self.field = GF(31)
-
-      def test_invert(self):
-          """Test inverse operation, including inverting zero."""
-          self.assertRaises(ZeroDivisionError, lambda: ~self.field(0))
-          self.assertEquals(~self.field(1), self.field(1))
-
-      def test_sqrt(self):
-          """Test extraction of square roots."""
-          square = self.field(4)**2
-          root = square.sqrt()
-          self.assertEquals(root**2, square)
-
-This demonstrates the most important features in a simple unit test:
-
-* First the needed definitions are imported as normal.
-
-* Setting the ``__doctest__`` field makes Trial run the doctests_ in
-  the named module.
-
-* A class is defined which inherit from ``TestCase``.
-
-* A ``setUp`` method is used to collect preperations that are needed
-  for every test.
-
-* Several test methods are defined. They make use of the assertions
-  offered by Trial.
-
-.. _doctests: http://docs.python.org/lib/module-doctest.html
-
-
-Tests Involving a VIFF Runtime
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Trial really shines when it comes to testing that involves networking.
-First, it allows us to forget about the networking — the network
-connections are replaced by direct method calls on the receiver's
-transport. This makes the test repeatable unlike if real network
-connections were used since they may fail if they cannot bind to the
-wanted port number.
-
-In VIFF the ``util.py`` file contains the logic needed to connect a
-number of Runtime instances in this way. All you need to do is to
-create a subclass of RuntimeTestCase and decorate the test methods
-with ``protocol`` like this example (abbreviated from
-``viff.test.test_active_runtime``):
-
-.. sourcecode:: python
-
-  from viff.test.util import RuntimeTestCase, protocol
-
-  class ActiveRuntimeTest(RuntimeTestCase):
-      """Test for active security."""
-
-      #: Number of players.
-      num_players = 4
-
-      @protocol
-      def test_broadcast(self, runtime):
-          """Test Bracha broadcast."""
-          if runtime.id == 1:
-              x = runtime.broadcast([1], "Hello world!")
-          else:
-              x = runtime.broadcast([1])
-          x.addCallback(self.assertEquals, "Hello world!")
-          return x
-
-By decorating ``test_broadcast`` with ``protocol`` we ensure that the
-method will be called with a Runtime instance. Furthermore, the method
-will be called ``num_player`` times, each time with another Runtime
-instance. The net result is that the test behaves just like if four
-players had started four programs containing the method body.
-
-In the method you can branch on ``runtime.id``. This is needed in the
-typical case where you want only one of the parties to input something
-to a calculation.
-
-In this example all four parties get an ``x`` which will eventually
-contain the string "Hello World". Using Trial we can return ``x`` and
-Trial will then wait for ``x`` to trigger before declaring the test a
-success or failure. We have attached ``self.assertEquals`` as a
-callback on ``x`` with an extra argument of "Hello World". This means
-that when ``x`` eventually triggers, the assertion is run and the test
-finishes.
-
-This is the real power of Trial. You can do some calculations and
-finish by returning a Deferred (and remember that Shares are Deferreds
-in VIFF). The value of this Deferred is not important, it is only
-important that it triggers when the test is done. You will often need
-to use ``twisted.internet.defer.gatherResults`` to combine several
-Deferreds into one that you can return to Trial. Just make sure that
-your final Deferred depends on all other Deferreds so that you do not
-leave lingering Deferreds behind. Trial will complain loudly if you
-do, so it should be easy to spot.
-
-
-.. include:: layout.rst