cgul_random_lcg32.h File Reference

32-bit PRNG (LCG) More...

#include "cgul_common.h"
#include "cgul_exception.h"
#include "cgul_int.h"
Include dependency graph for cgul_random_lcg32.h:
This graph shows which files directly or indirectly include this file:

Typedefs

typedef typedefCGUL_BEGIN_C struct cgul_random_lcg32 * cgul_random_lcg32_t
 

Functions

CGUL_EXPORT cgul_random_lcg32_t cgul_random_lcg32__new (cgul_exception_t *cex)
 
CGUL_EXPORT cgul_random_lcg32_t cgul_random_lcg32__new_from_seed (cgul_exception_t *cex, cgul_uint32_t seed)
 
CGUL_EXPORT cgul_random_lcg32_t cgul_random_lcg32__new_from_seed_array (cgul_exception_t *cex, cgul_uint32_t *seeds)
 
CGUL_EXPORT void cgul_random_lcg32__delete (cgul_random_lcg32_t r)
 
CGUL_EXPORT void cgul_random_lcg32__allocate_seed_array (cgul_exception_t *cex, cgul_uint32_t **v, unsigned int *v_count)
 
CGUL_EXPORT cgul_uint32_t cgul_random_lcg32__next (cgul_exception_t *cex, cgul_random_lcg32_t r)
 
CGUL_EXPORT cgul_uint32_t cgul_random_lcg32__next_in_range (cgul_exception_t *cex, cgul_random_lcg32_t r, cgul_uint32_t range_max)
 
CGUL_EXPORT double cgul_random_lcg32__next_in_unit (cgul_exception_t *cex, cgul_random_lcg32_t r)
 

Detailed Description

32-bit linear congruential pseudo-random number generator. This is the PRNG of last resort. If possible, use any of the other 32-bit PRNGs before using this one. This PRNG is a combination of two LCGs and one Weyl Generator. The way the generators are combined should produce a period that is a little less than 2^96, and it should also eliminate the problems that most other LCGs have with the low-order bits not being very random. This PRNG is mostly used for seeding the other PRNGs.

Author
Paul Serice

Typedef Documentation

§ cgul_random_lcg32_t

typedef typedefCGUL_BEGIN_C struct cgul_random_lcg32* cgul_random_lcg32_t

Opaque pointer to a cgul_random_lcg32 instance.

Function Documentation

§ cgul_random_lcg32__new()

CGUL_EXPORT cgul_random_lcg32_t cgul_random_lcg32__new ( cgul_exception_t cex)

This is a convenience function for creating a new cgul_random_lcg32 object seeding it with the value returned by time(), i.e., the 32-bit seconds since the epoch. The caller is responsible for freeing the object by calling cgul_random_lcg32__delete(). If memory cannot be allocated, NULL is returned, and an exception is thrown.

Parameters
[in,out]cexc-style exception
Returns
new cgul_random_lcg32 instance
See also
cgul_random_lcg32__new_from_seed()
cgul_random_lcg32__new_from_seed_array()

Referenced by cgul_random_lcg32_cxx::cgul_random_lcg32_cxx().

§ cgul_random_lcg32__new_from_seed()

CGUL_EXPORT cgul_random_lcg32_t cgul_random_lcg32__new_from_seed ( cgul_exception_t cex,
cgul_uint32_t  seed 
)

This is a convenience function for creating a new cgul_random_lcg32 object seeding it with seed. The caller is responsible for freeing the object by calling cgul_random_lcg32__delete(). If memory cannot be allocated, NULL is returned, and an exception is thrown.

Parameters
[in,out]cexc-style exception
[in]seedseed value
Returns
new cgul_random_lcg32 instance
See also
cgul_random_lcg32__new_from_seed_array()

Referenced by cgul_random_lcg32_cxx::cgul_random_lcg32_cxx().

§ cgul_random_lcg32__new_from_seed_array()

CGUL_EXPORT cgul_random_lcg32_t cgul_random_lcg32__new_from_seed_array ( cgul_exception_t cex,
cgul_uint32_t *  seeds 
)

