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 6.14
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
37       quality" 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 normally self-seeding, automatically acquiring a (19968-bit)
45       random seed from user-selectable sources.  (Manual seeding is
46       optionally available.)
47
48       Random Number Deviates
49           In addition to integer and floating-point uniformly-distributed
50           random number deviates (i.e., "irand" and "rand"), this module
51           implements the following non-uniform deviates as found in Numerical
52           Recipes in C:
53
54               ·   Gaussian (normal)
55
56               ·   Exponential
57
58               ·   Erlang (gamma of integer order)
59
60               ·   Poisson
61
62               ·   Binomial
63
64       Shuffling
65           This module also provides a subroutine/method for shuffling data
66           based on the Fisher-Yates shuffling algorithm.
67
68       Support for 64-bit Integers
69           If Perl has been compiled to support 64-bit integers (do perl -V
70           and look for "use64bitint=define"), then this module will use a
71           64-bit-integer version of the Mersenne Twister, thus providing
72           64-bit random integers and 52-bit random doubles.  The size of
73           integers returned by "irand", and used by "get_seed" and "set_seed"
74           will be sized accordingly.
75
76           Programmatically, the size of Perl's integers can be determined
77           using the "Config" module:
78
79            use Config;
80            print("Integers are $Config{'uvsize'} bytes in length\n");
81
82       The code for this module has been optimized for speed.  Under Cygwin,
83       it's 2.5 times faster than Math::Random::MT, and under Solaris, it's
84       more than four times faster.  (Math::Random::MT fails to build under
85       Windows.)
86

QUICKSTART

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

MODULE DECLARATION

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

STANDALONE PRNG OBJECT

283       my $obj = $MRMA::PRNG;
284           $MRMA::PRNG is the object that represents the standalone PRNG.
285

OBJECT CREATION

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

SUBROUTINES/METHODS

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

INSIDE-OUT OBJECTS

570       By using Object::InsideOut, Math::Random::MT::Auto's PRNG objects
571       support the following capabilities:
572
573   Cloning
574       Copies of PRNG objects can be created using the "->clone()" method.
575
576        my $prng2 = $prng->clone();
577
578       See "Object Cloning" in Object::InsideOut for more details.
579
580   Serialization
581       PRNG objects can be serialized using the "->dump()" method.
582
583        my $array_ref = $prng->dump();
584          # or
585        my $string = $prng->dump(1);
586
587       Serialized object can then be converted back into PRNG objects:
588
589        my $prng2 = Object::InsideOut->pump($array_ref);
590
591       See "Object Serialization" in Object::InsideOut for more details.
592
593       Serialization using Storable is also supported:
594
595        use Storable qw(freeze thaw);
596
597        BEGIN {
598            $Math::Random::MT::Auto::storable = 1;
599        }
600        use Math::Random::MT::Auto ...;
601
602        my $prng = Math::Random::MT::Auto->new();
603
604        my $tmp = $prng->freeze();
605        my $prng2 = thaw($tmp);
606
607       See "Storable" in Object::InsideOut for more details.
608
609       NOTE: Code refs cannot be serialized. Therefore, any "User-defined
610       Seeding Source" subroutines used in conjunction with "srand" will be
611       filtered out from the serialized results.
612
613   Coercion
614       Various forms of object coercion are supported through the overload
615       mechanism.  For instance, you can to use a PRNG object directly in a
616       string:
617
618        my $prng = Math::Random::MT::Auto->new();
619        print("Here's a random integer: $prng\n");
620
621       The stringification of the PRNG object is accomplished by calling
622       "->irand()" on the object, and returning the integer so obtained as the
623       coerced result.
624
625       A similar overload coercion is performed when the object is used in a
626       numeric context:
627
628        my $neg_rand = 0 - $prng;
629
630       (See "BUGS AND LIMITATIONS" regarding numeric overloading on 64-bit
631       integer Perls prior to 5.10.)
632
633       In a boolean context, the coercion returns true or false based on
634       whether the call to "->irand()" returns an odd or even result:
635
636        if ($prng) {
637            print("Heads - I win!\n");
638        } else {
639            print("Tails - You lose.\n");
640        }
641
642       In an array context, the coercion returns a single integer result:
643
644        my @rands = @{$prng};
645
646       This may not be all that useful, so you can call the "->array()" method
647       directly with a integer argument for the number of random integers
648       you'd like:
649
650        # Get 20 random integers
651        my @rands = @{$prng->array(20)};
652
653       Finally, a PRNG object can be used to produce a code reference that
654       will return random integers each time it is invoked:
655
656        my $rand = \&{$prng};
657        my $int = &$rand;
658
659       See "Object Coercion" in Object::InsideOut for more details.
660
661   Thread Support
662       Math::Random::MT::Auto provides thread support to the extent documented
663       in "THREAD SUPPORT" in Object::InsideOut.
664
665       In a threaded application (i.e., "use threads;"), the standalone PRNG
666       and all the PRNG objects from one thread will be copied and made
667       available in a child thread.
668
669       To enable the sharing of PRNG objects between threads, do the following
670       in your application:
671
672        use threads;
673        use threads::shared;
674
675        BEGIN {
676            $Math::Random::MT::Auto::shared = 1;
677        }
678        use Math::Random::MT::Auto ...;
679
680       NOTE: Code refs cannot be shared between threads. Therefore, you cannot
681       use "User-defined Seeding Source" subroutines in conjunction with
682       "srand" when "use threads::shared;" is in effect.
683
684       Depending on your needs, when using threads, but not enabling thread-
685       sharing of PRNG objects as per the above, you may want to perform an
686       "srand" call on the standalone PRNG and/or your PRNG objects inside the
687       threaded code so that the pseudorandom number sequences generated in
688       each thread differs.
689
690        use threads;
691        use Math::Random:MT::Auto qw(irand srand);
692
693        my $prng = Math::Random:MT::Auto->new();
694
695        sub thr_code
696        {
697            srand();
698            $prng->srand();
699
700            ....
701        }
702

