Ruby: include/ruby/random.h File Reference

Ruby 3.2.5p208 (2024-07-26 revision 31d0f1a2e7dbfb60731d1f05b868e1d578cda493)

Data Structures | Macros | Typedefs | Functions | Variables
random.h File Reference
`#include "ruby/ruby.h"`

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)
#define | RUBY_RANDOM_WITH_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)
| 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-/ramdom/loop.c`.

Definition in file random.h.

## Macro Definition Documentation

## ◆ RB_RANDOM_DATA_INIT_PARENT

#define RB_RANDOM_DATA_INIT_PARENT | ( |  | random_data | ) |

Value:
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); \
}
rb_random_struct
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:
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),
};
RB_RANDOM_INTERFACE_DEFINE
#define RB_RANDOM_INTERFACE_DEFINE(prefix)
This utility macro expands to the names declared using RB_RANDOM_INTERFACE_DECLARE.
Definition random.h:210
rb_random_interface_t
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:
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,
}
rb_random_mark
void rb_random_mark(void *ptr)
This is the implementation of rb_data_type_struct::dmark for rb_random_data_type.
RB_RANDOM_PARENT
#define RB_RANDOM_PARENT
This utility macro can be used when you define your own PRNG type:
Definition random.h:256
rb_data_type_struct
This is the struct that holds necessary info for a struct.
Definition rtypeddata.h:190

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 )

Value:
x##_##y##_##z
_
#define _(args)
This was a transition path from K&R to ANSI.
Definition stdarg.h:35

Definition at line 27 of file random.h.

## ◆ RUBY_RANDOM_WITH_VERSION_SUFFIX

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

Value:
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 1126 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 1272 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 329 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 252 of file random.c.