NAME
    Acme::CPANModules::UUID - Modules that can generate immutable
    universally unique identifier (UUIDs)

VERSION
    This document describes version 0.003 of Acme::CPANModules::UUID (from
    Perl distribution Acme-CPANModules-UUID), released on 2021-01-17.

SYNOPSIS
    To run benchmark with default option:

     % bencher --cpanmodules-module UUID

    To run module startup overhead benchmark:

     % bencher --module-startup --cpanmodules-module UUID

    For more options (dump scenario, list/include/exclude/add participants,
    list/include/exclude/add datasets, etc), see bencher or run "bencher
    --help".

DESCRIPTION
    UUIDs are 128-bit numbers that can be used as permanent IDs or keys in
    databases. There are 5 "versions" of UUID, each might be more suitable
    than others in specific cases. Version 1 (v1) UUIDs are generated from a
    time and a node ID (usually the MAC address); version 2 (v2) UUIDs from
    an identifier (group/user ID), a time, and a node ID; version 4 (v4)
    UUIDs from a random/pseudo-random number; version 3 (v3) UUIDs from
    hashing a namespace using MD5; version 5 (v5) from hashing a namespace
    using SHA-1.

    Data::UUID should be your first choice, and when you cannot install XS
    modules you can use UUID::Tiny instead.

BENCHMARKED MODULES
    Version numbers shown below are the versions used when running the
    sample benchmark.

    Data::UUID 1.224

    UUID::Tiny 1.04

    UUID::Random 0.04

    UUID::Random::PERLANCAR 0.001

    UUID::Random::Secure 0.001

BENCHMARK PARTICIPANTS
    *   Data::UUID (perl_code)

        Code template:

         my $u = Data::UUID->new; $u->create for 1..1000; $u->create

    *   UUID::Tiny (perl_code)

        Code template:

         UUID::Tiny::create_uuid() for 1..1000; UUID::Tiny::create_uuid()

    *   UUID::Random (perl_code)

        Code template:

         UUID::Random::generate() for 1..1000; ; UUID::Random::generate()

    *   UUID::Random::PERLANCAR (perl_code)

        Code template:

         UUID::Random::PERLANCAR::generate() for 1..1000; UUID::Random::PERLANCAR::generate()

    *   UUID::Random::Secure (perl_code)

        Code template:

         UUID::Random::Secure::generate() for 1..1000; UUID::Random::Secure::generate()

SAMPLE BENCHMARK RESULTS
    Run on: perl: *v5.30.0*, CPU: *Intel(R) Core(TM) i5-7200U CPU @ 2.50GHz
    (2 cores)*, OS: *GNU/Linux Ubuntu version 19.10*, OS kernel: *Linux
    version 5.3.0-64-generic*.

    Benchmark with default options ("bencher --cpanmodules-module UUID"):

     #table1#
     +-------------------------+-----------+-----------+-----------------------+-----------------------+---------+---------+
     | participant             | rate (/s) | time (ms) | pct_faster_vs_slowest | pct_slower_vs_fastest |  errors | samples |
     +-------------------------+-----------+-----------+-----------------------+-----------------------+---------+---------+
     | UUID::Random::Secure    |      50.3 |    19.9   |                 0.00% |              4001.27% | 1.2e-05 |      20 |
     | UUID::Random            |     128   |     7.81  |               154.35% |              1512.46% | 2.2e-06 |      20 |
     | UUID::Tiny              |     156   |     6.41  |               209.92% |              1223.32% | 3.8e-06 |      20 |
     | UUID::Random::PERLANCAR |    1460   |     0.684 |              2807.25% |                41.07% | 4.8e-07 |      20 |
     | Data::UUID              |    2100   |     0.48  |              4001.27% |                 0.00% | 1.6e-06 |      20 |
     +-------------------------+-----------+-----------+-----------------------+-----------------------+---------+---------+

    Benchmark module startup overhead ("bencher --cpanmodules-module UUID
    --module-startup"):

     #table2#
     +-------------------------+-----------+-------------------+-----------------------+-----------------------+---------+---------+
     | participant             | time (ms) | mod_overhead_time | pct_faster_vs_slowest | pct_slower_vs_fastest |  errors | samples |
     +-------------------------+-----------+-------------------+-----------------------+-----------------------+---------+---------+
     | UUID::Random::Secure    |      83.8 |              77   |                 0.00% |              1133.87% | 6.6e-05 |      20 |
     | UUID::Tiny              |      23   |              16.2 |               256.63% |               245.98% | 4.5e-05 |      22 |
     | Data::UUID              |      15   |               8.2 |               474.59% |               114.74% | 4.9e-05 |      20 |
     | UUID::Random            |       8.6 |               1.8 |               876.45% |                26.36% | 8.7e-06 |      20 |
     | UUID::Random::PERLANCAR |       8.5 |               1.7 |               884.63% |                25.31% | 1.7e-05 |      20 |
     | perl -e1 (baseline)     |       6.8 |               0   |              1133.87% |                 0.00% | 3.8e-05 |      21 |
     +-------------------------+-----------+-------------------+-----------------------+-----------------------+---------+---------+

    To display as an interactive HTML table on a browser, you can add option
    "--format html+datatables".

ACME::CPANMODULES FEATURE COMPARISON MATRIX
     +-------------------------+-----------+-----------+-----------+-----------+-----------+-------+-------+----------------------+
     | module                  | create_v1 | create_v2 | create_v3 | create_v4 | create_v5 | is_pp | is_xs | v4_secure_random *1) |
     +-------------------------+-----------+-----------+-----------+-----------+-----------+-------+-------+----------------------+
     | Data::UUID              | yes       | yes       | no        | no        | no        | no    | yes   | N/A                  |
     | UUID::Tiny              | yes       | no        | yes       | yes       | yes       | yes   | no    | no                   |
     | UUID::Random            | no        | no        | no        | yes       | no        | yes   | no    | no                   |
     | UUID::Random::PERLANCAR | no        | no        | no        | yes       | no        | yes   | no    | no                   |
     | UUID::Random::Secure    | no        | no        | no        | yes       | no        | yes   | no    | yes                  |
     +-------------------------+-----------+-----------+-----------+-----------+-----------+-------+-------+----------------------+

    Notes:

    1. v4_secure_random: Whether the module uses cryptographically secure
    pseudo-random number generator for v4 UUIDs

