UUID Generator

Generates universally unique identifiers (UUIDs) for use in distributed applications. Based on RFC 4122.

Generating UUIDs

Call #generate to generate a new UUID. The method returns a string in one of three formats. The default format is 36 characters long, and contains the 32 hexadecimal octets and hyphens separating the various value parts. The :compact format omits the hyphens, while the :urn format adds the :urn:uuid prefix.

For example:

  uuid = UUID.new
  10.times do
    p uuid.generate
  end

UUIDs in Brief

UUID (universally unique identifier) are guaranteed to be unique across time and space.

A UUID is 128 bit long, and consists of a 60-bit time value, a 16-bit sequence number and a 48-bit node identifier.

The time value is taken from the system clock, and is monotonically incrementing. However, since it is possible to set the system clock backward, a sequence number is added. The sequence number is incremented each time the UUID generator is started. The combination guarantees that identifiers created on the same machine are unique with a high degree of probability.

Note that due to the structure of the UUID and the use of sequence number, there is no guarantee that UUID values themselves are monotonically incrementing. The UUID value cannot itself be used to sort based on order of creation.

To guarantee that UUIDs are unique across all machines in the network, the IEEE 802 MAC address of the machine’s network interface card is used as the node identifier.

For more information see RFC 4122.

UUID State File

The UUID generator uses a state file to hold the MAC address and sequence number.

The MAC address is used to generate identifiers that are unique to your machine, preventing conflicts in distributed applications. The MAC address is six bytes (48 bit) long. It is automatically extracted from one of the network cards on your machine.

The sequence number is incremented each time the UUID generator is first used by the application, to prevent multiple processes from generating the same set of identifiers, and deal with changes to the system clock.

The UUID state file is created in /var/tmp/ruby-uuid or the Windows common application data directory using mode 0644. If that directory is not writable, the file is created as .ruby-uuid in the home directory. If you need to create the file with a different mode, use UUID#state_file before running the UUID generator.

State files are not portable across machines.

Latest and Greatest

Stable release are made through RubyForge, to upgrade simply:

  gem upgrade uuid

You can subscribe for notifications of new releases through the reliable-msg project page at rubyforge.org/projects/reliable-msg

Source code and documentation hosted on Github: github.com/assaf/uuid

To get UUID from source:

  git clone git://github.com/assaf/uuid.git

License

This package is licensed under the MIT license and/or the Creative Commons Attribution-ShareAlike.

:include: MIT-LICENSE