Math::Random::MT::Auto(3pm)

1Math::Random::MT::Auto(U3s)er Contributed Perl DocumentatMiaotnh::Random::MT::Auto(3)
2
3
4

NAME

6       Math::Random::MT::Auto - Auto-seeded Mersenne Twister PRNGs
7

VERSION

9       This documentation refers to Math::Random::MT::Auto version 5.04
10

SYNOPSIS

12        use strict;
13        use warnings;
14        use Math::Random::MT::Auto qw(rand irand shuffle gaussian),
15                                   '/dev/urandom' => 256,
16                                   'random_org';
17
18        # Functional interface
19        my $die_roll = 1 + int(rand(6));
20
21        my $coin_flip = (irand() & 1) ? 'heads' : 'tails';
22
23        my $deck = shuffle(1 .. 52);
24
25        my $rand_IQ = gaussian(15, 100);
26
27        # OO interface
28        my $prng = Math::Random::MT::Auto->new('SOURCE' => '/dev/random');
29
30        my $angle = $prng->rand(360);
31
32        my $decay_interval = $prng->exponential(12.4);
33

DESCRIPTION

35       The Mersenne Twister is a fast pseudorandom number generator (PRNG)
36       that is capable of providing large volumes (> 10^6004) of "high qual‐
37       ity" pseudorandom data to applications that may exhaust available
38       "truly" random data sources or system-provided PRNGs such as rand.
39
40       This module provides PRNGs that are based on the Mersenne Twister.
41       There is a functional interface to a single, standalone PRNG, and an OO
42       interface (based on the inside-out object model as implemented by the
43       Object::InsideOut module) for generating multiple PRNG objects.  The
44       PRNGs are self-seeding, automatically acquiring a (19968-bit) random
45       seed from user-selectable sources.
46
47       Random Number Deviates
48           In addition to integer and floating-point uniformly-distributed
49           random number deviates (i.e., "irand" and "rand"), this module
50           implements the following non-uniform deviates as found in Numerical
51           Recipes in C:
52
53               * Gaussian (normal)
54               * Exponential
55               * Erlang (gamma of integer order)
56               * Poisson
57               * Binomial
58       Shuffling
59           This module also provides a subroutine/method for shuffling data
60           based on the Fisher-Yates shuffling algorithm.
61
62       Support for 64-bit Integers
63           If Perl has been compiled to support 64-bit integers (do perl -V
64           and look for "use64bitint=define"), then this module will use a
65           64-bit-integer version of the Mersenne Twister, thus providing
66           64-bit random integers and 52-bit random doubles.  The size of
67           integers returned by "irand", and used by "get_seed" and "set_seed"
68           will be sized accordingly.
69
70           Programmatically, the size of Perl's integers can be determined
71           using the "Config" module:
72
73            use Config;
74            print("Integers are $Config{'uvsize'} bytes in length\n");
75
76       The code for this module has been optimized for speed.  Under Cygwin,
77       it's 2.5 times faster than Math::Random::MT, and under Solaris, it's
78       more than four times faster.  (Math::Random::MT fails to build under
79       Windows.)
80

QUICKSTART

