(Random): New text about the default random state,

following suggestions by Stephen Uitti.

diff --git a/THANKS b/THANKS
index 9d6f4b19d798e3353f8c38d1f0265da428dcda44..d42f853615a1d8d78905e9c945b35fa55b5e870e 100644 (file)
--- a/THANKS
+++ b/THANKS
@@ -83,6 +83,7 @@ For fixes or providing information which led to a fix:
           Issac Trotts
            Greg Troxel
        Aaron M. Ucko
+        Stephen Uitti
         Momchil Velikov
      Panagiotis Vossos
         Neil W. Van Dyke

diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog
index 0b7b9050579a80bd164522eabb351f28d7830f45..6d14d44f37845599ba945a6167beb8ecdf8ff3aa 100644 (file)
--- a/doc/ref/ChangeLog
+++ b/doc/ref/ChangeLog
@@ -1,3 +1,8 @@
+2008-02-11  Neil Jerram  <neil@ossau.uklinux.net>
+
+       * api-data.texi (Random): New text about the default random state,
+       following suggestions by Stephen Uitti.
+
 2008-02-01  Neil Jerram  <neil@ossau.uklinux.net>
 
        * api-scheduling.texi (Threads): Add "C Function scm_join_thread"

diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
index 93692fa701bb4dcf934cc76d55452eadc1f32152..e4afa615d9a769612d233697ff5c7049b3c60a0a 100755 (executable)
--- a/doc/ref/api-data.texi
+++ b/doc/ref/api-data.texi
@@ -1727,6 +1727,46 @@ The global random state used by the above functions when the
 @var{state} parameter is not given.
 @end defvar
 
+Note that the initial value of @code{*random-state*} is the same every
+time Guile starts up.  Therefore, if you don't pass a @var{state}
+parameter to the above procedures, and you don't set
+@code{*random-state*} to @code{(seed->random-state your-seed)}, where
+@code{your-seed} is something that @emph{isn't} the same every time,
+you'll get the same sequence of ``random'' numbers on every run.
+
+For example, unless the relevant source code has changed, @code{(map
+random (cdr (iota 30)))}, if the first use of random numbers since
+Guile started up, will always give:
+
+@lisp
+(map random (cdr (iota 19)))
+@result{}
+(0 1 1 2 2 2 1 2 6 7 10 0 5 3 12 5 5 12)
+@end lisp
+
+To use the time of day as the random seed, you can use code like this:
+
+@lisp
+(let ((time (gettimeofday)))
+  (set! *random-state*
+        (seed->random-state (+ (car time)
+                               (cdr time)))))
+@end lisp
+
+@noindent
+And then (depending on the time of day, of course):
+
+@lisp
+(map random (cdr (iota 19)))
+@result{}
+(0 0 1 0 2 4 5 4 5 5 9 3 10 1 8 3 14 17)
+@end lisp
+
+For security applications, such as password generation, you should use
+more bits of seed.  Otherwise an open source password generator could
+be attacked by guessing the seed@dots{} but that's a subject for
+another manual.
+
 
 @node Characters
 @subsection Characters