11.76 srfi.271 - Random port libraries ¶

Module: srfi.271 ¶

This module provides the means to create random ports, an input port to return random bytes.

This srfi has two submodules, both export make-random-port: srfi.271.randomized draws random bits from system’s high-entropy random source (/dev/urandom on Unix-family, and BCryptGenRandom on MinGW), which is hard to predict and cannot reproduce, while srfi.271.determinized uses pseudo random number generator (PRNG), which is deterministic. The user can import either one depending on the purpose. srfi.271.determinized.

The module srfi.271 is an alias of srfi.271.rnndomized, so its make-random-port takes system’s random source. Unless you need cryptographic quality, you may want srfi.271.determinized, as it can procude large quantitiy of random bits quickly, without exhausting external entropy pool.

See srfi.27 - Sources of Random Bits, for an alternative PRNG interface.

Module: srfi.271.randomized ¶

Module: srfi.271.determinized ¶

Function: make-random-port :optional initializer ¶

[SRFI-271]{srfi.271.randomized}{srfi.271.determinized} Returns an input port, from which you can read random octets. Note that the module srfi.271.randomized and srfi.271.determinized defines different procedures with the same name.

srfi.271.randomized#make-random-port pulls from high-entropy random source provided by the system. You can use it for the cryptgraphic purpose, but reading large number of bytes may be slow if it exhaust system’s entropy pool. The optional initializer argument is ignored.

srfi.271.determined#make-random-port uses PRNG to generate random octets; it’s fast, and reproducible from the same seed. The random seed can be provided with initializer, which may be either a binary input port or a <random-port-state> object retrieved from another determined random port. If omitted, it uses srfi.271.randomized#make-random-port as an initializer, so the seed is quite random.

To provide fixed seed, you can use gauche.vport’s open-input-byte-list (see gauche.vport - Virtual ports), or srfi.277’s open-cyclic-input-bytevector (see srfi.277 - Cyclic ports):

(make-random-port (open-input-byte-list '#0=(1 2 3 4 . #0#)))

(make-random-port (open-cyclic-input-bytevector '#u8"abcd"))

Providing a cicular list to open-input-byte-list ensures it provides enough seed values whatever the PRNG algorithm requires. If the initializer cannot provide enough seeds, a condition that satisfies random-port-initialization-error? is raised.

Function: random-port? obj ¶

[SRFI-271]{srfi.271.determinized} Returns #t iff obj is an input port created by srfi.271.determined#make-random-port. Note that the port returned by srfi.271.randomized#make-random-port does not satisfy this predicate.

Function: random-port-state drport ¶

[SRFI-271]{srfi.271.determinized} Returns an object that encapsulates the state of deteminized random port drport. Passing that state to srfi.271.determined#make-random-port yields a random port that produces exactly the same random sequence as drport would produce from this moment.

Function: random-port-state? obj ¶

[SRFI-271]{srfi.271.determinized} Returns #t iff obj is a random port state object returned by random-port-state.

Function: random-port-state=? s1 s2 s3 … ¶

[SRFI-271]{srfi.271.determinized} All the arguments must be random port states. Returns #t iff all the states are equivalent, i.e. they will produce the same random sequence when passed to srfi.271.determined#make-random-port.

Function: random-port-initialization-error? obj ¶

[SRFI-271]{srfi.271.determinized} Returns #t iff obj is a condition raised from srfi.271.determined#make-random-port when the initializer is not adequate.