Package viff :: Module util
[hide private]
[frames] | no frames]

Module util

source code

Miscellaneous utility functions. This module contains various utility functions used in all parts of the VIFF code. The most important is the rand random generator which is seeded with a known seed each time. Using this generator for all random numbers ensures that a protocol run can be reproduced at a later time.
Classes [hide private]
  deep_wait
Functions [hide private]
 
wrapper(func)
Decorator used for wrapper functions.
source code
 
fake(replacement)
Replace a function with a fake version.
source code
 
deprecation(message)
Issue a deprecation warning.
source code
 
dlift(func)
Lift a function to handle deferred arguments.
source code
 
dprint(*args, **kwargs)
Lifted wrapper function.
source code
 
clone_deferred(original)
Clone a Deferred.
source code
 
find_prime(lower_bound, blum=False)
Find a prime above a lower bound.
source code
 
find_random_prime(k)
Find a random k bit prime number.
source code
 
begin(result, phase)
Begin a phase.
source code
 
end(result, phase)
End a phase.
source code
 
profile(method)
Profiling decorator.
source code
 
memory_usage()
Read memory usage of the current process.
source code
 
track_memory_usage()
Print memory usage if changed since last time.
source code
 
if_then(cond, a, b)
If then else operator works both for integers and for shares.
source code
Variables [hide private]
  _seed = 8086
Seed for rand.
  rand = random.Random(_seed)
Random number generator used by all VIFF code.
  PHASES = {}
  _last_memory_usage = None
Function Details [hide private]

wrapper(func)

source code 

Decorator used for wrapper functions.

It is important to use this decorator on any wrapper functions in order to ensure that they end up with correct __name__ and __doc__ attributes.

In addition, if the environment variable VIFF_NO_WRAP is defined, then the wrapper functions will be turned into functions that do not wrap -- instead they let their argument function through unchanged. This is done so that epydoc and Sphinx can see the true function arguments when generating documentation. Just remember that your code will break if VIFF_NO_WRAP is set, so it should only be used when documentation is being generated.

fake(replacement)

source code 

Replace a function with a fake version.

This decorator is meant to be used for profiling where specific functions can be replaced with fake versions that are faster. The fake version should take the same input as the original function and deliver output of the correct type.

The environment variable VIFF_FAKE must be set to enable this decorator. The variable is treated as a list of function names, separated on whitespace. Setting VIFF_FAKE to the special value * will enable all fake replacements known.

dlift(func)

source code 

Lift a function to handle deferred arguments.

Use this as a decorator. The decorated function accepts the same arguments as the original function, but arguments for the lifted function can be Deferreds. The return value of the lifted function will always be a Deferred.

Keyword arguments are not lifted.

As an example, here is how to define a lazy addition and multiplication which works for integers (deferred or not):

>>> @dlift
... def add(a, b):
...     return a + b
...
>>> @dlift
... def mul(a, b):
...     return a * b
...
>>> x = Deferred()
>>> y = Deferred()
>>> z = mul(add(x, 10), y)
>>> x.callback(5)
>>> y.callback(10)
>>> z                                         # doctest: +ELLIPSIS
<DeferredList at 0x...  current result: 150>

dprint(*args, **kwargs)

source code 
Lifted wrapper function.
Decorators:
  • @dlift

clone_deferred(original)

source code 

Clone a Deferred.

The returned clone will fire with the same result as the original Deferred, but will otherwise be independent.

It is an error to call callback on the clone as it will result in an AlreadyCalledError when the original Deferred is triggered.

>>> x = Deferred()
>>> x.addCallback(lambda result: result * 10) # doctest: +ELLIPSIS
<Deferred at 0x...>
>>> y = clone_deferred(x)
>>> y.addCallback(lambda result: result + 1)  # doctest: +ELLIPSIS
<Deferred at 0x...>
>>> x.addCallback(lambda result: result + 2)  # doctest: +ELLIPSIS
<Deferred at 0x...>
>>> x.callback(1)
>>> x                                         # doctest: +ELLIPSIS
<Deferred at 0x...  current result: 12>
>>> y                                         # doctest: +ELLIPSIS
<Deferred at 0x...  current result: 11>

find_prime(lower_bound, blum=False)

source code 

Find a prime above a lower bound.

If a prime is given as the lower bound, then this prime is returned:

>>> find_prime(37)
37L

The bound can be a Python expression as a string. This makes it easy for users to specify command line arguments that generates primes of a particular bit length:

>>> find_prime("2**100") # 100 bit prime
1267650600228229401496703205653L

Blum primes (a prime p such that p % 4 == 3) can be found as well:

>>> find_prime(12)
13L
>>> find_prime(12, blum=True)
19L

If the bound is negative, 2 (the smallest prime) is returned:

>>> find_prime(-100)
2L

find_random_prime(k)

source code 

Find a random k bit prime number.

The prime may have fewer, but no more, than k significant bits:

>>> 2 <= find_random_prime(10) < 2**10
True

begin(result, phase)

source code 

Begin a phase.

You can define program phases for the purpose of profiling a program execution. Use end with a matching phase to record the ending of a phase. The profile decorator makes it easy to wrap a Runtime <viff.runtime.Runtime> method in matching begin/end calls.

The result argument is passed through, which makes it possible to add this function as a callback for a Deferred.

end(result, phase)

source code 

End a phase.

This is the counter-part for begin. It prints the name and the duration of the phase.

The result argument is passed through, which makes it possible to add this function as a callback for a Deferred.

profile(method)

source code 

Profiling decorator.

Add this decorator to a method in order to trace method entry and exit. If the method returns a Deferred, the method exit is recorded when the Deferred fires.

In addition to adding this decorator, you must run the programs in an environment with VIFF_PROFILE defined. Otherwise the decorator is a no-op and has no runtime overhead.


Variables Details [hide private]

rand

Random number generator used by all VIFF code.

The generator is by default initialized with a random seed, unless the environment variable VIFF_SEED is set to a value, in which case that value is used instead. If VIFF_SEED is defined, but empty, then no seed is used and a protocol cannot be reproduced exactly.

Value:
random.Random(_seed)