NAME
    Data::UUID::MT - Fast random UUID generator using the Mersenne Twister
    algorithm

VERSION
    version 1.001

SYNOPSIS
      use Data::UUID::MT;
      my $ug1 = Data::UUID::MT->new( version => 4 ); # "1", "4" or "4s"
      my $ug2 = Data::UUID::MT->new();               # default is "4"

      # method interface
      my $uuid1 = $ug->create();        # 16 byte binary string
      my $uuid2 = $ug->create_hex();
      my $uuid3 = $ug->create_string();

      # iterator -- avoids some method call overhead
      my $next = $ug->iterator;
      my $uuid4 = $next->();

DESCRIPTION
    This UUID generator uses the excellent Math::Random::MT::Auto module as
    a source of fast, high-quality (pseudo) random numbers.

    Three different types of UUIDs are supported. Two are consistent with
    RFC 4122 and one is a custom variant that provides a 'sequential UUID'
    that can be advantageous when used as a primary database key.

    Note: The Mersenne Twister pseudo-random number generator has excellent
    statistical properties, but it is not considered cryptographically
    secure. Pseudo-random UUIDs are not recommended for use as security
    authentication tokens in cookies or other user-visible session
    identifiers.

  Version 1 UUIDs
    The UUID generally follows the "version 1" spec from the RFC, however
    the clock sequence and MAC address are randomly generated each time.
    (This is permissible within the spec of the RFC.) The generated MAC
    address has the the multicast bit set as mandated by the RFC to ensure
    it does not conflict with real MAC addresses. This UUID has 60 bits of
    timestamp data, 61 bits of pseudo-random data and 7 mandated bits
    (multicast bit, "variant" field and "version" field).

  Version 4 UUIDs
    The UUID follows the "version 4" spec, with 122 pseudo-random bits and 6
    mandated bits ("variant" field and "version" field).

  Version 4s UUIDs
    This is a custom UUID form that resembles "version 4" form, but that
    overlays the first 60 bits with a timestamp akin to "version 1", Unlike
    "version 1", this custom version preserves the ordering of bits from
    high to low, whereas "version 1" puts the low 32 bits of the timestamp
    first, then the middle 16 bits, then multiplexes the high bits with
    version field. This "4s" variant provides a "sequential UUID" with the
    timestamp providing order and the remaining random bits making collision
    with other UUIDs created at the exact same microsecond highly unlikely.
    This UUID has 60 timestamp bits, 62 pseudo-random bits and 6 mandated
    bits ("variant" field and "version" field).

  Unsupported: Versions 2, 3 and 5
    This module focuses on generation of UUIDs with random elements and does
    not support UUID versions 2, 3 and 5.

METHODS
  new
      my $ug = Data::UUID::MT->new( version => 4 );

    Creates a UUID generator object. The only allowed versions are "1", "4"
    and "4s". If no version is specified, it defaults to "4".

  create
      my $uuid = $ug->create;

    Returns a UUID packed into a 16 byte string.

  create_hex
      my $uuid = $ug->create_hex();

    Returns a UUID as a lowercase hex string, prefixed with "0x", e.g.
    0xb0470602a64b11da863293ebf1c0e05a

  create_string
      my $uuid = $ug->create_string(); #

    Returns UUID as a lowercase string in "standard" format, e.g.
    "b0470602-a64b-11da-8632-93ebf1c0e05a"

  iterator
      my $next = $ug->iterator;
      my $uuid = $next->();

    Returns a reference to the internal UUID generator function. Because
    this avoids method call overhead, it is slightly faster than calling
    "create".

  reseed
      $ug->reseed;

    Reseeds the internal pseudo-random number generator. This happens
    automatically after a fork or thread creation (assuming
    Scalar::Util::weaken), but may be called manually if desired for some
    reason.

    Any arguments provided are passed to Math::Random::MT::Auto::srand() for
    custom seeding.

      $ug->reseed('hotbits' => 250, '/dev/random');

UUID STRING REPRESENTATIONS
    A UUID contains 16 bytes. A hex string representation looks like
    0xb0470602a64b11da863293ebf1c0e05a. A "standard" representation looks
    like "b0470602-a64b-11da-8632-93ebf1c0e05a". Sometimes these are seen in
    upper case and on Windows the standard format is often seen wrapped in
    parentheses.

    Converting back and forth is easy with "pack" and "unpack".

      # string to 16 bytes
      $string =~ s/^0x//i;            # remove leading "0x"
      $string =~ tr/()-//d;           # strip '-' and parentheses
      $binary = pack("H*", $string);

      # 16 bytes to uppercase string formats
      $hex = "0x" . uc unpack("H*", $binary);
      $std = uc join "-", unpack("H8H4H4H4H12", $binary);

    If you need a module that provides these conversions for you, consider
    UUID::Tiny.