This is the correct way to create a new cgul_random_lcg32 object by seeding it with the seeds array. The caller is responsible for freeing the object by calling cgul_random_lcg32__delete(). If memory cannot be allocated, NULL is returned, and an exception is thrown.

The caller is responsible for making sure seeds has the correct number of elements. The easiest way to do this is by using cgul_random_lcg32__allocate_seed_array() to allocate the array and get its size.

Parameters
[in,out]cexc-style exception
[in]seedsarray of 32-bit values used to seed the PRNG
Returns
new cgul_random_lcg32 instance
See also
cgul_random_lcg32__allocate_seed_array()

Referenced by cgul_random_lcg32_cxx::cgul_random_lcg32_cxx().

§ cgul_random_lcg32__delete()

CGUL_EXPORT void cgul_random_lcg32__delete ( cgul_random_lcg32_t  r)

This method frees all internally allocated memory. Do not attempt to dereference r after calling this method.

Parameters
[in]rcgul_random_lcg32 instance

Referenced by cgul_random_lcg32_cxx::set_obj(), and cgul_random_lcg32_cxx::~cgul_random_lcg32_cxx().

§ cgul_random_lcg32__allocate_seed_array()

CGUL_EXPORT void cgul_random_lcg32__allocate_seed_array ( cgul_exception_t cex,
cgul_uint32_t **  v,
unsigned int *  v_count 
)

This function allocates and returns an array of 32-bit seed values v where each element of the array is initialized to zero. The total number of 32-bit seed values in the array is returned in v_count. The caller should fill the array with true random values and create a new PRNG seeded with the values by calling cgul_random_lcg32__new_from_seed_array(). The caller is responsible for calling free(*v). If an error occurs, an exception is thrown.

Parameters
[in,out]cexc-style exception
[out]vuninitialized array of 32-bit seed values
[out]v_countcount of the number of 32-bit values in v

Referenced by cgul_random_lcg32_cxx::allocate_seed_array().

§ cgul_random_lcg32__next()

CGUL_EXPORT cgul_uint32_t cgul_random_lcg32__next ( cgul_exception_t cex,
cgul_random_lcg32_t  r 
)

Return the next element in the pseudo-random number sequence. The random numbers returned are 32 bits wide and should have a period that is a little less than 2^96. Also, the way the LCGs are combined should eliminate the problems that most other LCGs have with the low-order bits not being very random.

Parameters
[in]cexc-style exception
[in]rcgul_random_lcg32 instance
Returns
next element in the random number sequence
See also
cgul_random_lcg32__next_in_range()
cgul_random_lcg32__next_in_unit()

Referenced by cgul_random_lcg32_cxx::next().

§ cgul_random_lcg32__next_in_range()

CGUL_EXPORT cgul_uint32_t cgul_random_lcg32__next_in_range ( cgul_exception_t cex,
cgul_random_lcg32_t  r,
cgul_uint32_t  range_max 
)

If the value returned by cgul_random_lcg32__next() is not the exact range that is needed, this method can limit the return value to [0, range_max). If range_max is zero, an exception is thrown.

This function should avoid the very small round off error associated with just scaling the value returned by cgul_random_lcg32__next_in_unit(); however, this function is much slower.

Parameters
[in,out]cexc-style exception
[in]rcgul_random_lcg32 instance
[in]range_maxexclusive limit on the maximum value returned
Returns
next element in the random number sequence

Referenced by cgul_random_lcg32_cxx::next_in_range().

§ cgul_random_lcg32__next_in_unit()

CGUL_EXPORT double cgul_random_lcg32__next_in_unit ( cgul_exception_t cex,
cgul_random_lcg32_t  r 
)

Return the next element in the pseudo-random number sequence as type double on the range [0 - 1).

Parameters
[in]cexc-style exception
[in]rcgul_random_lcg32 instance
Returns
next element in the random number sequence

Referenced by cgul_random_lcg32_cxx::next_in_unit().