Provided by: libmath-random-mt-auto-perl_6.23-2_amd64 bug

NAME

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

VERSION

       This documentation refers to Math::Random::MT::Auto version 6.23

SYNOPSIS

        use strict;
        use warnings;
        use Math::Random::MT::Auto qw(rand irand shuffle gaussian),
                                   '/dev/urandom' => 256,
                                   'random_org';

        # Functional interface
        my $die_roll = 1 + int(rand(6));

        my $coin_flip = (irand() & 1) ? 'heads' : 'tails';

        my @deck = shuffle(1 .. 52);

        my $rand_IQ = gaussian(15, 100);

        # OO interface
        my $prng = Math::Random::MT::Auto->new('SOURCE' => '/dev/random');

        my $angle = $prng->rand(360);

        my $decay_interval = $prng->exponential(12.4);

DESCRIPTION

       The Mersenne Twister is a fast pseudorandom number generator (PRNG) that is capable of
       providing large volumes (> 10^6004) of "high quality" pseudorandom data to applications
       that may exhaust available "truly" random data sources or system-provided PRNGs such as
       rand.

       This module provides PRNGs that are based on the Mersenne Twister.  There is a functional
       interface to a single, standalone PRNG, and an OO interface (based on the inside-out
       object model as implemented by the Object::InsideOut module) for generating multiple PRNG
       objects.  The PRNGs are normally self-seeding, automatically acquiring a (19968-bit)
       random seed from user-selectable sources.  (Manual seeding is optionally available.)

       Random Number Deviates
           In addition to integer and floating-point uniformly-distributed random number deviates
           (i.e., "irand" and "rand"), this module implements the following non-uniform deviates
           as found in Numerical Recipes in C:

               •   Gaussian (normal)

               •   Exponential

               •   Erlang (gamma of integer order)

               •   Poisson

               •   Binomial

       Shuffling
           This module also provides a subroutine/method for shuffling data based on the Fisher-
           Yates shuffling algorithm.

       Support for 64-bit Integers
           If Perl has been compiled to support 64-bit integers (do perl -V and look for
           "use64bitint=define"), then this module will use a 64-bit-integer version of the
           Mersenne Twister, thus providing 64-bit random integers and 52-bit random doubles.
           The size of integers returned by "irand", and used by "get_seed" and "set_seed" will
           be sized accordingly.

           Programmatically, the size of Perl's integers can be determined using the "Config"
           module:

            use Config;
            print("Integers are $Config{'uvsize'} bytes in length\n");

       The code for this module has been optimized for speed.  Under Cygwin, it's 2.5 times
       faster than Math::Random::MT, and under Solaris, it's more than four times faster.
       (Math::Random::MT fails to build under Windows.)

