Hasard engine API

Warning

This documentation is outdated (Hasard version 0.6). Ask Hasard author to update it, or read directly Hasard source code.

Hasard library supports multiple “engines”. An engine is an algorithm responsible to generate pseudo-random numbers.

Engine API is the private header engine.h (see also internals.h and engines.c).

Initialization

An engine is initialized using hasard_engine_init() function. This function calls the engine constructor found in the hasard_engines list. The constructor, eg. hasard_mersenne_twister_init(), allocates memory to store the engine internal state, setup attributes (eg. tick_max) and, the most important point, set the pseudo-random generator seed. The seed is created using hasard->seed engine: an hardware generator (eg. /dev/random).

On error, the constructor returns the number 1. Otherwise, it returns zero. You can use hasard->error(...) to display an error message.

Destruction

On exit or when the user changes the current engine, the engine is destroyed using hasard_engine_deinit). It calls the engine destructor if the engine has a destructor (eg. hasard_linux_dev_deinit). And then the engine internal state memory is freed.

Pseudo-random number generation

An engine have to implement at least one method to generate pseudo-random numbers: “tick” or “bytes”. Both it’s possible to use both, hasard will choose the faster generator for each user request.

Generation using ticks

The engine have to setup three attributes:

  • ticks: the function callback
  • tick_max: the maximum value of a tick (minimum is always zero)
  • tick_bits: the minimum number of random bits in a tick

A tick is an unsigned integer in range [0; tick_max].

If your engine is generating numbers in [a; b] where a is not nul (eg. Park-Miller), substract the value “a” to get the output range [0; b-a].

Generation using bytes

An engine can also choose to generate unsigned bytes. The engine just have to setup the “bytes” function callback. The engine have to fill all requested bytes.