82       To use this module as a drop-in replacement for Perl's built-in rand
83       function, just add the following to the top of your application code:
84
85        use strict;
86        use warnings;
87        use Math::Random::MT::Auto 'rand';
88
89       and then just use "rand" as you would normally.  You don't even need to
90       bother seeding the PRNG (i.e., you don't need to call "srand"), as that
91       gets done automatically when the module is loaded by Perl.
92
93       If you need multiple PRNGs, then use the OO interface:
94
95        use strict;
96        use warnings;
97        use Math::Random::MT::Auto;
98
99        my $prng1 = Math::Random::MT::Auto->new();
100        my $prng2 = Math::Random::MT::Auto->new();
101
102        my $rand_num = $prng1->rand();
103        my $rand_int = $prng2->irand();
104
105       CAUTION: If you want to require this module, see the "Delayed Importa‐
106       tion" section for important information.
107

MODULE DECLARATION

109       Subroutine Declarations
110
111       By default, this module does not automatically export any of its sub‐
112       routines.  If you want to use the standalone PRNG, then you should
113       specify the subroutines you want to use when you declare the module:
114
115        use Math::Random::MT::Auto qw(rand irand shuffle gaussian
116                                      exponential erlang poisson binomial
117                                      srand get_seed set_seed get_state set_state);
118
119       Without the above declarations, it is still possible to use the stand‐
120       alone PRNG by accessing the subroutines using their fully-qualified
121       names.  For example:
122
123        my $rand = Math::Random::MT::Auto::rand();
124
125       Module Options
126
127       Seeding Sources
128           Starting the PRNGs with a 19968-bit random seed (312 64-bit inte‐
129           gers or 624 32-bit integers) takes advantage of their full range of
130           possible internal vectors states.  This module attempts to acquire
131           such seeds using several user-selectable sources.
132
133           (I would be interested to hear about other random data sources for
134           possible inclusion in future versions of this module.)
135
136           Random Devices
137               Most OSs offer some sort of device for acquiring random num‐
138               bers.  The most common are /dev/urandom and /dev/random.  You
139               can specify the use of these devices for acquiring the seed for
140               the PRNG when you declare this module:
141
142                use Math::Random::MT::Auto '/dev/urandom';
143                  # or
144                my $prng = Math::Random::MT::Auto->new('SOURCE' => '/dev/random');
145
146               or they can be specified when using "srand".
147
148                srand('/dev/random');
149                  # or
150                $prng->srand('/dev/urandom');
151
152               The devices are accessed in non-blocking mode so that if there
153               is insufficient data when they are read, the application will
154               not hang waiting for more.
155
156           File of Binary Data
157               Since the above devices are just files as far as Perl is con‐
158               cerned, you can also use random data previously stored in files
159               (in binary format).
160
161                srand('C:\\Temp\\RANDOM.DAT');
162                  # or
163                $prng->srand('/tmp/random.dat');
164
165           Internet Sites
166               This module provides support for acquiring seed data from sev‐
167               eral Internet sites:  random.org, HotBits and RandomNum‐
168               bers.info.  An Internet connection and LWP::UserAgent are
169               required to utilize these sources.
170
171                use Math::Random::MT::Auto 'random_org';
172                  # or
173                use Math::Random::MT::Auto 'hotbits';
174                  # or
175                use Math::Random::MT::Auto 'rn_info';
176
177               If you connect to the Internet through an HTTP proxy, then you
178               must set the http_proxy variable in your environment when using
179               these sources.  (See "Proxy attributes" in LWP::UserAgent.)
180
181               The HotBits site will only provide a maximum of 2048 bytes of
182               data per request, and RandomNumbers.info's maximum is 1000.  If
183               you want to get the full seed from these sites, then you can
184               specify the source multiple times:
185
186                my $prng = Math::Random::MT::Auto->new('SOURCE' => ['hotbits',
187                                                                    'hotbits']);
188
189               or specify multiple sources:
190
191                use Math::Random::MT::Auto qw(rn_info hotbits random_org);
192
193           Windows XP Random Data
194               Under MSWin32 on Windows XP, you can acquire random seed data
195               from the system.
196
197                use Math::Random::MT::Auto 'win32';
198
199               To utilize this option, you must have the Win32::API module
200               installed.
201
202           User-defined Seeding Source
203               A subroutine reference may be specified as a seeding source.
204               When called, it will be passed three arguments:  A array refer‐
205               ence where seed data is to be added, and the number of integers
206               (64- or 32-bit as the case may be) needed.
207
208                sub MySeeder
209                {
210                    my $seed = $_[0];
211                    my $need = $_[1];
212
213                    while ($need--) {
214                        my $data = ...;      # Get seed data from your source
215                        ...
216                        push(@{$seed}, $data);
217                    }
218                }
219
220                my $prng = Math::Random::MT::Auto->new(\&MySeeder);
221
222           The default list of seeding sources is determined when the module
223           is loaded.  Under MSWin32 on Windows XP, "win32" is added to the
224           list if Win32::API is available.  Otherwise, /dev/urandom and then
225           /dev/random are checked.  The first one found is added to the list.
226           Finally, "random_org" is added.
227
228           For the functional interface to the standalone PRNG, these defaults
229           can be overridden by specifying the desired sources when the module
230           is declared, or through the use of the "srand" subroutine.  Simi‐
231           larly for the OO interface, they can be overridden in the ->new()
232           method when the PRNG is created, or later using the "srand" method.
233
234           Optionally, the maximum number of integers (64- or 32-bits as the
235           case may be) to be acquired from a particular source may be speci‐
236           fied:
237
238            # Get at most 1024 bytes from random.org
239            # Finish the seed using data from /dev/urandom
240            use Math::Random::MT::Auto 'random_org' => (1024 / $Config{'uvsize'}),
241                                       '/dev/urandom';
242
243       Delayed Seeding
244           Normally, the standalone PRNG is automatically seeded when the mod‐
245           ule is loaded.  This behavior can be modified by supplying the
246           ":!auto" (or ":noauto") flag when the module is declared.  (The
247           PRNG will still be seeded using data such as time() and PID ($$),
248           just in case.)  When the ":!auto" option is used, the "srand" sub‐
249           routine should be imported, and then run before calling any of the
250           random number deviates.
251
252            use Math::Random::MT::Auto qw(rand srand :!auto);
253              ...
254            srand();
255              ...
256            my $rn = rand(10);
257
258       Delayed Importation
259
260       If you want to delay the importation of this module using require, then
261       you need to execute its "import" function to complete the module's ini‐
262       tialization:
263
264        eval {
265            require Math::Random::MT::Auto;
266            # Add options to the import call, as desired.
267            import Math::Random::MT::Auto qw(rand random_org);
268        };
269

OBJECT CREATION

271       The OO interface for this module allows you to create multiple, inde‐
272       pendent PRNGs.
273
274       If your application will only be using the OO interface, then declare
275       this module using the :!auto flag to forestall the automatic seeding of
276       the standalone PRNG:
277
278        use Math::Random::MT::Auto ':!auto';
279
280       Math::Random::MT::Auto->new
281            my $prng = Math::Random::MT::Auto->new( %options );
282
283           Creates a new PRNG.  With no options, the PRNG is seeded using the
284           default sources that were determined when the module was loaded, or
285           that were last supplied to the "srand" subroutine.
286
287           'STATE' => $prng_state
288               Sets the newly created PRNG to the specified state.  The PRNG
289               will then function as a clone of the RPNG that the state was
290               obtained from (at the point when then state was obtained).
291
292               When the "STATE" option is used, any other options are just
293               stored (i.e., they are not acted upon).
294
295           'SEED' => $seed_array_ref
296               When the "STATE" option is not used, this option seeds the
297               newly created PRNG using the supplied seed data.  Otherwise,
298               the seed data is just copied to the new object.
299
300           'SOURCE' => 'source'
301           'SOURCE' => ['source', ...]
302               Specifies the seeding source(s) for the PRNG.  If the "STATE"
303               and "SEED" options are not used, then seed data will be immedi‐
304               ately fetched using the specified sources, and used to seed the
305               PRNG.
306
307               The source list is retained for later use by the "srand"
308               method.  The source list may be replaced by calling the "srand"
309               method.
310
311               'SOURCES', 'SRC' and 'SRCS' can all be used as synonyms for
312               'SOURCE'.
313
314           The options above are also supported using lowercase and mixed-case
315           names (e.g., 'Seed', 'src', etc.).
316
317       $obj->new
318            my $prng2 = $prng1->new( %options );
319
320           Creates a new PRNG in the same manner as "Math::Ran‐
321           dom::MT::Auto->new".
322
323       $obj->clone
324            my $prng2 = $prng1->clone();
325
326           Creates a new PRNG that is a copy of the referenced PRNG.
327

SUBROUTINES/METHODS

329       When any of the functions listed below are invoked as subroutines, they
330       operates with respect to the standalone PRNG.  For example:
331
332        my $rand = rand();
333
334       When invoked as methods, they operate on the referenced PRNG object:
335
336        my $rand = $prng->rand();
337
338       For brevity, only usage examples for the functional interface are given
339       below.
340
341       rand
342            my $rn = rand();
343            my $rn = rand($num);
344
345           Behaves exactly like Perl's built-in rand, returning a number uni‐
346           formly distributed in [0, $num).  ($num defaults to 1.)
347
348           NOTE: If you still need to access Perl's built-in rand function,
349           you can do so using "CORE::rand()".
350
351       irand
352            my $int = irand();
353
354           Returns a random integer.  For 32-bit integer Perl, the range is 0
355           to 2^32-1 (0xFFFFFFFF) inclusive.  For 64-bit integer Perl, it's 0
356           to 2^64-1 inclusive.
357
358           This is the fastest way to obtain random numbers using this module.
359
360       shuffle
361            my $shuffled = shuffle($data, ...);
362            my $shuffled = shuffle(@data);
363            my $shuffled = shuffle(\@data);
364
365           Returns an array reference containing a random ordering of the sup‐
366           plied arguments (i.e., shuffled) by using the Fisher-Yates shuf‐
367           fling algorithm.  If called with a single array reference (fastest
368           method), the contents of the array are shuffled in situ.
369
370       gaussian
371            my $gn = gaussian();
372            my $gn = gaussian($sd);
373            my $gn = gaussian($sd, $mean);
374
375           Returns floating-point random numbers from a Gaussian (normal) dis‐
376           tribution (i.e., numbers that fit a bell curve).  If called with no
377           arguments, the distribution uses a standard deviation of 1, and a
378           mean of 0.  Otherwise, the supplied argument(s) will be used for
379           the standard deviation, and the mean.
380
381       exponential
382            my $xn = exponential();
383            my $xn = exponential($mean);
384
385           Returns floating-point random numbers from an exponential distribu‐
386           tion.  If called with no arguments, the distribution uses a mean of
387           1.  Otherwise, the supplied argument will be used for the mean.
388
389           An example of an exponential distribution is the time interval
390           between independent Poisson-random events such as radioactive
391           decay.  In this case, the mean is the average time between events.
392           This is called the mean life for radioactive decay, and its inverse
393           is the decay constant (which represents the expected number of
394           events per unit time).  The well known term half-life is given by
395           "mean * ln(2)".
396
397       erlang
398            my $en = erlang($order);
399            my $en = erlang($order, $mean);
400
401           Returns floating-point random numbers from an Erlang distribution
402           of specified order.  The order must be a positive integer (> 0).
403           The mean, if not specified, defaults to 1.
404
405           The Erlang distribution is the distribution of the sum of $order
406           independent identically distributed random variables each having an
407           exponential distribution.  (It is a special case of the gamma dis‐
408           tribution for which $order is a positive integer.)  When "$order =
409           1", it is just the exponential distribution.  It is named after A.
410           K. Erlang who developed it to predict waiting times in queuing sys‐
411           tems.
412
413       poisson
414            my $pn = poisson($mean);
415            my $pn = poisson($rate, $time);
416
417           Returns integer random numbers (>= 0) from a Poisson distribution
418           of specified mean (rate * time = mean).  The mean must be a posi‐
419           tive value (> 0).
420
421           The Poisson distribution predicts the probability of the number of
422           Poisson-random events occurring in a fixed time if these events
423           occur with a known average rate.  Examples of events that can be
424           modeled as Poisson distributions include:
425
426               * The number of decays from a radioactive sample within a given
427               time period.
428               * The number of cars that pass a certain point on a road within
429               a given time period.
430               * The number of phone calls to a call center per minute.
431               * The number of road kill found per a given length of road.
432       binomial
433            my $bn = binomial($prob, $trials);
434
435           Returns integer random numbers (>= 0) from a binomial distribution.
436           The probability ($prob) must be between 0.0 and 1.0 (inclusive),
437           and the number of trials must be >= 0.
438
439           The binomial distribution is the discrete probability distribution
440           of the number of successes in a sequence of $trials independent
441           Bernoulli trials (i.e., yes/no experiments), each of which yields
442           success with probability $prob.
443
444           If the number of trials is very large, the binomial distribution
445           may be approximated by a Gaussian distribution. If the average num‐
446           ber of successes is small ("$prob * $trials < 1"), then the bino‐
447           mial distribution can be approximated by a Poisson distribution.
448
449       srand
450            srand();
451            srand('source', ...);
452
453           This (re)seeds the PRNG.  It may be called anytime reseeding of the
454           PRNG is desired (although this should normally not be needed).
455
456           When the :!auto flag is used, the "srand" subroutine should be
457           called before any other access to the standalone PRNG.
458
459           When called without arguments, the previously determined/specified
460           seeding source(s) will be used to seed the PRNG.
461
462           Optionally, seeding sources may be supplied as arguments as when
463           using the 'SOURCE' option.  (These sources will be saved and used
464           again if "srand" is subsequently called without arguments).
465
466            # Get 250 integers of seed data from Hotbits,
467            #  and then get the rest from /dev/random
468            srand('hotbits' => 250, '/dev/random');
469
470           If called with integer data (a list of one or more value, or an
471           array of values), or a reference to an array of integers, these
472           data will be passed to "set_seed" for use in reseeding the PRNG.
473
474           NOTE: If you still need to access Perl's built-in srand function,
475           you can do so using "CORE::srand($seed)".
476
477       get_seed
478            my @seed = get_seed();
479              # or
480            my $seed = get_seed();
481
482           Returns an array or an array reference containing the seed last
483           sent to the PRNG.
484
485           NOTE: Changing the data in the array will not cause any changes in
486           the PRNG (i.e., it will not reseed it).  You need to use "srand" or
487           "set_seed" for that.
488
489       set_seed
490            set_seed($seed, ...);
491            set_seed(@seed);
492            set_seed(\@seed);
493
494           When called with integer data (a list of one or more value, or an
495           array of values), or a reference to an array of integers, these
496           data will be used to reseed the PRNG.
497
498           Together with "get_seed", "set_seed" may be useful for setting up
499           identical sequences of random numbers based on the same seed.
500
501           It is possible to seed the PRNG with more than 19968 bits of data
502           (312 64-bit integers or 624 32-bit integers).  However, doing so
503           does not make the PRNG "more random" as 19968 bits more than covers
504           all the possible PRNG state vectors.
505
506       get_state
507            my @state = get_state();
508              # or
509            my $state = get_state();
510
511           Returns an array (for list context) or an array reference (for
512           scalar context) containing the current state vector of the PRNG.
513
514           Note that the state vector is not a full serialization of the PRNG.
515           (See "Serialization" below.)
516
517       set_state
518            set_state(@state);
519              # or
520            set_state($state);
521
522           Sets a PRNG to the state contained in an array or array reference
523           containing the state previously obtained using "get_state".
524
525            # Get the current state of the PRNG
526            my @state = get_state();
527
528            # Run the PRNG some more
529            my $rand1 = irand();
530
531            # Restore the previous state of the PRNG
532            set_state(@state);
533
534            # Get another random number
535            my $rand2 = irand();
536
537            # $rand1 and $rand2 will be equal.
538
539           CAUTION:  It should go without saying that you should not modify
540           the values in the state vector obtained from "get_state".  Doing so
541           and then feeding it to "set_state" would be (to say the least)
542           naughty.
543

INSIDE-OUT OBJECTS

545       By using Object::InsideOut, Math::Random::MT::Auto's PRNG objects sup‐
546       port the following capabilities:
547
548       Cloning
549
550       Copies of PRNG objects can be created using the "->clone()" method.
551
552        my $prng2 = $prng->clone();
553
554       See "Object Cloning" in Object::InsideOut for more details.
555
556       Serialization
557
558       PRNG objects can be serialized using the "->dump()" method.
559
560        my $array_ref = $prng->dump();
561          # or
562        my $string = $prng->dump(1);
563
564       Serialized object can then be converted back into PRNG objects:
565
566        my $prng2 = Object::InsideOut->pump($array_ref);
567
568       See "Object Serialization" in Object::InsideOut for more details.
569
570       Serialization using Storable is also supported:
571
572        use Storable qw(freeze thaw);
573
574        BEGIN {
575            $Math::Random::MT::Auto::storable = 1;
576        }
577        use Math::Random::MT::Auto ...;
578
579        my $prng = Math::Random::MT::Auto->new();
580
581        my $tmp = $prng->freeze();
582        my $prng2 = thaw($tmp);
583
584       See "Storable" in Object::InsideOut for more details.
585
586       NOTE: Code refs cannot be serialized. Therefore, any "User-defined
587       Seeding Source" subroutines used in conjuction with "srand" will be
588       filtered out from the serialized results.
589
590       Coercion
591
592       Various forms of object coercion are supported through the overload
593       mechanism.  For instance, you want to use a PRNG object directly in a
594       string:
595
596        my $prng = Math::Random::MT::Auto->new();
597        print("Here's a random integer: $prng\n");
598
599       The stringification of the PRNG object is accomplished by calling
600       "->irand()" on the object, and returning the integer so obtained as the
601       coerced result.
602
603       Similarly, when used in a numeric context:
604
605        my $neg_rand = 0 - $prng;
606
607       (NOTE:  There is a bug in the overload module associated with 64-bit
608       integer Perl that causes the integer returned by the "->irand()" call
609       to be returned as a floating point number.)
610
611       In a boolean context, the coersion returns true or false based on
612       whether the call to "->irand()" returns an odd or even result:
613
614        if ($prng) {
615            print("Heads - I win!\n");
616        } else {
617            print("Tails - You lose.\n");
618        }
619
620       In an array context, the coercion returns a single integer result:
621
622        my @rands = @{$prng};
623
624       This may not be all that useful, so you can call the "->array()" method
625       directly with a integer argument for the number of random integers
626       you'd like:
627
628        # Get 20 random integers
629        my @rands = @{$prng->array(20)};
630
631       Finally, a PRNG object can be used to produce a code reference that
632       will return random integers each time it is invoked:
633
634        my $rand = \&{$prng};
635        my $int = &$rand;
636
637       See "Object Coercion" in Object::InsideOut for more details.
638
639       Thread Support
640
641       Math::Random::MT::Auto provides thread support to the extent documented
642       in "THREAD SUPPORT" in Object::InsideOut with the exception of the
643       standalone PRNG.
644
645       In a threaded application (i.e., "use threads;"), PRNG objects from one
646       thread will be copied and made available in a child thread.
647
648       To enable the sharing of PRNG objects between threads, do the following
649       in your application:
650
651        use threads;
652        use threads::shared;
653
654        BEGIN {
655            $Math::Random::MT::Auto::shared = 1;
656        }
657        use Math::Random::MT::Auto ...;
658
659       NOTE: Code refs cannot be shared between threads. Therefore, you cannot
660       use "User-defined Seeding Source" subroutines in conjuction with
661       "srand" when "use threads::shared;" is in effect.
662
663       The standalone PRNG can be used safely to generate random numbers in
664       threaded applications.  When "use threads::shared;" is in effect, any
665       operations on the standalone PRNG are fully supported.  However, if
666       only "use threads;" is in effect, then changes made to the standalone
667       PRNG in one thread (e.g., by calling "srand()") will affect the stand‐
668       alone PRNG in other threads in a inconsistent manner (e.g., the results
669       of "get_seed()" will differ between the threads).
670

EXAMPLES

672       Cloning the standalone PRNG to an object
673            use Math::Random::MT::Auto qw(rand irand get_state);
674
675            my $prng = Math::Random::MT::Auto->new('STATE' => scalar(get_state()));
676
677           The standalone PRNG and the PRNG object will now return the same
678           sequence of pseudorandom numbers.
679
680       Included in this module's distribution are several sample programs
681       (located in the samples sub-directory) that illustrate the use of the
682       various random number deviates and other features supported by this
683       module.
684

DIAGNOSTICS

686       WARNINGS
687
688       Warnings are generated by this module primarily when problems are
689       encountered while trying to obtain random seed data for the PRNGs.
690       This may occur after the module is loaded, after a PRNG object is cre‐
691       ated, or after calling "srand".
692
693       These seed warnings are not critical in nature.  The PRNG will still be
694       seeded (at a minimum using data such as time() and PID ($$)), and can
695       be used safely.
696
697       The following illustrates how such warnings can be trapped for program‐
698       matic handling:
699
700        my @WARNINGS;
701        BEGIN {
702            $SIG{__WARN__} = sub { push(@WARNINGS, @_); };
703        }
704
705        use Math::Random::MT::Auto;
706
707        # Check for standalone PRNG warnings
708        if (@WARNINGS) {
709            # Handle warnings as desired
710            ...
711            # Clear warnings
712            undef(@WARNINGS);
713        }
714
715        my $prng = Math::Random::MT::Auto->new();
716
717        # Check for PRNG object warnings
718        if (@WARNINGS) {
719            # Handle warnings as desired
720            ...
721            # Clear warnings
722            undef(@WARNINGS);
723        }
724
725       * Failure opening random device '...': ...
726           The specified device (e.g., /dev/random) could not be opened by the
727           module.  Further diagnostic information should be included with
728           this warning message (e.g., device does not exist, permission prob‐
729           lem, etc.).
730
731       * Failure setting non-blocking mode on random device '...': ...
732           The specified device could not be set to non-blocking mode.  Fur‐
733           ther diagnostic information should be included with this warning
734           message (e.g., permission problem, etc.).
735
736       * Failure reading from random device '...': ...
737           A problem occurred while trying to read from the specified device.
738           Further diagnostic information should be included with this warning
739           message.
740
741       * Random device '...' exhausted
742           The specified device did not supply the requested number of random
743           numbers for the seed.  It could possibly occur if /dev/random is
744           used too frequently.  It will occur if the specified device is a
745           file, and it does not have enough data in it.
746
747       * Failure creating user-agent: ...
748           To utilize the option of acquiring seed data from Internet sources,
749           you need to install the LWP::UserAgent module.
750
751       * Failure contacting XXX: ...
752       * Failure getting data from XXX: 500 Can't connect to ... (connect:
753       timeout)
754           You need to have an Internet connection to utilize "Internet Sites"
755           as random seed sources.
756
757           If you connect to the Internet through an HTTP proxy, then you must
758           set the http_proxy variable in your environment when using the
759           Internet seed sources.  (See "Proxy attributes" in LWP::UserAgent.)
760
761           This module sets a 5 second timeout for Internet connections so
762           that if something goes awry when trying to get seed data from an
763           Internet source, your application will not hang for an inordinate
764           amount of time.
765
766       * You have exceeded your 24-hour quota for HotBits.
767           The HotBits site has a quota on the amount of data you can request
768           in a 24-hour period.  (I don't know how big the quota is.)  There‐
769           fore, this source may fail to provide any data if used too often.
770
771       * Failure acquiring Win XP random data: ...
772           A problem occurred while trying to acquire seed data from the Win‐
773           dow XP random source.  Further diagnostic information should be
774           included with this warning message.
775
776       * Unknown seeding source: ...
777           The specified seeding source is not recognized by this module.
778
779           This error also occurs if you try to use the win32 random data
780           source on something other than MSWin32 on Windows XP.
781
782           See "Seeding Sources" for more information.
783
784       * No seed data obtained from sources - Setting minimal seed using PID
785       and time
786           This message will occur in combination with some other message(s)
787           above.
788
789           If the module cannot acquire any seed data from the specified
790           sources, then data such as time() and PID ($$) will be used to seed
791           the PRNG.
792
793       * Partial seed - only X of Y
794           This message will occur in combination with some other message(s)
795           above.  It informs you of how much seed data was acquired vs. how
796           much was needed.
797
798       ERRORS
799
800       This module uses "Exception::Class" for reporting errors.  The base
801       error class provided by Object::InsideOut is "OIO".  Here is an example
802       of the basic manner for trapping and handling errors:
803
804        my $obj;
805        eval { $obj = Math::Random::MT::Auto->new(); };
806        if (my $e = OIO->caught()) {
807            print(STDERR "Failure creating new PRNG: $e\n");
808            exit(1);
809        }
810
811       Errors specific to this module have a base class of "MRMA::Args", and
812       have the following error messages:
813
814       * Missing argument to 'set_seed'
815           "set_seed" must be called with an array ref, or a list of integer
816           seed data.
817

PERFORMANCE

819       Under Cygwin, this module is 2.5 times faster than Math::Random::MT,
820       and under Solaris, it's more than four times faster.  (Math::Random::MT
821       fails to build under Windows.)  The file samples/timings.pl, included
822       in this module's distribution, can be used to compare timing results.
823
824       If you connect to the Internet via a phone modem, acquiring seed data
825       may take a second or so.  This delay might be apparent when your appli‐
826       cation is first started, or when creating a new PRNG object.  This is
827       especially true if you specify multiple "Internet Sites" (so as to get
828       the full seed from them) as this results in multiple accesses to the
829       Internet.  (If /dev/urandom is available on your machine, then you
830       should definitely consider using the Internet sources only as a sec‐
831       ondary source.)
832