EXAMPLES

704       Cloning the standalone PRNG to an object
705            use Math::Random::MT::Auto qw(get_state);
706
707            my $prng = Math::Random::MT::Auto->new('STATE' => scalar(get_state()));
708
709           or using the standalone PRNG object directly:
710
711            my $prng = $Math::Random::MT::Auto::SA_PRNG->clone();
712
713           The standalone PRNG and the PRNG object will now return the same
714           sequence of pseudorandom numbers.
715
716       Included in this module's distribution are several sample programs
717       (located in the samples sub-directory) that illustrate the use of the
718       various random number deviates and other features supported by this
719       module.
720

DIAGNOSTICS

722   WARNINGS
723       Warnings are generated by this module primarily when problems are
724       encountered while trying to obtain random seed data for the PRNGs.
725       This may occur after the module is loaded, after a PRNG object is
726       created, or after calling "srand".
727
728       These seed warnings are not critical in nature.  The PRNG will still be
729       seeded (at a minimum using data such as time() and PID ($$)), and can
730       be used safely.
731
732       The following illustrates how such warnings can be trapped for
733       programmatic handling:
734
735        my @WARNINGS;
736        BEGIN {
737            $SIG{__WARN__} = sub { push(@WARNINGS, @_); };
738        }
739
740        use Math::Random::MT::Auto;
741
742        # Check for standalone PRNG warnings
743        if (@WARNINGS) {
744            # Handle warnings as desired
745            ...
746            # Clear warnings
747            undef(@WARNINGS);
748        }
749
750        my $prng = Math::Random::MT::Auto->new();
751
752        # Check for PRNG object warnings
753        if (@WARNINGS) {
754            # Handle warnings as desired
755            ...
756            # Clear warnings
757            undef(@WARNINGS);
758        }
759
760       ·   Failure opening random device '...': ...
761
762           The specified device (e.g., /dev/random) could not be opened by the
763           module.  Further diagnostic information should be included with
764           this warning message (e.g., device does not exist, permission
765           problem, etc.).
766
767       ·   Failure setting non-blocking mode on random device '...': ...
768
769           The specified device could not be set to non-blocking mode.
770           Further diagnostic information should be included with this warning
771           message (e.g., permission problem, etc.).
772
773       ·   Failure reading from random device '...': ...
774
775           A problem occurred while trying to read from the specified device.
776           Further diagnostic information should be included with this warning
777           message.
778
779       ·   Random device '...' exhausted
780
781           The specified device did not supply the requested number of random
782           numbers for the seed.  It could possibly occur if /dev/random is
783           used too frequently.  It will occur if the specified device is a
784           file, and it does not have enough data in it.
785
786       ·   Failure creating user-agent: ...
787
788           To utilize the option of acquiring seed data from Internet sources,
789           you need to install the LWP::UserAgent module.
790
791       ·   Failure contacting XXX: ...
792
793       ·   Failure getting data from XXX: 500 Can't connect to ... (connect:
794           timeout)
795
796           You need to have an Internet connection to utilize "Internet Sites"
797           as random seed sources.
798
799           If you connect to the Internet through an HTTP proxy, then you must
800           set the http_proxy variable in your environment when using the
801           Internet seed sources.  (See "Proxy attributes" in LWP::UserAgent.)
802
803           This module sets a 5 second timeout for Internet connections so
804           that if something goes awry when trying to get seed data from an
805           Internet source, your application will not hang for an inordinate
806           amount of time.
807
808       ·   You have exceeded your 24-hour quota for HotBits.
809
810           The HotBits site has a quota on the amount of data you can request
811           in a 24-hour period.  (I don't know how big the quota is.)
812           Therefore, this source may fail to provide any data if used too
813           often.
814
815       ·   Failure acquiring Win XP random data: ...
816
817           A problem occurred while trying to acquire seed data from the
818           Window XP random source.  Further diagnostic information should be
819           included with this warning message.
820
821       ·   Unknown seeding source: ...
822
823           The specified seeding source is not recognized by this module.
824
825           This error also occurs if you try to use the win32 random data
826           source on something other than MSWin32 or Cygwin on Windows XP.
827
828           See "Seeding Sources" for more information.
829
830       ·   No seed data obtained from sources - Setting minimal seed using PID
831           and time
832
833           This message will occur in combination with some other message(s)
834           above.
835
836           If the module cannot acquire any seed data from the specified
837           sources, then data such as time() and PID ($$) will be used to seed
838           the PRNG.
839
840       ·   Partial seed - only X of Y
841
842           This message will occur in combination with some other message(s)
843           above.  It informs you of how much seed data was acquired vs. how
844           much was needed.
845
846   ERRORS
847       This module uses "Exception::Class" for reporting errors.  The base
848       error class provided by Object::InsideOut is "OIO".  Here is an example
849       of the basic manner for trapping and handling errors:
850
851        my $obj;
852        eval { $obj = Math::Random::MT::Auto->new(); };
853        if (my $e = OIO->caught()) {
854            print(STDERR "Failure creating new PRNG: $e\n");
855            exit(1);
856        }
857
858       Errors specific to this module have a base class of "MRMA::Args", and
859       have the following error messages:
860
861       ·   Missing argument to 'set_seed'
862
863           "set_seed" must be called with an array ref, or a list of integer
864           seed data.
865

PERFORMANCE

867       Under Cygwin, this module is 2.5 times faster than Math::Random::MT,
868       and under Solaris, it's more than four times faster.  (Math::Random::MT
869       fails to build under Windows.)  The file samples/timings.pl, included
870       in this module's distribution, can be used to compare timing results.
871
872       If you connect to the Internet via a phone modem, acquiring seed data
873       may take a second or so.  This delay might be apparent when your
874       application is first started, or when creating a new PRNG object.  This
875       is especially true if you specify multiple "Internet Sites" (so as to
876       get the full seed from them) as this results in multiple accesses to
877       the Internet.  (If /dev/urandom is available on your machine, then you
878       should definitely consider using the Internet sources only as a
879       secondary source.)
880

