random.c 文件参考

伪随机数发生器与常用分布实现. 更多...

#include <string.h>
#include <math.h>
#include <stdlib.h>
#include <time.h>
#include <stdatomic.h>
#include "memory_bridge.h"
#include "internal.h"
#include "lmmc/config.h"
#include "lmmc/random.h"
#include "lmmc/status.h"
#include "random_internal.h"

random.c 的引用(Include)关系图:

浏览该文件的源代码.

函数
lmmc_rng_t *	lmmc_rng_default_get (void)
void	lmmc_rng_default_reset (void)
lmmc_status_t	lmmc_rng_create (lmmc_rng_t **out_rng)
	创建随机数发生器实例。
lmmc_status_t	lmmc_rng_seed (lmmc_rng_t *rng, uint64_t seed)
	重新设定种子。
void	lmmc_rng_destroy (lmmc_rng_t *rng)
	销毁发生器，释放内部分配的所有内存。
lmmc_status_t	lmmc_rng_clone (const lmmc_rng_t *src, lmmc_rng_t **out_rng)
	深拷贝 RNG 状态。
lmmc_status_t	lmmc_rng_jump (lmmc_rng_t *rng)
	将 RNG 状态前进 2^128 步（xoshiro256** jump 多项式）。
lmmc_status_t	lmmc_rng_long_jump (lmmc_rng_t *rng)
	将 RNG 状态前进 2^192 步（xoshiro256** long_jump 多项式）。
uint64_t	lmmc_rng_next_u64 (lmmc_rng_t *rng)
	直接获取下一个 64 位均匀整数。
lmmc_status_t	lmmc_rng_uniform (lmmc_rng_t *rng, lmmc_real_t a, lmmc_real_t b, lmmc_real_t *out_value)
	实数分布参数的公共约束。
lmmc_status_t	lmmc_rng_exponential (lmmc_rng_t *rng, lmmc_real_t rate, lmmc_real_t *out_value)
	生成参数为 rate 的指数分布样本。
lmmc_status_t	lmmc_rng_fill_uniform (lmmc_rng_t *rng, lmmc_real_t a, lmmc_real_t b, lmmc_real_t *array, size_t count)
	批量填充均匀分布样本到 array 。
lmmc_status_t	lmmc_rng_shuffle (lmmc_rng_t *rng, void *array, size_t count, size_t elem_size)
	Fisher-Yates 洗牌：就地随机重排 array 中的 count 个元素。 每次 Fisher-Yates 选择均使用无偏的拒绝采样。
lmmc_status_t	lmmc_rng_int_uniform (lmmc_rng_t *rng, int64_t lo, int64_t hi, int64_t *out)
	在 [lo, hi] 闭区间内生成无偏均匀整数分布样本。

详细描述

伪随机数发生器与常用分布实现.

在文件 random.c 中定义.

函数说明

lmmc_rng_default_get()

lmmc_rng_t * lmmc_rng_default_get

(

void

)

Return the allocation-free default RNG for the current thread.

在文件 random.c 第 50 行定义.

引用了 lmmc_rng_default_get() , 以及 lmmc_rng_seed().

被这些函数引用 lmmc_rng_default_get(), lmmc_std_random_default_choice(), lmmc_std_random_default_normal(), lmmc_std_random_default_rand(), lmmc_std_random_default_randint() , 以及 lmmc_std_random_default_seed().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_default_reset()

void lmmc_rng_default_reset

(

void

)

Clear only the current thread's default RNG state.

在文件 random.c 第 58 行定义.

引用了 lmmc_rng_default_reset().

被这些函数引用 lmmc_rng_default_reset() , 以及 lmmc_std_random_default_deinit().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_create()

lmmc_status_t lmmc_rng_create

(

lmmc_rng_t **

out_rng

)

创建随机数发生器实例。

分配并初始化一个 xoshiro256** 发生器。句柄由调用方拥有，默认 线程受限；跨线程传递或并发访问必须由调用方同步。并行工作负载应为 每个线程创建独立句柄，或使用 lmmc_rng_clone 和 ::lmmc_rng_jump。

参数

[out]

out_rng

输出新创建的 RNG 句柄。

返回

LMMC_STATUS_OK 成功； LMMC_STATUS_INVALID_ARGUMENT 若 out_rng 为 NULL； LMMC_STATUS_ALLOCATION_FAILED 若内存分配失败。

副作用

• 分配堆内存存储 RNG 内部状态，调用方必须调用 lmmc_rng_destroy 释放。

将平台熵混入默认种子,为各随机数发生器建立独立数据流.

在文件 random.c 第 76 行定义.

引用了 lmmc_memory_alloc(), lmmc_rng_create(), lmmc_rng_seed(), LMMC_STATUS_ALLOCATION_FAILED, LMMC_STATUS_INVALID_ARGUMENT , 以及 LMMC_STATUS_OK.

被这些函数引用 lmmc_rng_create().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_seed()

lmmc_status_t lmmc_rng_seed	(	lmmc_rng_t *	rng,
		uint64_t	seed )

重新设定种子。

在文件 random.c 第 96 行定义.

