.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Data::UUID::MT 3pm" .TH Data::UUID::MT 3pm "2023-02-08" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Data::UUID::MT \- Fast random UUID generator using the Mersenne Twister algorithm .SH "VERSION" .IX Header "VERSION" version 1.001 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& 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\->(); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This \s-1UUID\s0 generator uses the excellent Math::Random::MT::Auto module as a source of fast, high-quality (pseudo) random numbers. .PP Three different types of UUIDs are supported. Two are consistent with \&\s-1RFC 4122\s0 and one is a custom variant that provides a 'sequential \s-1UUID\s0' that can be advantageous when used as a primary database key. .PP \&\fBNote\fR: 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. .SS "Version 1 UUIDs" .IX Subsection "Version 1 UUIDs" The \s-1UUID\s0 generally follows the \*(L"version 1\*(R" spec from the \s-1RFC,\s0 however the clock sequence and \s-1MAC\s0 address are randomly generated each time. (This is permissible within the spec of the \s-1RFC.\s0) The generated \s-1MAC\s0 address has the the multicast bit set as mandated by the \s-1RFC\s0 to ensure it does not conflict with real \s-1MAC\s0 addresses. This \s-1UUID\s0 has 60 bits of timestamp data, 61 bits of pseudo-random data and 7 mandated bits (multicast bit, \*(L"variant\*(R" field and \*(L"version\*(R" field). .SS "Version 4 UUIDs" .IX Subsection "Version 4 UUIDs" The \s-1UUID\s0 follows the \*(L"version 4\*(R" spec, with 122 pseudo-random bits and 6 mandated bits (\*(L"variant\*(R" field and \*(L"version\*(R" field). .SS "Version 4s UUIDs" .IX Subsection "Version 4s UUIDs" This is a custom \s-1UUID\s0 form that resembles \*(L"version 4\*(R" form, but that overlays the first 60 bits with a timestamp akin to \*(L"version 1\*(R", Unlike \*(L"version 1\*(R", this custom version preserves the ordering of bits from high to low, whereas \&\*(L"version 1\*(R" puts the low 32 bits of the timestamp first, then the middle 16 bits, then multiplexes the high bits with version field. This \*(L"4s\*(R" variant provides a \*(L"sequential \s-1UUID\*(R"\s0 with the timestamp providing order and the remaining random bits making collision with other UUIDs created at the exact same microsecond highly unlikely. This \s-1UUID\s0 has 60 timestamp bits, 62 pseudo-random bits and 6 mandated bits (\*(L"variant\*(R" field and \*(L"version\*(R" field). .SS "Unsupported: Versions 2, 3 and 5" .IX Subsection "Unsupported: Versions 2, 3 and 5" This module focuses on generation of UUIDs with random elements and does not support \s-1UUID\s0 versions 2, 3 and 5. .SH "METHODS" .IX Header "METHODS" .SS "new" .IX Subsection "new" .Vb 1 \& my $ug = Data::UUID::MT\->new( version => 4 ); .Ve .PP Creates a \s-1UUID\s0 generator object. The only allowed versions are \&\*(L"1\*(R", \*(L"4\*(R" and \*(L"4s\*(R". If no version is specified, it defaults to \*(L"4\*(R". .SS "create" .IX Subsection "create" .Vb 1 \& my $uuid = $ug\->create; .Ve .PP Returns a \s-1UUID\s0 packed into a 16 byte string. .SS "create_hex" .IX Subsection "create_hex" .Vb 1 \& my $uuid = $ug\->create_hex(); .Ve .PP Returns a \s-1UUID\s0 as a lowercase hex string, prefixed with \*(L"0x\*(R", e.g. \&\f(CW0xb0470602a64b11da863293ebf1c0e05a\fR .SS "create_string" .IX Subsection "create_string" .Vb 1 \& my $uuid = $ug\->create_string(); # .Ve .PP Returns \s-1UUID\s0 as a lowercase string in \*(L"standard\*(R" format, e.g. \&\f(CW\*(C`b0470602\-a64b\-11da\-8632\-93ebf1c0e05a\*(C'\fR .SS "iterator" .IX Subsection "iterator" .Vb 2 \& my $next = $ug\->iterator; \& my $uuid = $next\->(); .Ve .PP Returns a reference to the internal \s-1UUID\s0 generator function. Because this avoids method call overhead, it is slightly faster than calling \f(CW\*(C`create\*(C'\fR. .SS "reseed" .IX Subsection "reseed" .Vb 1 \& $ug\->reseed; .Ve .PP 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. .PP Any arguments provided are passed to \fBMath::Random::MT::Auto::srand()\fR for custom seeding. .PP .Vb 1 \& $ug\->reseed(\*(Aqhotbits\*(Aq => 250, \*(Aq/dev/random\*(Aq); .Ve .SH "UUID STRING REPRESENTATIONS" .IX Header "UUID STRING REPRESENTATIONS" A \s-1UUID\s0 contains 16 bytes. A hex string representation looks like \&\f(CW0xb0470602a64b11da863293ebf1c0e05a\fR. A \*(L"standard\*(R" representation looks like \f(CW\*(C`b0470602\-a64b\-11da\-8632\-93ebf1c0e05a\*(C'\fR. Sometimes these are seen in upper case and on Windows the standard format is often seen wrapped in parentheses. .PP Converting back and forth is easy with \f(CW\*(C`pack\*(C'\fR and \f(CW\*(C`unpack\*(C'\fR. .PP .Vb 4 \& # string to 16 bytes \& $string =~ s/^0x//i; # remove leading "0x" \& $string =~ tr/()\-//d; # strip \*(Aq\-\*(Aq and parentheses \& $binary = pack("H*", $string); \& \& # 16 bytes to uppercase string formats \& $hex = "0x" . uc unpack("H*", $binary); \& $std = uc join "\-", unpack("H8H4H4H4H12", $binary); .Ve .PP If you need a module that provides these conversions for you, consider UUID::Tiny. .SH "COMPARISON TO OTHER UUID MODULES" .IX Header "COMPARISON TO OTHER UUID MODULES" At the time of writing, there are five other general purpose \s-1UUID\s0 generators on \&\s-1CPAN\s0 that I consider potential alternatives. Data::UUID::MT is included in the discussion below for comparison. .IP "\(bu" 4 Data::GUID \- version 1 UUIDs (wrapper around Data::UUID) .IP "\(bu" 4 Data::UUID \- version 1 or 3 UUIDs (derived from \s-1RFC 4122\s0 code) .IP "\(bu" 4 Data::UUID::LibUUID \- version 1 or 4 UUIDs (libuuid) .IP "\(bu" 4 \&\s-1UUID\s0 \- version 1 or 4 UUIDs (libuuid) .IP "\(bu" 4 UUID::Tiny \- versions 1, 3, 4, or 5 (pure perl) .IP "\(bu" 4 Data::UUID::MT \- version 1 or 4 (or custom sequential \*(L"4s\*(R") .PP \&\f(CW\*(C`libuuid\*(C'\fR 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). \f(CW\*(C`libuuid\*(C'\fR version 1 UUIDs could also be provided by the \&\f(CW\*(C`uuidd\*(C'\fR daemon if available. .PP \&\s-1UUID\s0.pm leaves the choice of version up to \f(CW\*(C`libuuid\*(C'\fR. 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 \s-1UUID\s0 explicitly, you would call \&\f(CWData::UUID::LibUUID::new_uuid_binary(2)\fR. .PP In addition to differences mentioned below, there are additional slight difference in how the modules (or \f(CW\*(C`libuuid\*(C'\fR) treat the \*(L"clock sequence\*(R" field and otherwise attempt to keep state between calls, but this is generally immaterial. .SS "Use of Ethernet \s-1MAC\s0 addresses" .IX Subsection "Use of Ethernet MAC addresses" Version 1 \s-1UUID\s0 generators differ in whether they include the Ethernet \s-1MAC\s0 address as a \*(L"node identifier\*(R" as specified in \s-1RFC 4122.\s0 Including the \s-1MAC\s0 has security implications as Version 1 UUIDs can then be traced to a particular machine at a particular time. .PP For \f(CW\*(C`libuuid\*(C'\fR based modules, Version 1 UUIDs will include the actual \s-1MAC\s0 address, if available, or will substitute a random \s-1MAC\s0 (with multicast bit set). .PP Data::UUID version 1 UUIDs do not contain the \s-1MAC\s0 address, but replace it with an \s-1MD5\s0 hash of data including the hostname and host id (possibly just the \s-1IP\s0 address), modified with the multicast bit. .PP Both UUID::Tiny and Data::UUID::MT version 1 UUIDs do not contain the actual \&\s-1MAC\s0 address, but replace it with a random multicast \s-1MAC\s0 address. .SS "Source of random bits" .IX Subsection "Source of random bits" All the modules differ in the source of random bits. .PP \&\f(CW\*(C`libuuid\*(C'\fR based modules get random bits from \f(CW\*(C`/dev/random\*(C'\fR or \f(CW\*(C`/dev/urandom\*(C'\fR or fall back to a pseudo-random number generator. .PP Data::UUID only uses random data to see the clock sequence and gets bits from the C \f(CW\*(C`rand()\*(C'\fR function. .PP UUID::Tiny uses Perl's \f(CW\*(C`rand()\*(C'\fR function. .PP 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. .SS "Fork and thread safety" .IX Subsection "Fork and thread safety" Pseudo-random number generators used in generating UUIDs should be reseeded if the process forks or if threads are created. .PP Data::UUID::MT checks if the process \s-1ID\s0 has changed before generating a \s-1UUID\s0 and reseeds if necessary. If Scalar::Util is installed and provides \&\f(CW\*(C`weaken()\*(C'\fR, Data::UUID::MT will also reseed its objects on thread creation. .PP Data::UUID::LibUUID will reseed on fork on Mac \s-1OSX.\s0 .PP I have not explored further whether other \s-1UUID\s0 generators are fork/thread safe. .SS "Benchmarks" .IX Subsection "Benchmarks" The \fIexamples/bench.pl\fR program included with this module does some simple benchmarking of \s-1UUID\s0 generation speeds. Here is the output from my desktop system (\s-1AMD\s0 Phenom \s-1II X6 1045T CPU\s0). Note that \*(L"v?\*(R" is used where the choice is left to \f(CW\*(C`libuuid\*(C'\fR \*(-- which will result in version 4 UUIDs on my system. .PP .Vb 1 \& 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 (\*(Aqmeth\*(Aq) and function (\*(Aqfunc\*(Aq) 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 .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\(bu" 4 \&\s-1RFC 4122 A\s0 Universally Unique IDentifier (\s-1UUID\s0) \s-1URN\s0 Namespace .SH "SUPPORT" .IX Header "SUPPORT" .SS "Bugs / Feature Requests" .IX Subsection "Bugs / Feature Requests" Please report any bugs or feature requests through the issue tracker at . You will be notified automatically of any progress on your issue. .SS "Source Code" .IX Subsection "Source Code" This is open source software. The code repository is available for public review and contribution under the terms of the license. .PP .PP .Vb 1 \& git clone git://github.com/dagolden/data\-uuid\-mt.git .Ve .SH "AUTHOR" .IX Header "AUTHOR" David Golden .SH "CONTRIBUTOR" .IX Header "CONTRIBUTOR" Matt Koscica .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is Copyright (c) 2011 by David Golden. .PP This is free software, licensed under: .PP .Vb 1 \& The Apache License, Version 2.0, January 2004 .Ve