(a6379032ee98bc43fb68ce7a6c186f3512558ce0)

#include "ruby/ruby.h"

Include dependency graph for random.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	rb_random_struct
	Base components of the random interface. More...

struct	rb_random_interface_t
	PRNG algorithmic interface, analogous to Ruby level classes. More...

Macros
#define	RUBY_RANDOM_INTERFACE_VERSION_MAJOR 1

#define	RUBY_RANDOM_INTERFACE_VERSION_MINOR 0

#define	RUBY_RANDOM_PASTE_VERSION_SUFFIX(x, y, z) x##_##y##_##z

#define	RUBY_RANDOM_WITH_VERSION_SUFFIX(name, major, minor) RUBY_RANDOM_PASTE_VERSION_SUFFIX(name, major, minor)

#define	rb_random_data_type

#define	RUBY_RANDOM_INTERFACE_VERSION_INITIALIZER {RUBY_RANDOM_INTERFACE_VERSION_MAJOR, RUBY_RANDOM_INTERFACE_VERSION_MINOR}

#define	RUBY_RANDOM_INTERFACE_VERSION_MAJOR_MAX 0xff

#define	RUBY_RANDOM_INTERFACE_VERSION_MINOR_MAX 0xff

#define	RB_RANDOM_INTERFACE_DECLARE(prefix)
	This utility macro defines 4 functions named prefix_init, prefix_init_int32, prefix_get_int32, prefix_get_bytes.

#define	RB_RANDOM_INTERFACE_DECLARE_WITH_REAL(prefix)
	Identical to RB_RANDOM_INTERFACE_DECLARE except it also declares prefix_get_real.

#define	RB_RANDOM_INTERFACE_DEFINE(prefix)
	This utility macro expands to the names declared using RB_RANDOM_INTERFACE_DECLARE.

#define	RB_RANDOM_INTERFACE_DEFINE_WITH_REAL(prefix)
	Identical to RB_RANDOM_INTERFACE_DEFINE except it also defines prefix_get_real.

#define	RB_RANDOM_DEFINE_INIT_INT32_FUNC(prefix)

#define	RB_RANDOM_PARENT &rb_random_data_type
	This utility macro can be used when you define your own PRNG type:

#define	RB_RANDOM_DATA_INIT_PARENT(random_data) rbimpl_random_data_init_parent(&random_data)
	This macro is expected to be called exactly once at the beginning of a program, possibly from inside of your `Init_Foo()` function.

Typedefs
typedef struct rb_random_struct	rb_random_t

typedef void	rb_random_init_func(rb_random_t rng, const uint32_t buf, size_t len)
	This is the type of functions called when your random object is initialised.

typedef void	rb_random_init_int32_func(rb_random_t *rng, uint32_t data)
	This is the type of functions called when your random object is initialised.

typedef unsigned int	rb_random_get_int32_func(rb_random_t *rng)
	This is the type of functions called from your object's `#rand` method.

typedef void	rb_random_get_bytes_func(rb_random_t rng, void buf, size_t len)
	This is the type of functions called from your object's `#bytes` method.

typedef double	rb_random_get_real_func(rb_random_t *rng, int excl)
	This is the type of functions called from your object's `#rand` method.

typedef const rb_data_type_t	rb_random_data_type_t
	This is the type of rb_random_data_type.

Functions
void	rb_random_mark (void *ptr)
	This is the implementation of rb_data_type_struct::dmark for rb_random_data_type.

void	rb_random_base_init (rb_random_t *rnd)
	Initialises an allocated rb_random_t instance.

double	rb_int_pair_to_real (uint32_t a, uint32_t b, int excl)
	Generates a 64 bit floating point number by concatenating two 32bit unsigned integers.

void	rb_rand_bytes_int32 (rb_random_get_int32_func func, rb_random_t prng, void *buff, size_t size)
	Repeatedly calls the passed function over and over again until the passed buffer is filled with random bytes.

static const rb_random_interface_t *	rb_rand_if (VALUE obj)
	Queries the interface of the passed random object.

Variables
const rb_data_type_t	rb_random_data_type
	The data that holds the backend type of rb_cRandom.

Detailed Description

Date: Sat May 7 11:51:14 JST 2016

