assaf / uuid

Generates universally unique identifiers (UUIDs) for use in distributed applications.

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 #Dir.tmpdir/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.

Note: If you are running on a shared host where the state file is not shared between processes, or persisted across restarts (e.g. Heroku, Google App Engine) you can simple turn it off:

UUID.state_file = false

State files are not portable across machines.

If you do not use the state file, UUID generation will attempt to use your server’s MAC address using the macaddr gem, which runs system commands to identify the MAC address and then cache it. Since this can take a few seconds on some operating systems, when using UUID.state_file = false, you should add the following line after disabling the state file:

UUID.generator.next_sequence

Note: when using a forking server (Unicorn, Resque, Pipemaster, etc) you don’t want your forked processes using the same sequence number. Make sure to increment the sequence number each time a worker forks.

For example, in config/unicorn.rb:

after_fork do |server, worker|
  UUID.generator.next_sequence
end

Command Line¶ ↑

You can run uuid from the command line, generating new UUID to stdout:

$ uuid

Multiple UUIDs in a sequence, separated with a newline:

$ uuid --count 10

You can also run client and server from the command line

$ uuid --server &
$ uuid --socket /var/lib/uuid.sock

Latest and Greatest¶ ↑

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

uuid's Issues

nil.unpack Issue on Windows

Getting, You have a nil object when you didn't expect it! The error occurred while evaluating nil.unpack
issue when trying UUID.new. The same thing was working fine earlier, but i tried opening same application on two ports after that im getting this issue, please help us in fixing the issue.

Multi-process access issue?

I'm digging into the locking code, but it seems there may be a problem using UUID from multiple processes on the same machine. We're using resque-status, which uses UUID under the covers to give each job an ID. Since we've started allowing jobs to reschedule themselves, and thus have UUID called from multiple processes, we've been seeing exceptions like the following:

NoMethodError: undefined method `unpack' for nil:NilClass
/usr/local/lib/ruby/gems/1.8/gems/uuid-2.2.0/lib/uuid.rb:300
/usr/local/lib/ruby/gems/1.8/gems/uuid-2.2.0/lib/uuid.rb:256
/usr/local/lib/ruby/gems/1.8/gems/uuid-2.2.0/lib/uuid.rb:290
/usr/local/lib/ruby/gems/1.8/gems/uuid-2.2.0/lib/uuid.rb:287
/usr/local/lib/ruby/gems/1.8/gems/uuid-2.2.0/lib/uuid.rb:287
/usr/local/lib/ruby/gems/1.8/gems/uuid-2.2.0/lib/uuid.rb:255
/usr/local/lib/ruby/gems/1.8/gems/uuid-2.2.0/lib/uuid.rb:189
/usr/local/lib/ruby/gems/1.8/gems/uuid-2.2.0/lib/uuid.rb:121
/usr/local/lib/ruby/gems/1.8/gems/uuid-2.2.0/lib/uuid.rb:121
/usr/local/lib/ruby/gems/1.8/gems/resque-status-0.1.3/lib/resque/status.rb:118
/usr/local/lib/ruby/gems/1.8/gems/resque-status-0.1.3/lib/resque/status.rb:17
/usr/local/lib/ruby/gems/1.8/gems/resque-status-0.1.3/lib/resque/job_with_status.rb:75
/usr/local/lib/ruby/gems/1.8/gems/resque-status-0.1.3/lib/resque/job_with_status.rb:69

uuid should not make hardcoded assumptions about temporary directories

Currently the state file is always created in /var/tmp in non-windows platforms. Please use a default that is platform dependent and can be overruled, such as Dir.tmpdir.

"Gemfile not found" when using rbenv

I installed uuid using rbenv. When calling the command line tool, I get:

/Users/mac/.rbenv/versions/2.1.2/lib/ruby/gems/2.1.0/gems/uuid-2.3.7/Gemfile not found

UUID::Client.inspect fails if socket is a UNIXSocket in uuid-2.3.1

u = UUID::Client.new '/tmp/uuid.sock'
u.inspect
ArgumentError: not an AF_INET/AF_INET6 sockaddr
        from /usr/local/lib/ruby/gems/1.9.1/gems/uuid-2.3.1/lib/uuid.rb:432:in `unpack_sockaddr_in'
        from /usr/local/lib/ruby/gems/1.9.1/gems/uuid-2.3.1/lib/uuid.rb:432:in `inspect'
        from (irb):17
        from /usr/local/lib/ruby/gems/1.9.1/gems/railties-3.0.3/lib/rails/commands/console.rb:44:in `start'
        from /usr/local/lib/ruby/gems/1.9.1/gems/railties-3.0.3/lib/rails/commands/console.rb:8:in `start'
        from /usr/local/lib/ruby/gems/1.9.1/gems/railties-3.0.3/lib/rails/commands.rb:23:in `<top (required)>'
        from script/rails:6:in `require'
        from script/rails:6:in `<main>'

uuid-2.3.2/lib/uuid.rb:71: warning: already initialized constant VERSION

uuid 2.3.2 appears to set the global constant 'VERSION', which yields this warning on Ruby 1.9.2 (when another gem also does this):

bundled/ruby/1.9.1/gems/uuid-2.3.2/lib/uuid.rb:71: warning: already initialized constant VERSION

I suspect VERSION (and probably the other constants) need to be prefixed.

Executable name conflict

The generic executable name uuid conflicts with existing softwares, like the widespread OSSP uuid. Maybe should you use another name?

FakeFS interference

This line: https://github.com/assaf/uuid/blob/master/lib/uuid.rb#L66

It causes a pretty bad headache if you're using FakeFS in your project (which stubs File).

Not sure how critical you would consider this, but it does make people do an integration without knowing about it.

Couldn't get 2.0.2 to install, had to go back to 1.0.1

2.0.2 wouldn't install for me (gem install assaf-uuid -s http://gems.github.com) ... something about it couldn't find the /lib directory? I just went down to 2.0.1 and everything worked fine!

use /tmp for state dir

when running under 'sudo -u user' as root, it tries to create state file under /root and fails.

http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=771544

I think it should try to create state file in /tmp

nil due to non-binary read of state file on Windows / Ruby 1.8.6

Changing the open mode from r+ to rb+ fixes the problem:

Updates the state file with a new sequence number.

def next_sequence
if self.class.state_file
open_lock 'rb+' do |io| # <==========
@mac, @sequence, @last_clock = read_state(io)

Windows 7
ruby 1.8.6 (2008-08-11 patchlevel 287) [i386-mswin32]

Add License information to Gemspec

This will make it show up on rubygems.org. I'm doing due diligence on our gems and need to find out the licenses for all the gems. Having it show up on rubygems.org cuts out the step of having to go to the github repo.

/var/tmp/ruby-uuid assumed to be writable

Deploying the app to Heroku, and /var/tmp/ruby-uuid isn't writable because somebody else already is running it on their user account.

uuid checks to see if the /var/tmp directory is writable, but it never does a similar sanity check to ensure the file itself is writable.

nil.unpack issue

I got this error
The error occurred while evaluating nil.unpack
I am using uuid-2.0.2 with rails2.3.4

UUID.generate collisions when called too often

Under JRuby I am calling UUID.generate quite often. I see a case in my logs where two successive calls returns the same UUID. Looking at the code, I see this comment:

    # The clock must be monotonically increasing. The clock resolution is at
    # best 100 ns (UUID spec), but practically may be lower (on my setup,
    # around 1ms). If this method is called too fast, we don't have a
    # monotonically increasing clock, so the solution is to just wait.
    #
    # It is possible for the clock to be adjusted backwards, in which case we
    # would end up blocking for a long time. When backward clock is detected,
    # we prevent duplicates by asking for a new sequence number and continue
    # with the new clock.

Judging by the comment, I assume that it is possible that a backward clock could be detected twice in a row, so asking for a new sequence number in that situation will still generate the same UUID when UUID.state_file=nil. If this assumption is correct, would it be reasonable to randomize the next sequence number?

e.g.

if self.class.state_file
  ....
else
  @sequence += rand(999)
end
...

If that is acceptable, I could provide a patch.

add development dependency on mocha

also mocha >1.0 needs require 'mocha/setup' instead of require 'mocha' (test/test-uuid.rb needs update)

RuntimeError: no mac address candidates

I am running UUID.new and this RuntimeError is being raised.

My environment is a VPS inside a OpenVZ container virtualization server.

Stack Trace:
irb(main):006:0> u = UUID.new
RuntimeError: no mac address candidates
from /var/lib/gems/1.8/gems/macaddr-1.0.0/lib/macaddr.rb:52:in addr' from /var/lib/gems/1.8/gems/uuid-2.3.0/lib/uuid.rb:208:ininitialize'
from (irb):6:in `new'
from (irb):6

Cant Convert Class to String - Jruby Rake

Hey,

I am trying to run the gem in JRUBY and get the following error while its trying to load under Rake..

'''rake aborted!
can't convert Class into String
''''

I can isolate the issue right down to gem by removing it and Rake runs fine. This is under all versions of JRUBY - even upto the recent 1.6.6

Thanks.

How does this compare to SecureRandom.uuid?

The Ruby standard library already has a UUID generator, SecureRandom.uuid. I thought it would be good to mention in the README how does this gem compare to SecureRandom.uuid, and what are the advantages of using this gem.

Add generate method usage to readme

I think there could be an improvement in the readme to provide an example of the generate method including the type, for example :compact

Allocation performance is *terrible* under JRuby when UUID.state_file = false

Chuck-Remess-Mac-Pro:perf cremes$ ruby uuid_bench.rb 
Rehearsal -------------------------------------------------------------------------
class allocation:                      59.914000   0.000000  59.914000 ( 59.914000)
uuid generation:                        0.020000   0.000000   0.020000 (  0.020000)
--------------------------------------------------------------- total: 59.934000sec

                                            user     system      total        real
class allocation:                      59.310000   0.000000  59.310000 ( 59.310000)
uuid generation:                        0.013000   0.000000   0.013000 (  0.013000)
Chuck-Remess-Mac-Pro:perf cremes$ ruby -v
jruby 1.7.0.dev (ruby-1.8.7-p352) (2011-12-19 f404f75) (Java HotSpot(TM) 64-Bit Server VM 1.6.0_29) [darwin-x86_64-java]
Chuck-Remess-Mac-Pro:perf cremes$ rvm system
Chuck-Remess-Mac-Pro:perf cremes$ ruby uuid_bench.rb 
Rehearsal -------------------------------------------------------------------------
class allocation:                       0.003916   0.000361   0.004277 (  0.004240)
uuid generation:                        0.005223   0.000498   0.005721 (  0.005720)
---------------------------------------------------------------- total: 0.009998sec

                                            user     system      total        real
class allocation:                       0.003570   0.000199   0.003769 (  0.003759)
uuid generation:                        0.003729   0.000237   0.003966 (  0.003967)
Chuck-Remess-Mac-Pro:perf cremes$ ruby -v
rubinius 2.0.0dev (1.8.7 964a1a2b yyyy-mm-dd JI) [x86_64-apple-darwin10.8.0]

Generated by code:

# Test the performance of creating UUID instances and generating
# UUID values.
#

require 'rubygems'
require 'benchmark'
require 'uuid'
UUID.state_file = false

class Bar1

  def alloc_it
    UUID.new
  end
end # Bar1

class Bar2
  def initialize
    @uuid = UUID.new
  end

  def alloc_it
    @uuid.generate
  end
end

@bar1 = Bar1.new
@bar2 = Bar2.new

Iterations = 100

Benchmark.bmbm("Compare UUID allocation and generation".size) do |x|
  x.report("class allocation:") do
    Iterations.times { @bar1.alloc_it }
  end

  x.report("uuid generation:") do
    Iterations.times { @bar2.alloc_it }
  end

end

Version of UUID generated

Which UUID version is used by this gem to generate UUIDs?

From my understanding of Variants and versions of UUIDs on Wikipedia, the character M defines the version and should be either set to 1, 2, 3, 4, or 5. However, when I generate a UUID using this gem, the M character appears to be always set to 0. I would have expected it to be set to 1 since the gem README indicates that the MAC address is used as part of generation.

How random / predictable are the results?

Not really an issue, sorry, but I wanted to double check before using this properly for filenames that I'd like to be unpredictable.

/var/tmp/ruby-uuid assumed to be writable

Deploying the app to Heroku, and /var/tmp/ruby-uuid isn't writable because somebody else already is running it on their user account.

uuid checks to see if the /var/tmp directory is writable, but it never does a similar sanity check to ensure the file itself is writable.

Sort method (or cmp) should be implemented for time based UUID's

I'd like to have a sort method that takes UUID's generated with uuidgen -t, and sorts them in order of generation. If two happen to be generated at exactly the same time, then they should be compared based on the remaining, non-time based data.

Thanks!

Unique and random uuid

When generate uuid, the result are very similar, not random, I understand they are unique. But is it possible to generate a new uuid that different in each range(split by -) each time?

irb(main):004:0> uuid.generate
=> "1c534e40-ebf3-0132-224b-20c9d088be77"
irb(main):005:0> uuid.generate
=> "1ce35a30-ebf3-0132-224b-20c9d088be77"

Gemfile not found

When I run gem install uuid; uuid it returns:

.../gems/uuid-2.3.4/Gemfile not found

I manually add the Gemfile and I get:

.../bin/uuid:19: stack level too deep (SystemStackError)

uuid is not multi-user aware

Using /var/tmp/ruby-uuid is unwise on a multi-user system. If /var/tmp is writable but /var/tmp/ruby-uuid is not (due to it being owned by another user who happens to have generated a UUID), UUID.new fails with an EACCESS error on /var/tmp/ruby-uuid.

Errno::EACCES: Permission denied - /root/.ruby-uuid

When trying to:

self.edit_token = UUID.generate(:compact)

trace:

/gems/uuid-2.3.7/lib/uuid.rb:270 in "initialize"
/gems/uuid-2.3.7/lib/uuid.rb:270 in "open"
/gems/uuid-2.3.7/lib/uuid.rb:270 in "initialize"
/gems/uuid-2.3.7/lib/uuid.rb:127 in "new"
/gems/uuid-2.3.7/lib/uuid.rb:127 in "generate"
/app/models/product.rb:46 in "block in <class:Product>"

application is ran by root user with unicorn+nginx, deployed with capistrano.
from rails console its working normally on same server

You checked in the bundler binstub of bin/uuid

bin/uuid is bundler binstub and cannot be executed.

$ uuid
/home/hal/.gem/ruby/1.9.3/gems/bundler-1.3.5/lib/bundler/rubygems_integration.rb:280:in `block in replace_bin_path': can't find executable uuid (Gem::Exception)
    from /home/hal/.gem/ruby/1.9.3/gems/uuid-2.3.7/bin/uuid:16:in `'
    from /home/hal/.gem/ruby/1.9.3/bin/uuid:19:in `load'
    from /home/hal/.gem/ruby/1.9.3/bin/uuid:19:in `'

Version 2.3.7 or 2.3.8

There is a version 2.3.8 in Rubygems but I cannot see the changes in the source code. Where is the code of this version?

clarify license statement

It says "License:: MIT and/or Creative Commons Attribution-ShareAlike"

If it is "MIT and CC-BY-SA" then conditions of both licenses have to be followed.

If it is "MIT or CC-BY-SA" then conditions of either licences can be followed.

Can you clarify? I assume it is "MIT or CC-BY-SA"