Struct rug::rand::ThreadRandState
source · pub struct ThreadRandState<'a> { /* private fields */ }
Expand description
The state of a random number generator that is suitable for a single thread only.
This is similar to RandState
but can only be used in a single thread.
Examples
use rug::rand::ThreadRandState;
let mut gen = create_generator();
let mut rand = ThreadRandState::new_custom(&mut gen);
let u = rand.bits(32);
println!("32 random bits: {:032b}", u);
Implementations§
source§impl ThreadRandState<'_>
impl ThreadRandState<'_>
sourcepub fn new_custom(custom: &mut dyn ThreadRandGen) -> ThreadRandState<'_>
pub fn new_custom(custom: &mut dyn ThreadRandGen) -> ThreadRandState<'_>
Creates a new custom random generator.
This is similar to
RandState::new_custom
. The
difference is that this method takes a ThreadRandGen
that does not
have to implement Send
or Sync
.
Examples
use rug::rand::{ThreadRandGen, ThreadRandState};
use rug::Integer;
// dummy pointer field to ensure Seed is not Send and not Sync
struct Seed(*const ());
impl ThreadRandGen for Seed {
fn gen(&mut self) -> u32 {
// not really random
0x8CEF_7310
}
}
let mut seed = Seed(&());
let mut rand = ThreadRandState::new_custom(&mut seed);
let mut i = Integer::from(15);
i.random_below_mut(&mut rand);
println!("0 ≤ {} < 15", i);
assert!(i < 15);
sourcepub fn new_custom_boxed(
custom: Box<dyn ThreadRandGen>
) -> ThreadRandState<'static>
pub fn new_custom_boxed( custom: Box<dyn ThreadRandGen> ) -> ThreadRandState<'static>
Creates a new custom random generator.
This is similar to
RandState::new_custom_boxed
.
The difference is that this method takes a ThreadRandGen
that does
not have to implement Send
or Sync
.
Examples
use rug::rand::{ThreadRandGen, ThreadRandState};
use rug::Integer;
// dummy pointer field to ensure Seed is not Send and not Sync
struct Seed(*const ());
impl ThreadRandGen for Seed {
fn gen(&mut self) -> u32 {
// not really random
0x8CEF_7310
}
}
let seed = Box::new(Seed(&()));
let mut rand = ThreadRandState::new_custom_boxed(seed);
let mut i = Integer::from(15);
i.random_below_mut(&mut rand);
println!("0 ≤ {} < 15", i);
assert!(i < 15);
sourcepub unsafe fn from_raw(raw: randstate_t) -> ThreadRandState<'static>
pub unsafe fn from_raw(raw: randstate_t) -> ThreadRandState<'static>
Creates a random generator from an initialized GMP random generator.
This is similar to
RandState::from_raw
, but the
object does not need to be thread safe. You can use this method if the
object is thread safe, but in that case
RandState::from_raw
is probably
better as it allows the returned object to be shared and transferred
across threads.
Safety
- The value must be initialized as a valid
randstate_t
. - The
randstate_t
type can be considered as a kind of pointer, so there can be multiple copies of it. Since this function takes over ownership, no other copies of the passed value should exist.
Examples
use core::mem::MaybeUninit;
use gmp_mpfr_sys::gmp;
use rug::rand::ThreadRandState;
let mut rand = unsafe {
let mut raw = MaybeUninit::uninit();
gmp::randinit_default(raw.as_mut_ptr());
let raw = raw.assume_init();
// raw is initialized and unique
ThreadRandState::from_raw(raw)
};
let u = rand.bits(32);
println!("32 random bits: {:032b}", u);
// since rand is a ThreadRandState now, deallocation is automatic
sourcepub fn into_raw(self) -> randstate_t
pub fn into_raw(self) -> randstate_t
Converts a random generator into a GMP random generator.
The returned object should be freed to avoid memory leaks.
This is similar to
RandState::into_raw
, but the
returned object is not thread safe. Notably, it should not be used in
RandState::from_raw
.
Panics
This method panics if the ThreadRandState
object was created using
new_custom
, as the borrow into the custom generator would be
terminated once self
is consumed. This would lead to undefined
behavior if the returned object is used. This method does work with
objects created using new_custom_boxed
.
Examples
use gmp_mpfr_sys::gmp;
use rug::rand::ThreadRandState;
let gen = Box::new(create_generator());
let rand = ThreadRandState::new_custom_boxed(gen);
let mut raw = rand.into_raw();
unsafe {
let u = gmp::urandomb_ui(&mut raw, 32) as u32;
println!("32 random bits: {:032b}", u);
// free object to prevent memory leak
gmp::randclear(&mut raw);
}
sourcepub fn as_raw(&self) -> *const randstate_t
pub fn as_raw(&self) -> *const randstate_t
Returns a pointer to the inner GMP random generator.
The returned pointer will be valid for as long as self
is valid.
This is similar to
RandState::as_raw
.
Examples
use rug::rand::ThreadRandState;
let mut gen = create_generator();
let mut rand = ThreadRandState::new_custom(&mut gen);
let raw_ptr = rand.as_raw();
// There is not much you can do with an immutable randstate_t pointer.
println!("pointer: {:p}", raw_ptr);
let u = rand.bits(32);
println!("32 random bits: {:032b}", u);
sourcepub fn as_raw_mut(&mut self) -> *mut randstate_t
pub fn as_raw_mut(&mut self) -> *mut randstate_t
Returns an unsafe mutable pointer to the inner GMP random generator.
The returned pointer will be valid for as long as self
is valid.
This is similar to
RandState::as_raw_mut
.
Examples
use gmp_mpfr_sys::gmp;
use rug::rand::ThreadRandState;
let mut gen = create_generator();
let mut rand = ThreadRandState::new_custom(&mut gen);
let raw_ptr = rand.as_raw_mut();
unsafe {
let u1 = gmp::urandomb_ui(raw_ptr, 32) as u32;
println!("32 random bits: {:032b}", u1);
}
let u2 = rand.bits(32);
println!("another 32 random bits: {:032b}", u2);
sourcepub fn into_custom_boxed(self) -> Result<Box<dyn ThreadRandGen>, Self>
pub fn into_custom_boxed(self) -> Result<Box<dyn ThreadRandGen>, Self>
Converts a random generator into Box<dyn ThreadRandGen>
if possible.
If the conversion is not possible, Err(self)
is
returned.
This conversion is always possible when the random generator was created
with new_custom_boxed
. It is also possible if the generator was
cloned, directly or indirectly, from another generator that was created
with new_custom
or new_custom_boxed
.
This is similar to
RandState::into_custom_boxed
.
Examples
use rug::rand::{ThreadRandGen, ThreadRandState};
struct Seed;
impl ThreadRandGen for Seed {
fn gen(&mut self) -> u32 {
// not really random
0x8CEF_7310
}
}
let seed = Box::new(Seed);
let rand = ThreadRandState::new_custom_boxed(seed);
let mut back_to_seed = rand.into_custom_boxed().unwrap();
assert_eq!(back_to_seed.gen(), 0x8CEF_7310);
sourcepub fn seed(&mut self, seed: &Integer)
pub fn seed(&mut self, seed: &Integer)
Seeds the random generator.
This is similar to RandState::seed
.
Examples
use rug::rand::ThreadRandState;
use rug::Integer;
let mut gen = create_generator_with_seed();
let seed = Integer::from(123456);
let mut rand = ThreadRandState::new_custom(&mut gen);
rand.seed(&seed);
let u1a = rand.bits(32);
let u1b = rand.bits(32);
// reseed with the same seed
rand.seed(&seed);
let u2a = rand.bits(32);
let u2b = rand.bits(32);
assert_eq!(u1a, u2a);
assert_eq!(u1b, u2b);
sourcepub fn bits(&mut self, bits: u32) -> u32
pub fn bits(&mut self, bits: u32) -> u32
Generates a random number with the specified number of bits.
This is similar to RandState::bits
.
Panics
Panics if bits
is greater than 32.
Examples
use rug::rand::ThreadRandState;
let mut gen = create_generator();
let mut rand = ThreadRandState::new_custom(&mut gen);
let u = rand.bits(16);
assert!(u < (1 << 16));
println!("16 random bits: {:016b}", u);
sourcepub fn below(&mut self, bound: u32) -> u32
pub fn below(&mut self, bound: u32) -> u32
Generates a random number below the given boundary value.
This is similar to RandState::below
.
Panics
Panics if the boundary value is zero.
Examples
use rug::rand::ThreadRandState;
let mut gen = create_generator();
let mut rand = ThreadRandState::new_custom(&mut gen);
let u = rand.below(10000);
assert!(u < 10000);
println!("0 ≤ {} < 10000", u);
Trait Implementations§
source§impl Clone for ThreadRandState<'_>
impl Clone for ThreadRandState<'_>
source§fn clone(&self) -> ThreadRandState<'static>
fn clone(&self) -> ThreadRandState<'static>
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read more