271: Random port libraries271: Random port librariesby Wolfgang Corcoran-Mathe
This SRFI is currently in draft status. Here is an explanation of each status that a SRFI can hold. To provide input on this SRFI, please send email to srfi-271@nospamsrfi.schemers.org. To subscribe to the list, follow these instructions. You can access previous messages via the mailing list archive.
This SRFI proposes a pattern of libraries for binary input ports that produce random bytes. Libraries are divided into “randomized” and “determinized” categories to address different uses of random data. The design leaves the details of random number generation to the implementer and the transformation of bytes to other types (floats, etc.) to higher-level libraries. A mechanism for saving random-port states and propagating them to new ports is also provided.
None at present.
As a foundation for random-number generation, the well-known (and excellent) SRFI 27 includes both too little and too much. On the one hand, it makes no distinction between sources of cryptographic-quality pseudorandom data and sources of the deterministic pseudorandom data sometimes needed for testing and other purposes. On the other, it includes forms for defining new random sources and for parameterizing library procedures over them, thus adding avoidable complexity to the specification.
In this SRFI I take a different tack and try to describe a framework for random-number generation that adds as little as necessary to the language. This SRFI:
Uses binary input ports, rather than a novel type, for random sources.
Uses the Scheme library system — and only the Scheme library system — to distinguish between randomized* sources and determinized sources, as well as between different kinds of randomized and determinized sources.
Specifies no procedures for drawing random data. The
random-byte-seeking user is pointed in the direction of
read-u8 and read-bytevector. Those
in search of other kinds of random data will need an additional
library; see Usage and
compatibility for some ideas.
*: Throughout this SRFI, I use the term “randomized” to denote sources that should produce “cryptographic-quality” random data. See the Terminology section for a precise — or at least longer — definition.
Everyone agrees that it is sometimes useful to generate
the same random sequence several times, e.g. on each run of
a test suite. Whether to allow random number generators to
be “seeded”, and what forms those seeds should take, is
controversial. Initializing one
kind of source may require more “seed” data than another,
so we can’t take the one-size-fits-all approach of C’s
srand (C23
section 7.24.3.2) and other obsolete systems.
This SRFI takes an approach similar to that of SRFI 27 in allowing random-port states to be manipulated as semi-opaque objects (i.e. objects of unspecified type with external representations). Whereas SRFI 27 allows the user to get or set the state of any source, however, this SRFI only allows determinized random ports to be so manipulated, since the states of randomized ports cannot in general be represented by Scheme values. (Consider a random port backed by a hardware random-number generator, for example.)
Random ports are seeded only when they are created. The
make-random-port constructor accepts an optional state
argument which, if present, is used as the initial state for the new
port. SRFI 27’s “reseeding” interface
(random-source-state-set!, etc.) has been discarded as
unnecessary, since it is easy enough to create a new random port
with a desired state. Random ports can also be seeded with data
from other random ports; this eliminates the need for awkward
initialization procedures like
random-source-randomize!. Given a single good-quality
randomized port, this makes it easy to create determinzed ports with
random initial states.
Input ports have been in the Scheme Reports since the early
days (the RRRS); thus they fit easily into existing programs,
and they come with a wealth of standard inspection
procedures (u8-ready?, etc.). In contrast, an
opaque type like SRFI 27's random-source needs a fair amount of
wheel-reinvention — procedures like the utterly elementary
read-u8 have to be specified anew.
SRFI 194's generator-based
interface is another option.
SRFI 158
generators, however, are ill-defined,
being no more than nullary Scheme procedures. There is no portable
way to distinguish a
generator from any other procedure.
They mimic input ports in several ways, but there are important
port operations that they cannot support in current Scheme.
For example, it isn’t possible to write peek or
ready? procedures for generators. Some have
suggested adding general language features to address these
weaknesses. We can look forward to a future Scheme in which
ports and generators have all of the same features and compete,
pointlessly, for control of every I/O domain.
Back to the point. Some of the standard port operations that
are not available for SRFI 158 generators are useful for random
ports. For example, some random sources (traditionally, though
unfortunately) may block until sufficient entropy is available. With
random ports, applying u8-ready? should be enough to
alert you of this situation.
The words “must”, “may”, etc., though not upper-cased in this SRFI, should be interpreted according to RFC 2119.
A random port is a binary input port which produces random data. Reading from a random port must not produce an end-of-file object.
An randomized random port should produce data from either a high-entropy external source (e.g. the operating system’s entropy pool or a hardware random-number generator) or from a deterministic generation algorithm which has been seeded from such a source. The sequence produced by a randomized source should be unpredictable, even by an adversary who can read past outputs and simulate generation of outputs on demand.
A determinized random port must produce data generated by a fully deterministic generation algorithm. Two determinized random ports with the same states must produce the same sequence of pseudorandom numbers.
A random state is a semi-opaque object representing
the state of a random port (or, more precisely, of the
random-number generator embodied by a random port). Random
states must have an external representation and be comparable
with equal?.
A Scheme implementation conforming to this specification provides at least the following R7RS libraries (R7RS section 5.6):
(srfi 271)(srfi 271 randomized)(srfi 271 determinized)The usual library-name-format variants for these libraries may also be provided:
(srfi :271 randomized), etc.(srfi srfi-271 randomized), etc.(srfi 271) is simply an alias for
(srfi 271 randomized). (Rationale:
Rushed or incautious programmers who just want random numbers
get the best available.)
The (srfi 271 randomized) library and any
libraries with the (srfi 271 randomized)
prefix provide randomized random-number ports.
Both the randomized and determinized
libraries must export the make-random-port constructor.
determinized libraries must provide an
additional interface for
creating random ports with predetermined initial
states.
Implementations are encouraged to provide additional libraries
(e.g. for different pseudorandom generation algorithms) under the
(srfi 271 determinized) “namespace”. If they do, they must ensure
that each library follows the protocol detailed above.
A list of example
library names is provided below.
This section is informational.
Each library is tied to a specific generation mechanism; import the library that provides the one you want. There is no other mechanism in this specification for choosing between random-number-generation algorithms.
No means is provided here for getting floats, arbitrary integers, or other data out of random ports. This is left to a higher-level library, similar to SRFI 194, which can transform the binary output of a random port into values of other types.
If this proposal is incorporated into the R7RS, I suggest
that aliases under the library prefix (scheme random)
(e.g. (scheme random randomized),
(scheme random determinized), etc.) be provided.
A make-random-port procedure is exported by each
library with the (srfi 271) prefix.
(make-random-port) → binary-input-port
Returns a new random port.
determinized librariesThe following procedures are exported by all libraries with
the (srfi 271 determinized) prefix.
(make-random-port [initializer]) →
binary-input-port
As above, but the optional initializer argument is used as follows:
If initializer is a random state object, then
the initial state of the random port returned by
make-random-port is the same as that
represented by initializer.
If initializer is a binary input port, then the returned port’s state is constructed from data read from initializer. The exact process of constructing a random state from arbitrary data is unspecified, but if two initializer ports produce the same sequences, then the random ports initialized from them should have the same initial states.
An error satisfying
random-port-initialization-error? is
signaled if make-random-port cannot obtain
enough data from initializer to initialize a
random port state, or if the data obtained is unsuitable
for initializing the implementation’s pseudorandom
generator. Implementations should allow initialization
from arbitrary infinite sequences. An exception is the
all-zeros sequence (0, 0, …), which is known to cause
problems for many algorithms; implementations may allow
initialization by such a sequence.
If initializer is neither a random state nor a binary input port, then the effect is undefined.
Rationale: In tandem with random-port-state,
this provides a way to put a random port into a known state.
Calling make-random-port without an
initializer is equivalent to
(call-with-port (randomized:make-random-port)
make-random-port)where randomized:make-random-port denotes the
make-random-port procedure exported by
(srfi 271 randomized).
The difference between initializing a random port with a random port and initializing it with a random-port state is a little subtle. The following examples are not equivalent:
(make-random-port rport)
(make-random-port (random-port-state rport))
The first example returns a port whose initial state is constructed from (random) data read from the random port rport, while the second returns a port whose initial state is the same as rport’s state.
(random-port-state random-port) →
state
Returns an immutable random-state object representing the
current state
of random-port. If a new port is created with
(make-random-port state), where
state is the value of (random-port-state
old-port) (or is equal to that value
in the sense of equal?), then the new port
must produce the same random sequence as old-port.
(random-port-initialization-error? obj)
→ boolean
Returns #t if obj is an object signaled
by make-random-port in the circumstances described
above, and #f otherwise.
determinized library namesThis section is informational.
Names are based on Sebastiano Vigna’s PRNG page and Wikipedia.
(srfi 271 determinized xorshift)
Library using some kind of xorshift generator. These are often very fast, but the simplest xorshift implementations may not be very reliable. It might be appropriate to use such a library for toy or educational programs.
(srfi 271 determinized xoshiro256++)
(srfi 271 determinized xoshiro256**)
xoshiro libraries. The authors of the xoshiro generators claim they are faster and more reliable than xorshift generators.
(srfi 271 determinized xoshiro-kawai)Reserved for use by the Gauche Scheme implementation.
(srfi 271 determinized mwc256)Library for a 256-bit multiply-with-carry (MWC) source. MWC generators tend to have extremely long periods, ranging from around 260 to 22,000,000.
This section is informational.
Since the libraries specified by this SRFI do not provide
procedures for getting generally useful data types (integers
within arbitrary ranges, reals, etc.) out of random ports, a
higher-level interface will be needed to make random-port
programming congenial. The multi-library design of this SRFI leads
to one important consideration in choosing such an interface: it
should work with random ports from any library. Because Scheme lacks
a means of parameterizing one library over the exports of another,
we need an interface to random ports in general, not just to the
ports from, say, (srfi 271 randomized), if we wish to
avoid multiplying libraries unnecessarily.
For several reasons, detailed below, SRFI 27 would make a poor
high-level interface to random ports. SRFI 194, while specified in
terms of SRFI 27, is a better fit, and it provides more kinds
of random-data generators than most programmers will ever need.
By wrapping random ports in SRFI 158 generators, however, several
useful properties of ports would be lost (see
the Rationale for details). My preference
(which may be reified in a future SRFI) is for a library of bland
port-reading procedures, e.g. read-random-integer,
read-random-real, etc., which would do the (sometimes
prickly) job of extracting good-quality random values without
hiding the ports providing the raw data.
That being said, SRFI 27 remains the best-known random-number interface in Scheme, and it may be desirable to provide both SRFI 27 and 271 interfaces. A discussion of SRFI 27 / 271 compatibility issues follows.
SRFI 27’s random sources are similar to random ports, but they support a few operations that cannot be directly implemented in terms of this SRFI’s forms:
random-source?Why not: Random ports are input ports, but SRFI 27 requires that random sources be of a disjoint type.
random-source-state-set!random-source-randomize!random-source-pseudo-randomize!Why not: This SRFI does not provide operations for directly changing the state of an existing random port.
SRFI 27’s type-disjointness requirement could be satisfied by wrapping a random port in a record type. State mutation could then be implemented by replacing the port within the random-source wrapper with a newly-created port (since this SRFI only allows states to be set during port creation).
A portable implementation of random ports is currently impossible. A sample implementation of this SRFI developed for Gauche (running on POSIX systems) is available in the SRFI repository.
Thanks to John W. Cowan for helping to chip away everything in this SRFI that did not look like an elephant.
Thanks to Taylor Campbell and Alaric Snell-Pym for suggestions and elucidations. In particular, the definition of a randomized port was adapted from Alaric’s description of the desirable properties of such a source; any inaccuracies in the SRFI’s version are my own doing.
Thanks to Peter McGoron and the other members of the R7RS Second Working Group for advice and discussion.
Thanks to those who provided feedback via the SRFI mailing list or on the #scheme IRC channel.
Of course, none of this should be taken to suggest that any of the people mentioned above endorse this SRFI.
S. Bradner, Key words for use in RFCs to Indicate Requirement Levels (RFC 2119), 1997. https://datatracker.ietf.org/doc/html/rfc2119
William Clinger, ed., Revised Revised Report on Scheme (RRRS), MIT Artificial Intelligence Memo No. 848, August 1985.
Alex Shinn, John Cowan, & Arthur A. Gleckler, eds., Revised7 Report on the Algorithmic Language Scheme (R7RS Small), 2013. https://small.r7rs.org
Sebastiano Vigna, A PRNG shootout, 2026. https://prng.di.unimi.it
ISO/IEC 9899:2024. Programming languages — C (C23). ISO/IEC, 2024.
Alaric Snell-Pym. Some thoughts on random number generation. Communication to the R7RS WG2 mailing list, March 2026.
Sebastian Egner. SRFI 27: Sources of random bits. https://srfi.schemers.org/srfi-27/, 2002.
Shiro Kawai, John Cowan, and Thomas Gilray. SRFI 158: Generators and Accumulators. https://srfi.schemers.org/srfi-158/, 2017.
Shiro Kawai, Arvydas Silanskas, Linas Vepštas, and John Cowan. SRFI 194: Random data generators. https://srfi.schemers.org/srfi-194/, 2020.
Taylor Campbell. Personal communication, 2025. Available on the R7RS issue tracker.
© 2026 Wolfgang Corcoran-Mathe.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.