Utility Functions Module

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.

VIFF_SEED

The rand random generator is seeded using this environment variable, if it is defined.

viff.util.rand

All VIFF code uses this random number generator for all randomness needed.

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 run cannot be reproduced exactly.

VIFF_PROFILE

Defining this variable will change profile() from a no-op to real decorator.

viff.util.begin(result, phase)

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 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.

viff.util.clone_deferred(original)

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) 
<Deferred at 0x...>
>>> y = clone_deferred(x)
>>> y.addCallback(lambda result: result + 1)  
<Deferred at 0x...>
>>> x.addCallback(lambda result: result + 2)  
<Deferred at 0x...>
>>> x.callback(1)
>>> x                                         
<Deferred at 0x...  current result: 12>
>>> y                                         
<Deferred at 0x...  current result: 11>
viff.util.deprecation(message)

Issue a deprecation warning.

viff.util.dlift(func)

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                                         
<DeferredList at 0x...  current result: 150>
viff.util.dprint(*args, **kwargs)

Lifted wrapper function.

viff.util.end(result, phase)

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.

viff.util.fake(replacement)

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.

viff.util.find_prime(lower_bound, blum=False)

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
viff.util.find_random_prime(k)

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
viff.util.if_then(cond, a, b)

If then else operator works both for integers and for shares.

>>> if_then(0, 3, 6)
6
>>> if_then(1, 3, 6)
3
viff.util.memory_usage()

Read memory usage of the current process.

viff.util.profile(method)

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.

viff.util.rand = <random.Random object at 0x3333320>

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.

viff.util.track_memory_usage()

Print memory usage if changed since last time.

viff.util.wrapper(func)

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.

Previous topic

Implementation

Next topic

Finite Fields Module

This Page