class Cassandra::Uuid::Generator

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

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

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, 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, 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

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