ACME::MODULES ENTRIES
    *   Data::UUID

        This module creates v1 and v2 UUIDs. Depending on the OS, for MAC
        address, it usually uses a hash of hostname instead. This module is
        XS, so performance is good. If you cannot use an XS module, try
        UUID::Tiny instead.

        The benchmark code creates 1000+1 v1 string UUIDs.

    *   UUID::Tiny

        This module should be your go-to choice if you cannot use an XS
        module.

        To create a cryptographically secure random (v4) UUIDs, use
        UUID::Tiny::Patch::UseMRS.

        The benchmark code creates 1000+1 v1 string UUIDs.

        See also: Types::UUID which is a type library that uses Data::UUID
        as the backend.

    *   UUID::Random

        This module simply uses 32 calls to Perl's "rand()" to construct
        each random hexadecimal digits of the UUID (v4). Not really
        recommended, since perl's default pseudo-random generator is neither
        cryptographically secure nor has 128 bit of entropy.

        To create a cryptographically secure random UUIDs, use
        UUID::Random::Secure or UUID::Random::Patch::UseMRS.

        The benchmark code creates 1000+1 v4 string UUIDs.

    *   UUID::Random::PERLANCAR

        Just another implementation of UUID::Random.

        The benchmark code creates 1000+1 v4 string UUIDs.

    *   UUID::Random::Secure

        Just like UUID::Random, except it uses Math::Random::Secure's
        "irand()" to produce random numbers.

        The benchmark code creates 1000+1 v4 string UUIDs.

FAQ
  What is an Acme::CPANModules::* module?
    An Acme::CPANModules::* module, like this module, contains just a list
    of module names that share a common characteristics. It is a way to
    categorize modules and document CPAN. See Acme::CPANModules for more
    details.

  What are ways to use this Acme::CPANModules module?
    Aside from reading this Acme::CPANModules module's POD documentation,
    you can install all the listed modules (entries) using cpanmodules CLI
    (from App::cpanmodules distribution):

        % cpanmodules ls-entries UUID | cpanm -n

    or Acme::CM::Get:

        % perl -MAcme::CM::Get=UUID -E'say $_->{module} for @{ $LIST->{entries} }' | cpanm -n

    or directly:

        % perl -MAcme::CPANModules::UUID -E'say $_->{module} for @{ $Acme::CPANModules::UUID::LIST->{entries} }' | cpanm -n

    This Acme::CPANModules module contains benchmark instructions. You can
    run a benchmark for some/all the modules listed in this
    Acme::CPANModules module using the bencher CLI (from Bencher
    distribution):

        % bencher --cpanmodules-module UUID

    This Acme::CPANModules module also helps lcpan produce a more meaningful
    result for "lcpan related-mods" command when it comes to finding related
    modules for the modules listed in this Acme::CPANModules module.

HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/Acme-CPANModules-UUID>.

SOURCE
    Source repository is at
    <https://github.com/perlancar/perl-Acme-CPANModules-UUID>.

BUGS
    Please report any bugs or feature requests on the bugtracker website
    <https://github.com/perlancar/perl-Acme-CPANModules-UUID/issues>

    When submitting a bug or request, please include a test-file or a patch
    to an existing test-file that illustrates the bug or desired feature.

SEE ALSO
    Acme::CPANModules - about the Acme::CPANModules namespace

    cpanmodules - CLI tool to let you browse/view the lists

AUTHOR
    perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2021, 2020 by perlancar@cpan.org.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.