DEPENDENCIES

882   Installation
883       A 'C' compiler is required for building this module.
884
885       This module uses the following 'standard' modules for installation:
886
887           ExtUtils::MakeMaker
888           File::Spec
889           Test::More
890
891   Operation
892       Requires Perl 5.6.0 or later.
893
894       This module uses the following 'standard' modules:
895
896           Scalar::Util (1.18 or later)
897           Carp
898           Fcntl
899           XSLoader
900
901       This module uses the following modules available through CPAN:
902
903           Object::InsideOut (2.06 or later)
904           Exception::Class (1.22 or later)
905
906       To utilize the option of acquiring seed data from Internet sources, you
907       need to install the LWP::UserAgent module.
908
909       To utilize the option of acquiring seed data from the system's random
910       data source under MSWin32 or Cygwin on Windows XP, you need to install
911       the Win32::API module.
912

BUGS AND LIMITATIONS

914       This module does not support multiple inheritance.
915
916       For Perl prior to 5.10, there is a bug in the overload code associated
917       with 64-bit integers that causes the integer returned by the
918       "->irand()" call to be coerced into a floating-point number.  The
919       workaround in this case is to call "->irand()" directly:
920
921        # my $neg_rand = 0 - $prng;          # Result is a floating-point number
922        my $neg_rand = 0 - $prng->irand();   # Result is an integer number
923
924       Please submit any bugs, problems, suggestions, patches, etc. to:
925       http://rt.cpan.org/Public/Dist/Display.html?Name=Math-Random-MT-Auto
926       <http://rt.cpan.org/Public/Dist/Display.html?Name=Math-Random-MT-Auto>
927

AUTHOR

996       Jerry D. Hedden, <jdhedden AT cpan DOT org>
997

COPYRIGHT AND LICENSE

999       A C-Program for MT19937 (32- and 64-bit versions), with initialization
1000       improved 2002/1/26.  Coded by Takuji Nishimura and Makoto Matsumoto,
1001       and including Shawn Cokus's optimizations.
1002
1003        Copyright (C) 1997 - 2004, Makoto Matsumoto and Takuji Nishimura,
1004         All rights reserved.
1005        Copyright (C) 2005, Mutsuo Saito, All rights reserved.
1006        Copyright 2005 - 2008 Jerry D. Hedden <jdhedden AT cpan DOT org>
1007
1008       Redistribution and use in source and binary forms, with or without
1009       modification, are permitted provided that the following conditions are
1010       met:
1011
1012       1. Redistributions of source code must retain the above copyright
1013          notice, this list of conditions and the following disclaimer.
1014
1015       2. Redistributions in binary form must reproduce the above copyright
1016          notice, this list of conditions and the following disclaimer in the
1017          documentation and/or other materials provided with the distribution.
1018
1019       3. The names of its contributors may not be used to endorse or promote
1020          products derived from this software without specific prior written
1021          permission.
1022
1023       THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
1024       IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
1025       TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
1026       PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT
1027       OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
1028       SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
1029       LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
1030       DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
1031       THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
1032       (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
1033       OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1034
1035        Any feedback is very welcome.
1036        m-mat AT math DOT sci DOT hiroshima-u DOT ac DOT jp
1037        http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html
1038
1039
1040
1041perl v5.12.0                      2008-06-11         Math::Random::MT::Auto(3)