NAME

UUID::Generator::PurePerl - Universally Unique IDentifier (UUID) Generator

SYNOPSIS

  use UUID::Generator::PurePerl;
  
  $ug = UUID::Generator::PurePerl->new();
  
  $uuid1 = $ug->generate_v1();
  print $uuid1->as_string();          #=>

DESCRIPTION

UUID::Generator::PurePerl is UUID (Universally Unique IDentifier; described in RFC 4122) generator class.

METHODS

Following methods generate a UUID as an instance of UUID::Object. For information about retrieving some representation (such as string, Base64 string, etc) from generated UUID, please refer to <UUID::Object> document.

$uuidgen->generate_v1()

This method generates a version 1 UUID.

Version 1 UUID is constructed from machine dependent information (such as MAC address bound with network interface) and high resolution time-stamp, so in most cases generated UUIDs are guaranteed to be unique over world.

But for the same reason, this sort of UUIDs are not suitable for security-aware software.

$uuidgen->generate_v1mc()

This method generates a version 1 UUID, where node address is multicast MAC address created randomly.

$uuidgen->generate_v3($namespace, $name)

This method generates a version 3 UUID.

Version 3 UUID is for unique id of any names belonging to some sort of namespace. Generator calculates digest of that namespace and that name, and uses it as source of UUID.

In version 3, MD5 mechanism is used as digest function.

Module for calculating MD5 digest (such as Digest::MD5) is required to use this method, but in modern version perl, those modules are included as core module.

$uuidgen->generate_v4()

This method generates a version 4 UUID.

Version 4 UUID is constructed from random numbers. UUIDs have variant and version field with fixed values, so not whole entity (128-bit) is scattered randomly, only 122 bits are from random numbers.

$uuidgen->generate_v5($namespace, $name)

This method generates a version 5 UUID.

Algorithm for creating version 5 UUID is quite similar to one of version 3. The difference is, SHA-1 is used for digest of name on version 5 UUID, whereas MD5 is used on version 3.

Module for calculating SHA-1 digest (such as Digest::SHA) is required to use this method.

CONSTANTS

Namespace UUIDs are not defined in this package. Use UUID::Object instead.

NOTICE

In RFC 4122, a principle for creating a time-based UUID (version1 UUID) is described as follows.

Obtain a system-wide global lock

From a system-wide shared stable store, read the UUID generator state (such as time-stamp, clock sequence, and node ID).

Retrieve current time-stamp and node ID

Generate a UUID

Save the state back to the stable storage.

Release the global lock

But in this package, system-wide global locking and persistent storage are not used. This class only acts on a small world around a process, so same UUIDs will be generated on some conditions over processes, over time. This nature of uniqueness might not be suitable for your application.

In addition, node ID is a not real physical hardware address in current implementation. In return, pseudo node ID is calculated from system information. I have a plan to make real node ID retrieval functionality, but not yet.

AUTHOR

ITO Nobuaki <banb@cpan.org>

LICENSE

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

SEE ALSO

UUID::Object, UUID::Generator::PurePerl::Compat.

RFC 4122: "A Universally Unique IDentifier (UUID) URN Namespace", 2005, http://www.ietf.org/rfc/rfc4122.txt.

cpanm UUID::Generator::PurePerl

perl -MCPAN -e shell
install UUID::Generator::PurePerl