Copyright: 2007-2020 Yukihiro Matsumoto; This file is a part of the programming language Ruby. Permission is hereby granted, to either redistribute and/or modify this file, provided that the conditions mentioned in the file COPYING are met. Consult the file for details.

This is a set of APIs to roll your own subclass of rb_cRandom. An illustrative example of such PRNG can be found at ext/-test-/random/loop.c.

Definition in file random.h.

Macro Definition Documentation

◆ RB_RANDOM_DATA_INIT_PARENT

#define RB_RANDOM_DATA_INIT_PARENT ( random_data ) rbimpl_random_data_init_parent(&random_data)

This macro is expected to be called exactly once at the beginning of a program, possibly from inside of your Init_Foo() function.

Depending on platforms RB_RANDOM_PARENT can require a fixup. This routine does that when necessary.

Definition at line 265 of file random.h.

◆ rb_random_data_type

#define rb_random_data_type

Value:

    RUBY_RANDOM_WITH_VERSION_SUFFIX(rb_random_data_type, \
                                    RUBY_RANDOM_INTERFACE_VERSION_MAJOR, \
                                    RUBY_RANDOM_INTERFACE_VERSION_MINOR)

Definition at line 30 of file random.h.

◆ RB_RANDOM_DEFINE_INIT_INT32_FUNC

#define RB_RANDOM_DEFINE_INIT_INT32_FUNC ( prefix )

Value:

    static void prefix##_init_int32(rb_random_t *rnd, uint32_t data) \
    { \
        prefix##_init(rnd, &data, 1); \
    }

Definition at line 225 of file random.h.

◆ RB_RANDOM_INTERFACE_DECLARE

#define RB_RANDOM_INTERFACE_DECLARE ( prefix )

Value:

    static void prefix##_init(rb_random_t *, const uint32_t *, size_t); \
    static void prefix##_init_int32(rb_random_t *, uint32_t); \
    static unsigned int prefix##_get_int32(rb_random_t *); \
    static void prefix##_get_bytes(rb_random_t *, void *, size_t)

This utility macro defines 4 functions named prefix_init, prefix_init_int32, prefix_get_int32, prefix_get_bytes.

Definition at line 182 of file random.h.

◆ RB_RANDOM_INTERFACE_DECLARE_WITH_REAL

#define RB_RANDOM_INTERFACE_DECLARE_WITH_REAL ( prefix )

Value:

RB_RANDOM_INTERFACE_DECLARE(prefix); \

static double prefix##_get_real(rb_random_t *, int)

RB_RANDOM_INTERFACE_DECLARE

#define RB_RANDOM_INTERFACE_DECLARE(prefix)

This utility macro defines 4 functions named prefix_init, prefix_init_int32, prefix_get_int32,...

Definition random.h:182

Identical to RB_RANDOM_INTERFACE_DECLARE except it also declares prefix_get_real.

Definition at line 192 of file random.h.

◆ RB_RANDOM_INTERFACE_DEFINE

#define RB_RANDOM_INTERFACE_DEFINE ( prefix )

Value:

    RUBY_RANDOM_INTERFACE_VERSION_INITIALIZER, 0, \
    prefix##_init, \
    prefix##_init_int32, \
    prefix##_get_int32, \
    prefix##_get_bytes

This utility macro expands to the names declared using RB_RANDOM_INTERFACE_DECLARE.

Expected to be used inside of a rb_random_interface_t initialiser:

RB_RANDOM_INTERFACE_DECLARE(foo);
 
static inline constexpr rb_random_interface_t foo_interface = {
    32768, // bits
    RB_RANDOM_INTERFACE_DEFINE(foo),
};

Definition at line 210 of file random.h.

◆ RB_RANDOM_INTERFACE_DEFINE_WITH_REAL

#define RB_RANDOM_INTERFACE_DEFINE_WITH_REAL ( prefix )

Value:

RB_RANDOM_INTERFACE_DEFINE(prefix), \

prefix##_get_real

Identical to RB_RANDOM_INTERFACE_DEFINE except it also defines prefix_get_real.

Definition at line 221 of file random.h.

◆ RB_RANDOM_PARENT

#define RB_RANDOM_PARENT &rb_random_data_type

This utility macro can be used when you define your own PRNG type:

static inline constexpr rb_random_interface_t your_if = {
    0, RB_RANDOM_INTERFACE_DEFINE(your),
};
 
static inline constexpr rb_random_data_type_t your_prng_type = {
    "your PRNG",
    { rb_random_mark, },
    RB_RANDOM_PARENT,                 // <<-- HERE
    &your_if,
    0,
}

Definition at line 256 of file random.h.

◆ RUBY_RANDOM_INTERFACE_VERSION_INITIALIZER

#define RUBY_RANDOM_INTERFACE_VERSION_INITIALIZER {RUBY_RANDOM_INTERFACE_VERSION_MAJOR, RUBY_RANDOM_INTERFACE_VERSION_MINOR}

Definition at line 34 of file random.h.

◆ RUBY_RANDOM_INTERFACE_VERSION_MAJOR

#define RUBY_RANDOM_INTERFACE_VERSION_MAJOR 1

Definition at line 24 of file random.h.

◆ RUBY_RANDOM_INTERFACE_VERSION_MAJOR_MAX

#define RUBY_RANDOM_INTERFACE_VERSION_MAJOR_MAX 0xff

Definition at line 36 of file random.h.

◆ RUBY_RANDOM_INTERFACE_VERSION_MINOR

#define RUBY_RANDOM_INTERFACE_VERSION_MINOR 0

Definition at line 25 of file random.h.

◆ RUBY_RANDOM_INTERFACE_VERSION_MINOR_MAX

#define RUBY_RANDOM_INTERFACE_VERSION_MINOR_MAX 0xff

Definition at line 37 of file random.h.

◆ RUBY_RANDOM_PASTE_VERSION_SUFFIX

#define RUBY_RANDOM_PASTE_VERSION_SUFFIX	(	x,
		y,
		z
	)	x##_##y##_##z

Definition at line 27 of file random.h.

◆ RUBY_RANDOM_WITH_VERSION_SUFFIX

#define RUBY_RANDOM_WITH_VERSION_SUFFIX	(	name,
		major,
		minor
	)	RUBY_RANDOM_PASTE_VERSION_SUFFIX(name, major, minor)

Definition at line 28 of file random.h.

Typedef Documentation

◆ rb_random_data_type_t

typedef const rb_data_type_t rb_random_data_type_t

This is the type of rb_random_data_type.

Definition at line 237 of file random.h.

◆ rb_random_get_bytes_func

typedef void rb_random_get_bytes_func(rb_random_t *rng, void *buf, size_t len)

This is the type of functions called from your object's #bytes method.

Parameters

[out]	rng	Your random struct to extract an integer from.
[out]	buf	Return buffer of at least `len` bytes length.
[in]	len	Number of bytes of `buf`.

Postcondition: rng is consumed somehow.; buf is filled with random bytes.

Definition at line 100 of file random.h.

◆ rb_random_get_int32_func

typedef unsigned int rb_random_get_int32_func(rb_random_t *rng)

This is the type of functions called from your object's #rand method.

Parameters

[out] rng Your random struct to extract an integer from.

Returns: A random number.

Postcondition: rng is consumed somehow.

Definition at line 88 of file random.h.

◆ rb_random_get_real_func

typedef double rb_random_get_real_func(rb_random_t *rng, int excl)

This is the type of functions called from your object's #rand method.

Parameters

[out]	rng	Your random struct to extract an integer from.
[in]	excl	Pass nonzero value here to indicate you don't want 1.0.

Returns: A random number of range 0.0 to 1.0.

Postcondition: rng is consumed somehow.

Definition at line 111 of file random.h.

◆ rb_random_init_func

typedef void rb_random_init_func(rb_random_t *rng, const uint32_t *buf, size_t len)

This is the type of functions called when your random object is initialised.

Passed buffer is the seed object basically. But in Ruby a number can be really big. This type of functions accept such big integers as a series of machine words.

Parameters

[out]	rng	Your random struct to fill in.
[in]	buf	Seed, maybe converted from a bignum.
[in]	len	Number of words of `buf`.

Postcondition: rng is initialised using the passed seeds.

Definition at line 67 of file random.h.

◆ rb_random_init_int32_func

typedef void rb_random_init_int32_func(rb_random_t *rng, uint32_t data)

This is the type of functions called when your random object is initialised.

Passed data is the seed integer.

Parameters

[out]	rng	Your random struct to fill in.
[in]	data	Seed, single word.

Postcondition: rng is initialised using the passed seeds.

Definition at line 78 of file random.h.

◆ rb_random_t

typedef struct rb_random_struct rb_random_t

See also: rb_random_struct

Definition at line 53 of file random.h.

Function Documentation

◆ rb_int_pair_to_real()

double rb_int_pair_to_real	(	uint32_t	a,
		uint32_t	b,
		int	excl
	)

Generates a 64 bit floating point number by concatenating two 32bit unsigned integers.

Parameters

[in]	a	Most significant 32 bits of the result.
[in]	b	Least significant 32 bits of the result.
[in]	excl	Whether the result should exclude 1.0 or not.

Returns: A double, whose range is either [0, 1) or [0, 1].

See also: rb_random_interface_t::get_real()

Definition at line 1163 of file random.c.

◆ rb_rand_bytes_int32()

void rb_rand_bytes_int32	(	rb_random_get_int32_func *	func,
		rb_random_t *	prng,
		void *	buff,
		size_t	size
	)

Repeatedly calls the passed function over and over again until the passed buffer is filled with random bytes.

Parameters

[in]	func	Generator function.
[out]	prng	Passed as-is to `func`.
[out]	buff	Return buffer.
[in]	size	Number of words of `buff`.

Postcondition: buff is filled with random bytes.; prng is updated by func.

See also: rb_random_interface_t::get_bytes()

Definition at line 1309 of file random.c.

Referenced by rb_rand_bytes_int32().

◆ rb_rand_if()

static const rb_random_interface_t * rb_rand_if ( VALUE obj )

inlinestatic

Queries the interface of the passed random object.

Parameters

[in] obj An instance (of a subclass) of rb_cRandom.

Returns: Its corresponding rb_random_interface_t interface.

Definition at line 333 of file random.h.

◆ rb_random_base_init()

void rb_random_base_init ( rb_random_t * rnd )

Initialises an allocated rb_random_t instance.

Call it from your own initialiser appropriately.

Parameters

[out] rnd Your PRNG's base part.

Postcondition: rnd is filled with an initial state.

Definition at line 345 of file random.c.

◆ rb_random_mark()

void rb_random_mark ( void * ptr )

This is the implementation of rb_data_type_struct::dmark for rb_random_data_type.

In case your PRNG does not involve Ruby objects at all (which is quite likely), you can simply reuse it.

Parameters

[out] ptr Target to mark, which is a rb_random_t this case.

Variable Documentation

◆ rb_random_data_type

const rb_data_type_t rb_random_data_type

extern

The data that holds the backend type of rb_cRandom.

Used as your PRNG's rb_data_type_struct::parent.

Definition at line 268 of file random.c.

(a6379032ee98bc43fb68ce7a6c186f3512558ce0)

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ RB_RANDOM_DATA_INIT_PARENT

◆ rb_random_data_type

◆ RB_RANDOM_DEFINE_INIT_INT32_FUNC

◆ RB_RANDOM_INTERFACE_DECLARE

◆ RB_RANDOM_INTERFACE_DECLARE_WITH_REAL

◆ RB_RANDOM_INTERFACE_DEFINE

◆ RB_RANDOM_INTERFACE_DEFINE_WITH_REAL

◆ RB_RANDOM_PARENT

◆ RUBY_RANDOM_INTERFACE_VERSION_INITIALIZER

◆ RUBY_RANDOM_INTERFACE_VERSION_MAJOR

◆ RUBY_RANDOM_INTERFACE_VERSION_MAJOR_MAX

◆ RUBY_RANDOM_INTERFACE_VERSION_MINOR

◆ RUBY_RANDOM_INTERFACE_VERSION_MINOR_MAX

◆ RUBY_RANDOM_PASTE_VERSION_SUFFIX

◆ RUBY_RANDOM_WITH_VERSION_SUFFIX

Typedef Documentation

◆ rb_random_data_type_t

◆ rb_random_get_bytes_func

◆ rb_random_get_int32_func

◆ rb_random_get_real_func

◆ rb_random_init_func

◆ rb_random_init_int32_func

◆ rb_random_t

Function Documentation

◆ rb_int_pair_to_real()

◆ rb_rand_bytes_int32()

◆ rb_rand_if()

◆ rb_random_base_init()

◆ rb_random_mark()

Variable Documentation

◆ rb_random_data_type