QUICKSTART

       To use this module as a drop-in replacement for Perl's built-in rand function, just add
       the following to the top of your application code:

        use strict;
        use warnings;
        use Math::Random::MT::Auto 'rand';

       and then just use "rand" as you would normally.  You don't even need to bother seeding the
       PRNG (i.e., you don't need to call "srand"), as that gets done automatically when the
       module is loaded by Perl.

       If you need multiple PRNGs, then use the OO interface:

        use strict;
        use warnings;
        use Math::Random::MT::Auto;

        my $prng1 = Math::Random::MT::Auto->new();
        my $prng2 = Math::Random::MT::Auto->new();

        my $rand_num = $prng1->rand();
        my $rand_int = $prng2->irand();

       CAUTION: If you want to require this module, see the "Delayed Importation" section for
       important information.

MODULE DECLARATION

       The module must always be declared such that its "->import()" method gets called:

        use Math::Random::MT::Auto;            # Correct

        #use Math::Random::MT::Auto ();        # Does not work because
                                               #   ->import() does not get invoked

   Subroutine Declarations
       By default, this module does not automatically export any of its subroutines.  If you want
       to use the standalone PRNG, then you should specify the subroutines you want to use when
       you declare the module:

        use Math::Random::MT::Auto qw(rand irand shuffle gaussian
                                      exponential erlang poisson binomial
                                      srand get_seed set_seed get_state set_state);

       Without the above declarations, it is still possible to use the standalone PRNG by
       accessing the subroutines using their fully-qualified names.  For example:

        my $rand = Math::Random::MT::Auto::rand();

   Module Options
       Seeding Sources
           Starting the PRNGs with a 19968-bit random seed (312 64-bit integers or 624 32-bit
           integers) takes advantage of their full range of possible internal vectors states.
           This module attempts to acquire such seeds using several user-selectable sources.

           (I would be interested to hear about other random data sources for possible inclusion
           in future versions of this module.)

           Random Devices
               Most OSs offer some sort of device for acquiring random numbers.  The most common
               are /dev/urandom and /dev/random.  You can specify the use of these devices for
               acquiring the seed for the PRNG when you declare this module:

                use Math::Random::MT::Auto '/dev/urandom';
                  # or
                my $prng = Math::Random::MT::Auto->new('SOURCE' => '/dev/random');

               or they can be specified when using "srand".

                srand('/dev/random');
                  # or
                $prng->srand('/dev/urandom');

               The devices are accessed in non-blocking mode so that if there is insufficient
               data when they are read, the application will not hang waiting for more.

           File of Binary Data
               Since the above devices are just files as far as Perl is concerned, you can also
               use random data previously stored in files (in binary format).

                srand('C:\\Temp\\RANDOM.DAT');
                  # or
                $prng->srand('/tmp/random.dat');

           Internet Sites
               This module provides support for acquiring seed data from several Internet sites:
               random.org, HotBits and RandomNumbers.info.  An Internet connection and
               LWP::UserAgent are required to utilize these sources.

                use Math::Random::MT::Auto 'random_org';
                  # or
                use Math::Random::MT::Auto 'hotbits';
                  # or
                use Math::Random::MT::Auto 'rn_info';

               If you connect to the Internet through an HTTP proxy, then you must set the
               http_proxy variable in your environment when using these sources.  (See "Proxy
               attributes" in LWP::UserAgent.)

               The HotBits site will only provide a maximum of 2048 bytes of data per request,
               and RandomNumbers.info's maximum is 1000.  If you want to get the full seed from
               these sites, then you can specify the source multiple times:

                my $prng = Math::Random::MT::Auto->new('SOURCE' => ['hotbits',
                                                                    'hotbits']);

               or specify multiple sources:

                use Math::Random::MT::Auto qw(rn_info hotbits random_org);

           Windows XP Random Data
               Under MSWin32 or Cygwin on Windows XP, you can acquire random seed data from the
               system.

                use Math::Random::MT::Auto 'win32';

               To utilize this option, you must have the Win32::API module installed.

           User-defined Seeding Source
               A subroutine reference may be specified as a seeding source.  When called, it will
               be passed three arguments:  A array reference where seed data is to be added, and
               the number of integers (64- or 32-bit as the case may be) needed.

                sub MySeeder
                {
                    my $seed = $_[0];
                    my $need = $_[1];

                    while ($need--) {
                        my $data = ...;      # Get seed data from your source
                        ...
                        push(@{$seed}, $data);
                    }
                }

                my $prng = Math::Random::MT::Auto->new('SOURCE' => \&MySeeder);

           The default list of seeding sources is determined when the module is loaded.  Under
           MSWin32 or Cygwin on Windows XP, "win32" is added to the list if Win32::API is
           available.  Otherwise, /dev/urandom and then /dev/random are checked.  The first one
           found is added to the list.  Finally, "random_org" is added.

           For the functional interface to the standalone PRNG, these defaults can be overridden
           by specifying the desired sources when the module is declared, or through the use of
           the "srand" subroutine.  Similarly for the OO interface, they can be overridden in the
           ->new() method when the PRNG is created, or later using the "srand" method.

           Optionally, the maximum number of integers (64- or 32-bits as the case may be) to be
           acquired from a particular source may be specified:

            # Get at most 1024 bytes from random.org
            # Finish the seed using data from /dev/urandom
            use Math::Random::MT::Auto 'random_org' => (1024 / $Config{'uvsize'}),
                                       '/dev/urandom';

       Delayed Seeding
           Normally, the standalone PRNG is automatically seeded when the module is loaded.  This
           behavior can be modified by supplying the ":!auto" (or ":noauto") flag when the module
           is declared.  (The PRNG will still be seeded using data such as time() and PID ($$),
           just in case.)  When the ":!auto" option is used, the "srand" subroutine should be
           imported, and then run before calling any of the random number deviates.

            use Math::Random::MT::Auto qw(rand srand :!auto);
              ...
            srand();
              ...
            my $rn = rand(10);

   Delayed Importation
       If you want to delay the importation of this module using require, then you must execute
       its "->import()" method to complete the module's initialization:

        eval {
            require Math::Random::MT::Auto;
            # You may add options to the import call, if desired.
            Math::Random::MT::Auto->import();
        };

STANDALONE PRNG OBJECT

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

OBJECT CREATION

       The OO interface for this module allows you to create multiple, independent PRNGs.

       If your application will only be using the OO interface, then declare this module using
       the :!auto flag to forestall the automatic seeding of the standalone PRNG:

        use Math::Random::MT::Auto ':!auto';

       Math::Random::MT::Auto->new
            my $prng = Math::Random::MT::Auto->new( %options );

           Creates a new PRNG.  With no options, the PRNG is seeded using the default sources
           that were determined when the module was loaded, or that were last supplied to the
           "srand" subroutine.

           'STATE' => $prng_state
               Sets the newly created PRNG to the specified state.  The PRNG will then function
               as a clone of the RPNG that the state was obtained from (at the point when then
               state was obtained).

               When the "STATE" option is used, any other options are just stored (i.e., they are
               not acted upon).

           'SEED' => $seed_array_ref
               When the "STATE" option is not used, this option seeds the newly created PRNG
               using the supplied seed data.  Otherwise, the seed data is just copied to the new
               object.

           'SOURCE' => 'source'
           'SOURCE' => ['source', ...]
               Specifies the seeding source(s) for the PRNG.  If the "STATE" and "SEED" options
               are not used, then seed data will be immediately fetched using the specified
               sources, and used to seed the PRNG.

               The source list is retained for later use by the "srand" method.  The source list
               may be replaced by calling the "srand" method.

               'SOURCES', 'SRC' and 'SRCS' can all be used as synonyms for 'SOURCE'.

           The options above are also supported using lowercase and mixed-case names (e.g.,
           'Seed', 'src', etc.).

       $obj->new
            my $prng2 = $prng1->new( %options );

           Creates a new PRNG in the same manner as "Math::Random::MT::Auto->new".

       $obj->clone
            my $prng2 = $prng1->clone();

           Creates a new PRNG that is a copy of the referenced PRNG.

SUBROUTINES/METHODS

       When any of the functions listed below are invoked as subroutines, they operates with
       respect to the standalone PRNG.  For example:

        my $rand = rand();

       When invoked as methods, they operate on the referenced PRNG object:

        my $rand = $prng->rand();

       For brevity, only usage examples for the functional interface are given below.

       rand
            my $rn = rand();
            my $rn = rand($num);

           Behaves exactly like Perl's built-in rand, returning a number uniformly distributed in
           [0, $num).  ($num defaults to 1.)

           NOTE: If you still need to access Perl's built-in rand function, you can do so using
           "CORE::rand()".

       irand
            my $int = irand();

           Returns a random integer.  For 32-bit integer Perl, the range is 0 to 2^32-1
           (0xFFFFFFFF) inclusive.  For 64-bit integer Perl, it's 0 to 2^64-1 inclusive.

           This is the fastest way to obtain random numbers using this module.

       shuffle
            my @shuffled = shuffle($data, ...);
            my @shuffled = shuffle(@data);

           Returns an array of the random ordering of the supplied arguments (i.e., shuffled) by
           using the Fisher-Yates shuffling algorithm.  It can also be called to return an array
           reference:

            my $shuffled = shuffle($data, ...);
            my $shuffled = shuffle(@data);

           If called with a single array reference (fastest method), the contents of the array
           are shuffled in situ:

            shuffle(\@data);

       gaussian
            my $gn = gaussian();
            my $gn = gaussian($sd);
            my $gn = gaussian($sd, $mean);

           Returns floating-point random numbers from a Gaussian (normal) distribution (i.e.,
           numbers that fit a bell curve).  If called with no arguments, the distribution uses a
           standard deviation of 1, and a mean of 0.  Otherwise, the supplied argument(s) will be
           used for the standard deviation, and the mean.

       exponential
            my $xn = exponential();
            my $xn = exponential($mean);

           Returns floating-point random numbers from an exponential distribution.  If called
           with no arguments, the distribution uses a mean of 1.  Otherwise, the supplied
           argument will be used for the mean.

           An example of an exponential distribution is the time interval between independent
           Poisson-random events such as radioactive decay.  In this case, the mean is the
           average time between events.  This is called the mean life for radioactive decay, and
           its inverse is the decay constant (which represents the expected number of events per
           unit time).  The well known term half-life is given by "mean * ln(2)".

       erlang
            my $en = erlang($order);
            my $en = erlang($order, $mean);

           Returns floating-point random numbers from an Erlang distribution of specified order.
           The order must be a positive integer (> 0).  The mean, if not specified, defaults to
           1.

           The Erlang distribution is the distribution of the sum of $order independent
           identically distributed random variables each having an exponential distribution.  (It
           is a special case of the gamma distribution for which $order is a positive integer.)
           When "$order = 1", it is just the exponential distribution.  It is named after A. K.
           Erlang who developed it to predict waiting times in queuing systems.

       poisson
            my $pn = poisson($mean);
            my $pn = poisson($rate, $time);

           Returns integer random numbers (>= 0) from a Poisson distribution of specified mean
           (rate * time = mean).  The mean must be a positive value (> 0).

           The Poisson distribution predicts the probability of the number of Poisson-random
           events occurring in a fixed time if these events occur with a known average rate.
           Examples of events that can be modeled as Poisson distributions include:

               •   The number of decays from a radioactive sample within a given time period.

               •   The number of cars that pass a certain point on a road within a given time
                   period.

               •   The number of phone calls to a call center per minute.

               •   The number of road kill found per a given length of road.

       binomial
            my $bn = binomial($prob, $trials);

           Returns integer random numbers (>= 0) from a binomial distribution.  The probability
           ($prob) must be between 0.0 and 1.0 (inclusive), and the number of trials must be >=
           0.

           The binomial distribution is the discrete probability distribution of the number of
           successes in a sequence of $trials independent Bernoulli trials (i.e., yes/no
           experiments), each of which yields success with probability $prob.

           If the number of trials is very large, the binomial distribution may be approximated
           by a Gaussian distribution. If the average number of successes is small ("$prob *
           $trials < 1"), then the binomial distribution can be approximated by a Poisson
           distribution.

       srand
            srand();
            srand('source', ...);

           This (re)seeds the PRNG.  It may be called anytime reseeding of the PRNG is desired
           (although this should normally not be needed).

           When the :!auto flag is used, the "srand" subroutine should be called before any other
           access to the standalone PRNG.

           When called without arguments, the previously determined/specified seeding source(s)
           will be used to seed the PRNG.

           Optionally, seeding sources may be supplied as arguments as when using the 'SOURCE'
           option.  (These sources will be saved and used again if "srand" is subsequently called
           without arguments).

            # Get 250 integers of seed data from Hotbits,
            #  and then get the rest from /dev/random
            srand('hotbits' => 250, '/dev/random');

           If called with integer data (a list of one or more value, or an array of values), or a
           reference to an array of integers, these data will be passed to "set_seed" for use in
           reseeding the PRNG.

           NOTE: If you still need to access Perl's built-in srand function, you can do so using
           "CORE::srand($seed)".

       get_seed
            my @seed = get_seed();
              # or
            my $seed = get_seed();

           Returns an array or an array reference containing the seed last sent to the PRNG.

           NOTE: Changing the data in the array will not cause any changes in the PRNG (i.e., it
           will not reseed it).  You need to use "srand" or "set_seed" for that.

       set_seed
            set_seed($seed, ...);
            set_seed(@seed);
            set_seed(\@seed);

           When called with integer data (a list of one or more value, or an array of values), or
           a reference to an array of integers, these data will be used to reseed the PRNG.

           Together with "get_seed", "set_seed" may be useful for setting up identical sequences
           of random numbers based on the same seed.

           It is possible to seed the PRNG with more than 19968 bits of data (312 64-bit integers
           or 624 32-bit integers).  However, doing so does not make the PRNG "more random" as
           19968 bits more than covers all the possible PRNG state vectors.

       get_state
            my @state = get_state();
              # or
            my $state = get_state();

           Returns an array (for list context) or an array reference (for scalar context)
           containing the current state vector of the PRNG.

           Note that the state vector is not a full serialization of the PRNG.  (See
           "Serialization" below.)

       set_state
            set_state(@state);
              # or
            set_state($state);

           Sets a PRNG to the state contained in an array or array reference containing the state
           previously obtained using "get_state".

            # Get the current state of the PRNG
            my @state = get_state();

            # Run the PRNG some more
            my $rand1 = irand();

            # Restore the previous state of the PRNG
            set_state(@state);

            # Get another random number
            my $rand2 = irand();

            # $rand1 and $rand2 will be equal.

           CAUTION:  It should go without saying that you should not modify the values in the
           state vector obtained from "get_state".  Doing so and then feeding it to "set_state"
           would be (to say the least) naughty.

INSIDE-OUT OBJECTS

       By using Object::InsideOut, Math::Random::MT::Auto's PRNG objects support the following
       capabilities:

   Cloning
       Copies of PRNG objects can be created using the "->clone()" method.

        my $prng2 = $prng->clone();

       See "Object Cloning" in Object::InsideOut for more details.

   Serialization
       PRNG objects can be serialized using the "->dump()" method.

        my $array_ref = $prng->dump();
          # or
        my $string = $prng->dump(1);

       Serialized object can then be converted back into PRNG objects:

        my $prng2 = Object::InsideOut->pump($array_ref);

       See "Object Serialization" in Object::InsideOut for more details.

       Serialization using Storable is also supported:

        use Storable qw(freeze thaw);

        BEGIN {
            $Math::Random::MT::Auto::storable = 1;
        }
        use Math::Random::MT::Auto ...;

        my $prng = Math::Random::MT::Auto->new();

        my $tmp = $prng->freeze();
        my $prng2 = thaw($tmp);

       See "Storable" in Object::InsideOut for more details.

       NOTE: Code refs cannot be serialized. Therefore, any "User-defined Seeding Source"
       subroutines used in conjunction with "srand" will be filtered out from the serialized
       results.

   Coercion
       Various forms of object coercion are supported through the overload mechanism.  For
       instance, you can to use a PRNG object directly in a string:

        my $prng = Math::Random::MT::Auto->new();
        print("Here's a random integer: $prng\n");

       The stringification of the PRNG object is accomplished by calling "->irand()" on the
       object, and returning the integer so obtained as the coerced result.

       A similar overload coercion is performed when the object is used in a numeric context:

        my $neg_rand = 0 - $prng;

       (See "BUGS AND LIMITATIONS" regarding numeric overloading on 64-bit integer Perls prior to
       5.10.)

       In a boolean context, the coercion returns true or false based on whether the call to
       "->irand()" returns an odd or even result:

        if ($prng) {
            print("Heads - I win!\n");
        } else {
            print("Tails - You lose.\n");
        }

       In an array context, the coercion returns a single integer result:

        my @rands = @{$prng};

       This may not be all that useful, so you can call the "->array()" method directly with a
       integer argument for the number of random integers you'd like:

        # Get 20 random integers
        my @rands = @{$prng->array(20)};

       Finally, a PRNG object can be used to produce a code reference that will return random
       integers each time it is invoked:

        my $rand = \&{$prng};
        my $int = &$rand;

       See "Object Coercion" in Object::InsideOut for more details.

   Thread Support
       Math::Random::MT::Auto provides thread support to the extent documented in "THREAD
       SUPPORT" in Object::InsideOut.

       In a threaded application (i.e., "use threads;"), the standalone PRNG and all the PRNG
       objects from one thread will be copied and made available in a child thread.

       To enable the sharing of PRNG objects between threads, do the following in your
       application:

        use threads;
        use threads::shared;

        BEGIN {
            $Math::Random::MT::Auto::shared = 1;
        }
        use Math::Random::MT::Auto ...;

       NOTE: Code refs cannot be shared between threads. Therefore, you cannot use "User-defined
       Seeding Source" subroutines in conjunction with "srand" when "use threads::shared;" is in
       effect.

       Depending on your needs, when using threads, but not enabling thread-sharing of PRNG
       objects as per the above, you may want to perform an "srand" call on the standalone PRNG
       and/or your PRNG objects inside the threaded code so that the pseudorandom number
       sequences generated in each thread differs.

        use threads;
        use Math::Random:MT::Auto qw(irand srand);

        my $prng = Math::Random:MT::Auto->new();

        sub thr_code
        {
            srand();
            $prng->srand();

            ....
        }

EXAMPLES

       Cloning the standalone PRNG to an object
            use Math::Random::MT::Auto qw(get_state);

            my $prng = Math::Random::MT::Auto->new('STATE' => scalar(get_state()));

           or using the standalone PRNG object directly:

            my $prng = $Math::Random::MT::Auto::SA_PRNG->clone();

           The standalone PRNG and the PRNG object will now return the same sequence of
           pseudorandom numbers.

       Included in this module's distribution are several sample programs (located in the samples
       sub-directory) that illustrate the use of the various random number deviates and other
       features supported by this module.

DIAGNOSTICS

   WARNINGS
       Warnings are generated by this module primarily when problems are encountered while trying
       to obtain random seed data for the PRNGs.  This may occur after the module is loaded,
       after a PRNG object is created, or after calling "srand".

       These seed warnings are not critical in nature.  The PRNG will still be seeded (at a
       minimum using data such as time() and PID ($$)), and can be used safely.

       The following illustrates how such warnings can be trapped for programmatic handling:

        my @WARNINGS;
        BEGIN {
            $SIG{__WARN__} = sub { push(@WARNINGS, @_); };
        }

        use Math::Random::MT::Auto;

        # Check for standalone PRNG warnings
        if (@WARNINGS) {
            # Handle warnings as desired
            ...
            # Clear warnings
            undef(@WARNINGS);
        }

        my $prng = Math::Random::MT::Auto->new();

        # Check for PRNG object warnings
        if (@WARNINGS) {
            # Handle warnings as desired
            ...
            # Clear warnings
            undef(@WARNINGS);
        }

       •   Failure opening random device '...': ...

           The specified device (e.g., /dev/random) could not be opened by the module.  Further
           diagnostic information should be included with this warning message (e.g., device does
           not exist, permission problem, etc.).

       •   Failure setting non-blocking mode on random device '...': ...

           The specified device could not be set to non-blocking mode.  Further diagnostic
           information should be included with this warning message (e.g., permission problem,
           etc.).

       •   Failure reading from random device '...': ...

           A problem occurred while trying to read from the specified device.  Further diagnostic
           information should be included with this warning message.

       •   Random device '...' exhausted

           The specified device did not supply the requested number of random numbers for the
           seed.  It could possibly occur if /dev/random is used too frequently.  It will occur
           if the specified device is a file, and it does not have enough data in it.

       •   Failure creating user-agent: ...

           To utilize the option of acquiring seed data from Internet sources, you need to
           install the LWP::UserAgent module.

       •   Failure contacting XXX: ...

       •   Failure getting data from XXX: 500 Can't connect to ... (connect: timeout)

           You need to have an Internet connection to utilize "Internet Sites" as random seed
           sources.

           If you connect to the Internet through an HTTP proxy, then you must set the http_proxy
           variable in your environment when using the Internet seed sources.  (See "Proxy
           attributes" in LWP::UserAgent.)

           This module sets a 5 second timeout for Internet connections so that if something goes
           awry when trying to get seed data from an Internet source, your application will not
           hang for an inordinate amount of time.

       •   You have exceeded your 24-hour quota for HotBits.

           The HotBits site has a quota on the amount of data you can request in a 24-hour
           period.  (I don't know how big the quota is.)  Therefore, this source may fail to
           provide any data if used too often.

       •   Failure acquiring Win XP random data: ...

           A problem occurred while trying to acquire seed data from the Window XP random source.
           Further diagnostic information should be included with this warning message.

       •   Unknown seeding source: ...

           The specified seeding source is not recognized by this module.

           This error also occurs if you try to use the win32 random data source on something
           other than MSWin32 or Cygwin on Windows XP.

           See "Seeding Sources" for more information.

       •   No seed data obtained from sources - Setting minimal seed using PID and time

           This message will occur in combination with some other message(s) above.

           If the module cannot acquire any seed data from the specified sources, then data such
           as time() and PID ($$) will be used to seed the PRNG.

       •   Partial seed - only X of Y

           This message will occur in combination with some other message(s) above.  It informs
           you of how much seed data was acquired vs. how much was needed.

   ERRORS
       This module uses "Exception::Class" for reporting errors.  The base error class provided
       by Object::InsideOut is "OIO".  Here is an example of the basic manner for trapping and
       handling errors:

        my $obj;
        eval { $obj = Math::Random::MT::Auto->new(); };
        if (my $e = OIO->caught()) {
            print(STDERR "Failure creating new PRNG: $e\n");
            exit(1);
        }

       Errors specific to this module have a base class of "MRMA::Args", and have the following
       error messages:

       •   Missing argument to 'set_seed'

           "set_seed" must be called with an array ref, or a list of integer seed data.

       •   Invalid state vector

           "set_state" was called with an incompatible state vector.  For example, a state vector
           from a 32-bit integer version of Perl being used with a 64-bit integer version of
           Perl.

PERFORMANCE

       Under Cygwin, this module is 2.5 times faster than Math::Random::MT, and under Solaris,
       it's more than four times faster.  (Math::Random::MT fails to build under Windows.)  The
       file samples/timings.pl, included in this module's distribution, can be used to compare
       timing results.

       If you connect to the Internet via a phone modem, acquiring seed data may take a second or
       so.  This delay might be apparent when your application is first started, or when creating
       a new PRNG object.  This is especially true if you specify multiple "Internet Sites" (so
       as to get the full seed from them) as this results in multiple accesses to the Internet.
       (If /dev/urandom is available on your machine, then you should definitely consider using
       the Internet sources only as a secondary source.)

DEPENDENCIES

   Installation
       A 'C' compiler is required for building this module.

       This module uses the following 'standard' modules for installation:

           ExtUtils::MakeMaker
           File::Spec
           Test::More

   Operation
       Requires Perl 5.6.0 or later.

       This module uses the following 'standard' modules:

           Scalar::Util (1.18 or later)
           Carp
           Fcntl
           XSLoader

       This module uses the following modules available through CPAN:

           Object::InsideOut (2.06 or later)
           Exception::Class (1.22 or later)

       To utilize the option of acquiring seed data from Internet sources, you need to install
       the LWP::UserAgent module.

       To utilize the option of acquiring seed data from the system's random data source under
       MSWin32 or Cygwin on Windows XP, you need to install the Win32::API module.

BUGS AND LIMITATIONS

       This module does not support multiple inheritance.

       For Perl prior to 5.10, there is a bug in the overload code associated with 64-bit
       integers that causes the integer returned by the "->irand()" call to be coerced into a
       floating-point number.  The workaround in this case is to call "->irand()" directly:

        # my $neg_rand = 0 - $prng;          # Result is a floating-point number
        my $neg_rand = 0 - $prng->irand();   # Result is an integer number

       The transfer of state vector arrays and serialized objects between 32- and 64-bit integer
       versions of Perl is not supported, and will produce an 'Invalid state vector' error.

       Please submit any bugs, problems, suggestions, patches, etc. to:
       <http://rt.cpan.org/Public/Dist/Display.html?Name=Math-Random-MT-Auto>

SEE ALSO

       Math::Random::MT::Auto on MetaCPAN: <https://metacpan.org/release/Math-Random-MT-Auto>

       Code repository: <https://github.com/jdhedden/Math-Random-MT-Auto>

       Sample code in the examples directory of this distribution on CPAN.

       The Mersenne Twister is the (current) quintessential pseudorandom number generator. It is
       fast, and has a period of 2^19937 - 1.  The Mersenne Twister algorithm was developed by
       Makoto Matsumoto and Takuji Nishimura.  It is available in 32- and 64-bit integer
       versions.  <http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html>

       Wikipedia entries on the Mersenne Twister and pseudorandom number generators, in general:
       <http://en.wikipedia.org/wiki/Mersenne_twister>, and
       <http://en.wikipedia.org/wiki/Pseudorandom_number_generator>

       random.org generates random numbers from radio frequency noise.  <http://random.org/>

       HotBits generates random number from a radioactive decay source.
       <http://www.fourmilab.ch/hotbits/>

       RandomNumbers.info generates random number from a quantum optical source.
       <http://www.randomnumbers.info/>

       OpenBSD random devices:
       <http://www.openbsd.org/cgi-bin/man.cgi?query=arandom&sektion=4&apropos=0&manpath=OpenBSD+Current&arch=>

       FreeBSD random devices:
       <http://www.freebsd.org/cgi/man.cgi?query=random&sektion=4&apropos=0&manpath=FreeBSD+5.3-RELEASE+and+Ports>

       Man pages for /dev/random and /dev/urandom on Unix/Linux/Cygwin/Solaris:
       <http://www.die.net/doc/linux/man/man4/random.4.html>

       Windows XP random data source:
       <http://blogs.msdn.com/michael_howard/archive/2005/01/14/353379.aspx>

       Fisher-Yates Shuffling Algorithm:
       <http://en.wikipedia.org/wiki/Shuffling_playing_cards#Shuffling_algorithms>, and shuffle()
       in List::Util

       Non-uniform random number deviates in Numerical Recipes in C, Chapters 7.2 and 7.3:
       <http://www.library.cornell.edu/nr/bookcpdf.html>

       Inside-out Object Model: Object::InsideOut

       Math::Random::MT::Auto::Range - Subclass of Math::Random::MT::Auto that creates range-
       valued PRNGs

       LWP::UserAgent

       Math::Random::MT

       Net::Random

AUTHOR

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

COPYRIGHT AND LICENSE

       A C-Program for MT19937 (32- and 64-bit versions), with initialization improved 2002/1/26.
       Coded by Takuji Nishimura and Makoto Matsumoto, and including Shawn Cokus's optimizations.

        Copyright (C) 1997 - 2004, Makoto Matsumoto and Takuji Nishimura,
         All rights reserved.
        Copyright (C) 2005, Mutsuo Saito, All rights reserved.
        Copyright 2005 - 2009 Jerry D. Hedden <jdhedden AT cpan DOT org>

       Redistribution and use in source and binary forms, with or without modification, are
       permitted provided that the following conditions are met:

       1. Redistributions of source code must retain the above copyright
          notice, this list of conditions and the following disclaimer.

       2. Redistributions in binary form must reproduce the above copyright
          notice, this list of conditions and the following disclaimer in the
          documentation and/or other materials provided with the distribution.

       3. The names of its contributors may not be used to endorse or promote
          products derived from this software without specific prior written
          permission.

       THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
       MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
       THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
       SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
       OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
       HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
       TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
       SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

        Any feedback is very welcome.
        m-mat AT math DOT sci DOT hiroshima-u DOT ac DOT jp
        http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html