Page MenuHomeWickedGov Phorge

randomness.rst
No OneTemporary

Size
3 KB
Referenced Files
None
Subscribers
None

randomness.rst

.. _randomness:
Randomness
==========
Eris allow multiple sources of randomness, with the requirements that they must accept a seed for reproducibility. Therefore, sequence Pseudo Random Number Generators (PRNG) are used instead of Cryptographically Secure PRNG, which would provide no additional value in generating test cases but make impossible to run the same test twice.
The supported random number generators are:
* the ``rand`` PHP function: this is the default, and simpler, choice.
* the ``mt_rand`` PHP function: this is a faster PRNG.
* the PHP code implementation ``purePhpMtRand()`` is equivalent to ``mt_rand``.
Being implemented inside a PHP object, ``purePhpMtRand()`` allows to isolate its state while the first two implementations modify the global state of the PHP process. Use ``purePhpMtRand()`` when your code calls ``rand()`` or ``mt_rand()`` and you don't want it to interact with the testing framework.
Configuration
-------------
.. literalinclude:: ../examples/RandConfigurationTest.php
:language: php
``testUsingTheDefaultRandFunction`` specifies the ``rand`` variant, but is equivalent to not calling ``withRand()`` at all. ``srand`` is the corresponding seed function.
``testUsingTheDefaultMtRandFunction`` configured ``mt_rand`` and ``mt_srand`` as its seed function.
``testUsingThePurePhpMtRandFunction`` configures ``purePhpMtRand()``.
.. _randomness-size:
Maximum sizes
-------------
The size that can be set and actually reached with ``withMaxSize()`` is limited by the chosen PRNG.
* For ``rand`` the maximum values is the result of ``getrandmax()``, which is platform dependent but usually 2^31-1.
* For ``mt_rand`` the maximum value is the result of ``mt_getrandmax()``, which is also platform dependent but usually 2^31-1.
* For ``purePhpMtRand()``, being implemented in PHP code, the maximum value is 2^32-1.
The limitation on size depends not only on the processor architecture but also on the parameters of the algorithm. Both ``mt_rand`` and `purePhpMtRand()`` implement `MT19937`_, which generates 32-bit integers that can be scaled on any smaller interval.
However, according to the `PHP source code`_, ``mt_rand`` implementations uses a lower limit for backward compatibility with ``rand``. ``purePhpMtRand()`` has no need for backward compatibility and chooses to allow numbers up to 2^32-1, which is the maximum unsigned number representable with 32 bit.
.. _MT19937: https://en.wikipedia.org/wiki/Mersenne_Twister
.. _PHP source code: https://github.com/php/php-src/blob/master/ext/standard/rand.c#L361
Seeding
-------
The PRNGS are seeded using the ``microtime()`` of the system, or with the ``ERIS_SEED`` environment variable for :ref:`test reproducibility<reproducibility>`.
Comparison
----------
==================== ================ ====== ============
Variant Portability Speed Global state
==================== ================ ====== ============
``rand`` PHP core Slow Yes
``mt_rand`` PHP core Fast Yes
``purePhpMtRand()`` Eris source code Medium No
==================== ================ ====== ============

File Metadata

Mime Type
text/plain
Expires
Oct 5 2026, 02:47 (6 w, 2 d ago)
Storage Engine
local-disk
Storage Format
Raw Data
Storage Handle
15/39/8acfe5bcc1424fe5e859c3805fae
Default Alt Text
randomness.rst (3 KB)

Event Timeline