COMPARISON TO OTHER UUID MODULES
    At the time of writing, there are five other general purpose UUID
    generators on CPAN that I consider potential alternatives.
    Data::UUID::MT is included in the discussion below for comparison.

    *   Data::GUID - version 1 UUIDs (wrapper around Data::UUID)

    *   Data::UUID - version 1 or 3 UUIDs (derived from RFC 4122 code)

    *   Data::UUID::LibUUID - version 1 or 4 UUIDs (libuuid)

    *   UUID - version 1 or 4 UUIDs (libuuid)

    *   UUID::Tiny - versions 1, 3, 4, or 5 (pure perl)

    *   Data::UUID::MT - version 1 or 4 (or custom sequential "4s")

    "libuuid" based UUIDs may generally be either version 4 (preferred) or
    version 1 (fallback), depending on the availability of a good random bit
    source (e.g. /dev/random). "libuuid" version 1 UUIDs could also be
    provided by the "uuidd" daemon if available.

    UUID.pm leaves the choice of version up to "libuuid".
    Data::UUID::LibUUID does so by default, but also allows specifying a
    specific version. Note that Data::UUID::LibUUID incorrectly refers to
    version 1 UUIDs as version 2 UUIDs. For example, to get a version 1
    binary UUID explicitly, you would call
    Data::UUID::LibUUID::new_uuid_binary(2).

    In addition to differences mentioned below, there are additional slight
    difference in how the modules (or "libuuid") treat the "clock sequence"
    field and otherwise attempt to keep state between calls, but this is
    generally immaterial.

  Use of Ethernet MAC addresses
    Version 1 UUID generators differ in whether they include the Ethernet
    MAC address as a "node identifier" as specified in RFC 4122. Including
    the MAC has security implications as Version 1 UUIDs can then be traced
    to a particular machine at a particular time.

    For "libuuid" based modules, Version 1 UUIDs will include the actual MAC
    address, if available, or will substitute a random MAC (with multicast
    bit set).

    Data::UUID version 1 UUIDs do not contain the MAC address, but replace
    it with an MD5 hash of data including the hostname and host id (possibly
    just the IP address), modified with the multicast bit.

    Both UUID::Tiny and Data::UUID::MT version 1 UUIDs do not contain the
    actual MAC address, but replace it with a random multicast MAC address.

  Source of random bits
    All the modules differ in the source of random bits.

    "libuuid" based modules get random bits from "/dev/random" or
    "/dev/urandom" or fall back to a pseudo-random number generator.

    Data::UUID only uses random data to see the clock sequence and gets bits
    from the C "rand()" function.

    UUID::Tiny uses Perl's "rand()" function.

    Data::UUID::MT gets random bits from Math::Random::MT::Auto, which uses
    the Mersenne Twister algorithm. Math::Random::MT::Auto seeds from system
    sources (including Win32 specific ones on that platform) if available
    and falls back to other less ideal sources if not.

  Fork and thread safety
    Pseudo-random number generators used in generating UUIDs should be
    reseeded if the process forks or if threads are created.

    Data::UUID::MT checks if the process ID has changed before generating a
    UUID and reseeds if necessary. If Scalar::Util is installed and provides
    "weaken()", Data::UUID::MT will also reseed its objects on thread
    creation.

    Data::UUID::LibUUID will reseed on fork on Mac OSX.

    I have not explored further whether other UUID generators are
    fork/thread safe.

  Benchmarks
    The examples/bench.pl program included with this module does some simple
    benchmarking of UUID generation speeds. Here is the output from my
    desktop system (AMD Phenom II X6 1045T CPU). Note that "v?" is used
    where the choice is left to "libuuid" -- which will result in version 4
    UUIDs on my system.

     Benchmark on Perl v5.14.0 for x86_64-linux with 8 byte integers.

     Key:
       U     => UUID 0.02
       UT    => UUID::Tiny 1.03
       DG    => Data::GUID 0.046
       DU    => Data::UUID 1.217
       DULU  => Data::UUID::LibUUID 0.05
       DUMT  => Data::UUID::MT 0.001

     Benchmarks are marked as to which UUID version is generated.
     Some modules offer method ('meth') and function ('func') interfaces.

             UT|v1    85229/s
             UT|v4   110652/s
           DULU|v1   177495/s
           DULU|v?   178629/s
     DUMT|v4s|meth   274905/s
      DUMT|v1|meth   281942/s
              U|v?   288136/s
           DULU|v4   295107/s
     DUMT|v4s|func   307575/s
      DUMT|v1|func   313538/s
        DG|v1|func   335333/s
        DG|v1|meth   373515/s
      DUMT|v4|meth   450845/s
      DUMT|v4|func   588573/s
             DU|v1  1312946/s

SEE ALSO
    *   RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
        <http://www.apps.ietf.org/rfc/rfc4122.html>

SUPPORT
  Bugs / Feature Requests
    Please report any bugs or feature requests through the issue tracker at
    <https://github.com/dagolden/data-uuid-mt/issues>. You will be notified
    automatically of any progress on your issue.

  Source Code
    This is open source software. The code repository is available for
    public review and contribution under the terms of the license.

    <https://github.com/dagolden/data-uuid-mt>

      git clone git://github.com/dagolden/data-uuid-mt.git

AUTHOR
    David Golden <dagolden@cpan.org>

CONTRIBUTOR
    Matt Koscica <matt.koscica@gmail.com>

COPYRIGHT AND LICENSE
    This software is Copyright (c) 2011 by David Golden.

    This is free software, licensed under:

      The Apache License, Version 2.0, January 2004

