A UUID generator.

This class can be used to genereate Apache Cassandra timeuuid and uuid values.

Note
Instances of this class are absolutely not threadsafe. You should never share instances between threads.
See Also:

Inherits

Object

Methods

self.

new

(node_id = (::SecureRandom.random_number(2**47) | 0x010000000000), clock_id = ::SecureRandom.random_number(65536), clock = ::Time)

Create a new UUID generator.

The clock ID and node ID components are set to random numbers when the generator is created. These are used for generation of time UUIDs only.

Parameters:
Name Type Details
node_id Integer (defaults to: (::SecureRandom.random_number(2**47) | 0x010000000000)) an alternate node ID
clock_id Integer (defaults to: ::SecureRandom.random_number(65536)) an alternate clock ID
clock Object<#now> (defaults to: ::Time) used to generate timeuuid from current time
Raises:
Type Details
ArgumentError if clock doesn’t respond to now

now

Returns a new UUID with a time component that is the current time.

If two calls to #now happen within the time afforded by the system clock resolution a counter is incremented and added to the time component.

If the clock moves backwards the clock ID is reset to a new random number.

Examples:
Creating a sequential TimeUuids for the current time
generator = Cassandra::Uuid::Generator.new
timeuuids = 5.times.map { generator.now }

puts timeuuids.zip(timeuuids.map(&:to_time)).map(&:inspect)

# Outputs:
# [8614b7d0-5646-11e4-8e54-6761d3995ef3, 2014-10-17 21:42:42 UTC]
# [8614b91a-5646-11e4-8e54-6761d3995ef3, 2014-10-17 21:42:42 UTC]
# [8614b960-5646-11e4-8e54-6761d3995ef3, 2014-10-17 21:42:42 UTC]
# [8614b99c-5646-11e4-8e54-6761d3995ef3, 2014-10-17 21:42:42 UTC]
# [8614b9ce-5646-11e4-8e54-6761d3995ef3, 2014-10-17 21:42:42 UTC]
Returns:
Type Details
TimeUuid a new UUID
See Also:
  • Time.now
Specifications:
Generator#now returns a UUID generated from the current time
x = generator.now
x.to_time.to_i.should == 1370771820
x.to_time.usec.should == 329394
Generator#now returns unique IDs even when called within a time shorter than the clock resolution
x1 = generator.now
x2 = generator.now
clock.stub(:usec).and_return(329394 + 1)
x3 = generator.now
x1.should_not == x2
x2.should_not == x3
Generator#now creates a pseudo random clock ID
str = generator.now.to_s.split('-')[3]
str.should_not === '0000'
Generator#now uses the clock ID for all generated UUIDs
str1 = generator.now.to_s.split('-')[3]
str2 = generator.now.to_s.split('-')[3]
str3 = generator.now.to_s.split('-')[3]
str1.should == str2
str2.should == str3
Generator#now creates a new clock ID when the clock has moved backwards
str1 = generator.now.to_s.split('-')[3]
clock.stub(:to_i).and_return(1370771820 - 5)
str2 = generator.now.to_s.split('-')[3]
str1.should_not == str2
Generator#now creates a pseudo random node ID
str = generator.now.to_s.split('-')[4]
str.should_not == '000000000000'
Generator#now uses the node ID for all generated UUIDs
str1 = generator.now.to_s.split('-')[4]
str2 = generator.now.to_s.split('-')[4]
str3 = generator.now.to_s.split('-')[4]
str1.should == str2
str2.should == str3
Generator#now sets the multicast bit of the node ID (so that it does not conflict with valid MAC addresses)
x = generator.now.value & 0x010000000000
x.should == 0x010000000000
Generator#now generates a version 1, variant 1 UUID
x = generator.at(clock)
(x.value & 0x10008000000000000000).should == 0x10008000000000000000

at

(*args)

Returns a new UUID with a time component based on the specified Time. A piece of jitter is added to ensure that multiple calls with the same time do not generate the same UUID (if you want determinism you can set the second parameter to zero).

Note
the jitter argument accepted by all variants of this method is required to add randomness to generated TimeUuid and might affect the order of generated timestamps. You should set jitter to 0 when the source time(stamp)s are unique.
Examples:
Creating a TimeUuid from a Time instance
generator = Cassandra::Uuid::Generator.new
timeuuid  = generator.at(Time.at(1413582460))

puts timeuuid.to_time

# Outputs:
# 2014-10-17 21:47:40 UTC
Creating a TimeUuid from a timestamp
generator = Cassandra::Uuid::Generator.new
timeuuid  = generator.at(1413582423)

puts timeuuid.to_time

# Outputs:
# 2014-10-17 21:47:03 UTC
Avoid jitter in generated TimeUuid
timestamp = 1413582418
generator = Cassandra::Uuid::Generator.new
timeuuid  = generator.at(timestamp, 0)

puts timeuuid.to_time.to_i

# Outputs:
# 1413582418
Overloads:
at(time, jitter = SecureRandom.random_number(65536))

Returns a new UUID

Parameters:
Name Type Details
time Time a Time instance
jitter Integer (defaults to: SecureRandom.random_number(65536)) a number of microseconds to add to the time
Returns:
Type Details
TimeUuid a new UUID
at(seconds_with_frac, jitter = SecureRandom.random_number(65536))

Returns a new UUID

Parameters:
Name Type Details
seconds_with_frac Numeric can be Integer, Types::Float, Rational, or other Numeric
jitter Integer (defaults to: SecureRandom.random_number(65536)) a number of microseconds to add to the time
Returns:
Type Details
TimeUuid a new UUID
at(seconds, microseconds_with_frac, jitter = SecureRandom.random_number(65536))

Returns a new UUID

Parameters:
Name Type Details
seconds Integer
microseconds_with_frac Numeric can be Integer, Types::Float, Rational, or other Numeric
jitter Integer (defaults to: SecureRandom.random_number(65536)) a number of microseconds to add to the time
Returns:
Type Details
TimeUuid a new UUID
Raises:
Type Details
ArgumentError when given no arguments or more than 3 arguments
See Also:
  • Time.at
Specifications:
Generator#at returns a UUID for the specified time with a bit of random jitter
x = generator.at(clock)
x.to_time.to_i.should == 1370771820
x.to_time.usec.should be > 329394
Generator#at returns a UUID for the specified time with an offset
x = generator.at(clock, 8)
x.to_time.to_i.should == 1370771820
x.to_time.usec.should == 329394 + 8
Generator#at returns a UUID for the specified timestamp with a bit of random jitter
x = generator.at(1370771820, 329394)
x.to_time.to_i.should == 1370771820
x.to_time.usec.should be > 329394
Generator#at returns a UUID for the specified timestamp with an offset
x = generator.at(1370771820, 329394, 8)
x.to_time.to_i.should == 1370771820
x.to_time.usec.should == 329394 + 8

uuid

Returns a completely random version 4 UUID.

Examples:
Generating a random Uuid
generator = Cassandra::Uuid::Generator.new
uuid      = generator.uuid

puts uuid

# Outputs:
# 664dedae-e162-4bc0-9066-b9f1968252aa
Returns:
Type Details
Uuid a new UUID
See Also:
  • SecureRandom.uuid