引用了 lmmc_rng_seed(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_create(), lmmc_rng_default_get(), lmmc_rng_seed() , 以及 lmmc_std_random_seed().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_destroy()

void lmmc_rng_destroy

(

lmmc_rng_t *

rng

)

销毁发生器，释放内部分配的所有内存。

在文件 random.c 第 112 行定义.

引用了 lmmc_memory_free(), lmmc_rng_destroy() , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_destroy().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_clone()

lmmc_status_t lmmc_rng_clone	(	const lmmc_rng_t *	src,
		lmmc_rng_t **	out_rng )

深拷贝 RNG 状态。

调用方可对副本调用 lmmc_rng_jump 以获得独立的并行流。

参数

[in]	src	源 RNG（不可为 NULL）。
[out]	out_rng	输出新分配的 RNG 副本。

返回

LMMC_STATUS_OK 成功；LMMC_STATUS_INVALID_ARGUMENT 若 src 或 out_rng 为 NULL。

副作用

• 分配堆内存存储副本状态，调用方必须调用 lmmc_rng_destroy 释放。

在文件 random.c 第 120 行定义.

引用了 lmmc_memory_alloc(), lmmc_rng_clone(), LMMC_STATUS_ALLOCATION_FAILED, LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_clone().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_jump()

lmmc_status_t lmmc_rng_jump

(

lmmc_rng_t *

rng

)

将 RNG 状态前进 2^128 步（xoshiro256** jump 多项式）。

用于将一个 RNG 流拆分为多个不重叠的子流。

参数

[in,out]

rng

已初始化的 RNG（不可为 NULL）。

返回

LMMC_STATUS_OK 成功；LMMC_STATUS_INVALID_ARGUMENT 若 rng 为 NULL。

副作用

• 就地修改 rng 的内部状态。

在文件 random.c 第 190 行定义.

引用了 lmmc_rng_jump(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_jump().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_long_jump()

lmmc_status_t lmmc_rng_long_jump

(

lmmc_rng_t *

rng

)

将 RNG 状态前进 2^192 步（xoshiro256** long_jump 多项式）。

用于在更大尺度上拆分并行流。

参数

[in,out]

rng

已初始化的 RNG（不可为 NULL）。

返回

LMMC_STATUS_OK 成功；LMMC_STATUS_INVALID_ARGUMENT 若 rng 为 NULL。

副作用

• 就地修改 rng 的内部状态。

在文件 random.c 第 200 行定义.

引用了 lmmc_rng_long_jump(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_long_jump().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_next_u64()

uint64_t lmmc_rng_next_u64

(

lmmc_rng_t *

rng

)

直接获取下一个 64 位均匀整数。

在文件 random.c 第 210 行定义.

引用了 lmmc_rng_next_u64() , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_next_u64().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_uniform()

lmmc_status_t lmmc_rng_uniform	(	lmmc_rng_t *	rng,
		lmmc_real_t	a,
		lmmc_real_t	b,
		lmmc_real_t *	out_value )

实数分布参数的公共约束。

所有实数参数必须有限；尺度、形状、速率和自由度参数还必须为正数。 违反约束时返回 LMMC_STATUS_INVALID_ARGUMENT，且不会进入拒绝采样循环。

在 \([a,b)\) 区间内生成均匀分布样本。

使用防溢出的仿射插值；有限端点即使跨越完整 double 范围也不会因 计算 b-a 而产生无穷值。

在文件 random.c 第 220 行定义.

引用了 lmmc_rng_uniform(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_uniform() , 以及 lmmc_std_random_rand().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_exponential()

lmmc_status_t lmmc_rng_exponential	(	lmmc_rng_t *	rng,
		lmmc_real_t	rate,
		lmmc_real_t *	out_value )

生成参数为 rate 的指数分布样本。

在文件 random.c 第 240 行定义.

引用了 lmmc_rng_exponential(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_exponential().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_fill_uniform()

lmmc_status_t lmmc_rng_fill_uniform	(	lmmc_rng_t *	rng,
		lmmc_real_t	a,
		lmmc_real_t	b,
		lmmc_real_t *	array,
		size_t	count )

批量填充均匀分布样本到 array 。

在文件 random.c 第 263 行定义.

引用了 lmmc_rng_fill_uniform(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_fill_uniform().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_shuffle()

lmmc_status_t lmmc_rng_shuffle	(	lmmc_rng_t *	rng,
		void *	array,
		size_t	count,
		size_t	elem_size )

Fisher-Yates 洗牌：就地随机重排 array 中的 count 个元素。 每次 Fisher-Yates 选择均使用无偏的拒绝采样。

参数

[in]	rng	已初始化的 RNG。
[in,out]	array	待洗牌的数组，就地重排。
[in]	count	元素个数。
[in]	elem_size	每个元素的字节大小。

副作用

• 就地修改 array 中元素的顺序。
• 就地修改 rng 的内部状态。

在文件 random.c 第 288 行定义.

引用了 lmmc_memory_alloc(), lmmc_memory_free(), lmmc_rng_shuffle(), LMMC_STATUS_ALLOCATION_FAILED, LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_shuffle().

函数调用图:

这是这个函数的调用关系图:

lmmc_rng_int_uniform()

lmmc_status_t lmmc_rng_int_uniform	(	lmmc_rng_t *	rng,
		int64_t	lo,
		int64_t	hi,
		int64_t *	out )

在 [lo, hi] 闭区间内生成无偏均匀整数分布样本。

支持完整的 int64_t 定义域且不执行有符号溢出；lo == hi 时不消耗 RNG 状态。

参数

[in]	rng	已初始化的 RNG。
[in]	lo	下界（含）。
[in]	hi	上界（含）。
[out]	out	输出样本值。

返回

LMMC_STATUS_OK 成功；LMMC_STATUS_INVALID_ARGUMENT 若 lo > hi。

在文件 random.c 第 329 行定义.

引用了 lmmc_rng_int_uniform(), LMMC_STATUS_INVALID_ARGUMENT, LMMC_STATUS_OK , 以及 lmmc_rng_t::state.

被这些函数引用 lmmc_rng_int_uniform(), lmmc_std_random_choice() , 以及 lmmc_std_random_randint().

函数调用图:

这是这个函数的调用关系图: