1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
(**************************************************************************)
(* *)
(* OCaml *)
(* *)
(* Damien Doligez, projet Para, INRIA Rocquencourt *)
(* Xavier Leroy, projet Cambium, College de France and Inria *)
(* *)
(* Copyright 1996 Institut National de Recherche en Informatique et *)
(* en Automatique. *)
(* *)
(* All rights reserved. This file is distributed under the terms of *)
(* the GNU Lesser General Public License version 2.1, with the *)
(* special exception on linking described in the file LICENSE. *)
(* *)
(**************************************************************************)
(** Pseudo-random number generators (PRNG).
With multiple domains, each domain has its own generator that evolves
independently of the generators of other domains. When a domain is
created, its generator is initialized by splitting the state
of the generator associated with the parent domain.
In contrast, all threads within a domain share the same domain-local
generator. Independent generators can be created with the {!Random.split}
function and used with the functions from the {!Random.State} module.
*)
(** {1 Basic functions} *)
val init : int -> unit
(** Initialize the domain-local generator, using the argument as a seed.
The same seed will always yield the same sequence of numbers. *)
val full_init : int array -> unit
(** Same as {!Random.init} but takes more data as seed. *)
val self_init : unit -> unit
(** Initialize the domain-local generator with a random seed chosen
in a system-dependent way. If [/dev/urandom] is available on the host
machine, it is used to provide a highly random initial seed. Otherwise, a
less random seed is computed from system parameters (current time, process
IDs, domain-local state). *)
val bits : unit -> int
(** Return 30 random bits in a nonnegative integer.
@before 5.0 used a different algorithm (affects all the following functions)
*)
val int : int -> int
(** [Random.int bound] returns a random integer between 0 (inclusive)
and [bound] (exclusive). [bound] must be greater than 0 and less
than 2{^30}. *)
val full_int : int -> int
(** [Random.full_int bound] returns a random integer between 0 (inclusive)
and [bound] (exclusive). [bound] may be any positive integer.
If [bound] is less than 2{^30}, [Random.full_int bound] is equal to
{!Random.int}[ bound]. If [bound] is greater than 2{^30} (on 64-bit systems
or non-standard environments, such as JavaScript), [Random.full_int]
returns a value, where {!Random.int} raises {!Stdlib.Invalid_argument}.
@since 4.13 *)
val int32 : Int32.t -> Int32.t
(** [Random.int32 bound] returns a random integer between 0 (inclusive)
and [bound] (exclusive). [bound] must be greater than 0. *)
val nativeint : Nativeint.t -> Nativeint.t
(** [Random.nativeint bound] returns a random integer between 0 (inclusive)
and [bound] (exclusive). [bound] must be greater than 0. *)
val int64 : Int64.t -> Int64.t
(** [Random.int64 bound] returns a random integer between 0 (inclusive)
and [bound] (exclusive). [bound] must be greater than 0. *)
val float : float -> float
(** [Random.float bound] returns a random floating-point number
between 0 and [bound] (inclusive). If [bound] is
negative, the result is negative or zero. If [bound] is 0,
the result is 0. *)
val bool : unit -> bool
(** [Random.bool ()] returns [true] or [false] with probability 0.5 each. *)
val bits32 : unit -> Int32.t
(** [Random.bits32 ()] returns 32 random bits as an integer between
{!Int32.min_int} and {!Int32.max_int}.
@since 4.14 *)
val bits64 : unit -> Int64.t
(** [Random.bits64 ()] returns 64 random bits as an integer between
{!Int64.min_int} and {!Int64.max_int}.
@since 4.14 *)
val nativebits : unit -> Nativeint.t
(** [Random.nativebits ()] returns 32 or 64 random bits (depending on
the bit width of the platform) as an integer between
{!Nativeint.min_int} and {!Nativeint.max_int}.
@since 4.14 *)
(** {1 Advanced functions} *)
(** The functions from module {!State} manipulate the current state
of the random generator explicitly.
This allows using one or several deterministic PRNGs,
even in a multi-threaded program, without interference from
other parts of the program.
*)
module State : sig
type t
(** The type of PRNG states. *)
val make : int array -> t
(** Create a new state and initialize it with the given seed. *)
val make_self_init : unit -> t
(** Create a new state and initialize it with a random seed chosen
in a system-dependent way.
The seed is obtained as described in {!Random.self_init}. *)
val copy : t -> t
(** Return a copy of the given state. *)
val bits : t -> int
val int : t -> int -> int
val full_int : t -> int -> int
val int32 : t -> Int32.t -> Int32.t
val nativeint : t -> Nativeint.t -> Nativeint.t
val int64 : t -> Int64.t -> Int64.t
val float : t -> float -> float
val bool : t -> bool
val bits32 : t -> Int32.t
val bits64 : t -> Int64.t
val nativebits : t -> Nativeint.t
(** These functions are the same as the basic functions, except that they
use (and update) the given PRNG state instead of the default one.
*)
val split : t -> t
(** Draw a fresh PRNG state from the given PRNG state.
(The given PRNG state is modified.)
The new PRNG is statistically independent from the given PRNG.
Data can be drawn from both PRNGs, in any order, without risk of
correlation. Both PRNGs can be split later, arbitrarily many times.
@since 5.0 *)
val to_binary_string : t -> string
(** Serializes the PRNG state into an immutable sequence of bytes.
See {!of_binary_string} for deserialization.
The [string] type is intended here for serialization only, the
encoding is not human-readable and may not be printable.
Note that the serialization format may differ across OCaml
versions.
@since 5.1
*)
val of_binary_string : string -> t
(** Deserializes a byte sequence obtained by calling
{!to_binary_string}. The resulting PRNG state will produce the
same random numbers as the state that was passed as input to
{!to_binary_string}.
@raise Failure if the input is not in the expected format.
Note that the serialization format may differ across OCaml
versions.
Unlike the functions provided by the {!Marshal} module, this
function either produces a valid state or fails cleanly with
a [Failure] exception. It can be safely used on user-provided,
untrusted inputs.
@since 5.1
*)
end
val get_state : unit -> State.t
(** [get_state()] returns a fresh copy of the current state of the
domain-local generator (which is used by the basic functions). *)
val set_state : State.t -> unit
(** [set_state s] updates the current state of the domain-local
generator (which is used by the basic functions) by copying
the state [s] into it. *)
val split : unit -> State.t
(** Draw a fresh PRNG state from the current state of the domain-local
generator used by the default functions.
(The state of the domain-local generator is modified.)
See {!Random.State.split}.
@since 5.0 *)
|
