Ruby  3.4.0dev (2024-12-06 revision 892c46283a5ea4179500d951c9d4866c0051f27b)
Data Structures | Macros | Typedefs | Functions | Variables
random.h File Reference

(892c46283a5ea4179500d951c9d4866c0051f27b)

#include "ruby/ruby.h"
Include dependency graph for random.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of 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. More...
 
#define RB_RANDOM_INTERFACE_DECLARE_WITH_REAL(prefix)
 Identical to RB_RANDOM_INTERFACE_DECLARE except it also declares prefix_get_real. More...
 
#define RB_RANDOM_INTERFACE_DEFINE(prefix)
 This utility macro expands to the names declared using RB_RANDOM_INTERFACE_DECLARE. More...
 
#define RB_RANDOM_INTERFACE_DEFINE_WITH_REAL(prefix)
 Identical to RB_RANDOM_INTERFACE_DEFINE except it also defines prefix_get_real. More...
 
#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: More...
 
#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. More...
 

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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
typedef const rb_data_type_t rb_random_data_type_t
 This is the type of rb_random_data_type. More...
 

Functions

void rb_random_mark (void *ptr)
 This is the implementation of rb_data_type_struct::dmark for rb_random_data_type. More...
 
void rb_random_base_init (rb_random_t *rnd)
 Initialises an allocated rb_random_t instance. More...
 
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. More...
 
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. More...
 
static const rb_random_interface_trb_rand_if (VALUE obj)
 Queries the interface of the passed random object. More...
 

Variables

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

Detailed Description

Date
Sat May 7 11:51:14 JST 2016

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)
const rb_data_type_t rb_random_data_type
The data that holds the backend type of rb_cRandom.
Definition: random.c:259

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); \
}
Base components of the random interface.
Definition: random.h:49

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:
static double prefix##_get_real(rb_random_t *, int)
#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:

static inline constexpr rb_random_interface_t foo_interface = {
32768, // bits
};
#define RB_RANDOM_INTERFACE_DEFINE(prefix)
This utility macro expands to the names declared using RB_RANDOM_INTERFACE_DECLARE.
Definition: random.h:210
PRNG algorithmic interface, analogous to Ruby level classes.
Definition: random.h:114

Definition at line 210 of file random.h.

◆ RB_RANDOM_INTERFACE_DEFINE_WITH_REAL

#define RB_RANDOM_INTERFACE_DEFINE_WITH_REAL (   prefix)
Value:
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 = {
};
static inline constexpr rb_random_data_type_t your_prng_type = {
"your PRNG",
RB_RANDOM_PARENT, // <<-- HERE
&your_if,
0,
}
void rb_random_mark(void *ptr)
This is the implementation of rb_data_type_struct::dmark for rb_random_data_type.
#define RB_RANDOM_PARENT
This utility macro can be used when you define your own PRNG type:
Definition: random.h:256
This is the struct that holds necessary info for a struct.
Definition: rtypeddata.h:200

Definition at line 256 of file random.h.

Typedef Documentation

◆ 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]rngYour random struct to extract an integer from.
[out]bufReturn buffer of at least len bytes length.
[in]lenNumber 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]rngYour 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]rngYour random struct to extract an integer from.
[in]exclPass 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]rngYour random struct to fill in.
[in]bufSeed, maybe converted from a bignum.
[in]lenNumber 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]rngYour random struct to fill in.
[in]dataSeed, 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 1 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]aMost significant 32 bits of the result.
[in]bLeast significant 32 bits of the result.
[in]exclWhether 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 1137 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]funcGenerator function.
[out]prngPassed as-is to func.
[out]buffReturn buffer.
[in]sizeNumber 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 1283 of file random.c.

◆ 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]objAn 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]rndYour PRNG's base part.
Postcondition
rnd is filled with an initial state.

Definition at line 336 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]ptrTarget 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 259 of file random.c.