DEPENDENCIES

834       Installation
835
836       A 'C' compiler is required for building this module.
837
838       This module uses the following 'standard' modules for installation:
839
840           ExtUtils::MakeMaker
841           File::Spec
842           Test::More
843
844       Operation
845
846       Requires Perl 5.6.0 or later.
847
848       This module uses the following 'standard' modules:
849
850           Scalar::Util (1.18 or later)
851           Carp
852           Fcntl
853           DynaLoader
854           Exporter
855
856       This module uses the following modules available through CPAN:
857
858           Object::InsideOut (2.06 or later)
859           Exception::Class (1.22 or later)
860
861       To utilize the option of acquiring seed data from Internet sources, you
862       need to install the LWP::UserAgent module.
863
864       To utilize the option of acquiring seed data from the system's random
865       data source under MSWin32 on Windows XP, you need to install the
866       Win32::API module.
867

BUGS AND LIMITATIONS

869       There are no known bugs in this module.
870
871       This module does not support multiple inheritance.
872
873       Please submit any bugs, problems, suggestions, patches, etc. to:
874       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Math-Random-MT-Auto>
875

AUTHOR

933       Jerry D. Hedden, <jdhedden AT cpan DOT org>
934

COPYRIGHT AND LICENSE

936       A C-Program for MT19937 (32- and 64-bit versions), with initialization
937       improved 2002/1/26.  Coded by Takuji Nishimura and Makoto Matsumoto,
938       and including Shawn Cokus's optimizations.
939
940        Copyright (C) 1997 - 2004, Makoto Matsumoto and Takuji Nishimura,
941         All rights reserved.
942        Copyright (C) 2005, Mutsuo Saito, All rights reserved.
943        Copyright 2005, 2006 Jerry D. Hedden <jdhedden AT cpan DOT org>
944
945       Redistribution and use in source and binary forms, with or without mod‐
946       ification, are permitted provided that the following conditions are
947       met:
948
949       1. Redistributions of source code must retain the above copyright
950          notice, this list of conditions and the following disclaimer.
951
952       2. Redistributions in binary form must reproduce the above copyright
953          notice, this list of conditions and the following disclaimer in the
954          documentation and/or other materials provided with the distribution.
955
956       3. The names of its contributors may not be used to endorse or promote
957          products derived from this software without specific prior written
958          permission.
959
960       THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
961       IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
962       TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTIC‐
963       ULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
964       CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
965       EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
966       PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
967       PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
968       LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
969       NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
970       SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
971
972        Any feedback is very welcome.
973        m-mat AT math DOT sci DOT hiroshima-u DOT ac DOT jp
974        http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html
975
976
977
978perl v5.8.8                       2006-10-09         Math::Random::MT::Auto(3)