Class: UUID
- Inherits:
-
Object
- Object
- UUID
- Defined in:
- lib/uuid.rb
Overview
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.
Defined Under Namespace
Modules: Version Classes: Client, Server
Constant Summary collapse
- VERSION =
Version::STRING
- CLOCK_MULTIPLIER =
Clock multiplier. Converts Time (resolution: seconds) to UUID clock (resolution: 10ns)
10000000
- CLOCK_GAPS =
Clock gap is the number of ticks (resolution: 10ns) between two Ruby Time ticks.
100000
- VERSION_CLOCK =
Version number stamped into the UUID to identify it as time-based.
0x0100
- FORMATS =
Formats supported by the UUID generator.
:default
-
Produces 36 characters, including hyphens separating the UUID value parts
:compact
-
Produces a 32 digits (hexadecimal) value with no hyphens
:urn
-
Adds the prefix
urn:uuid:
to the default format
{ :compact => '%08x%04x%04x%04x%012x', :default => '%08x-%04x-%04x-%04x-%012x', :urn => 'urn:uuid:%08x-%04x-%04x-%04x-%012x', }
- STATE_FILE_FORMAT =
MAC address (48 bits), sequence number and last clock
'SLLQ'
Class Method Summary collapse
-
.generate(format = :default) ⇒ Object
Generates a new UUID string using
format
. -
.generator ⇒ Object
Returns the UUID generator used by generate.
-
.mode ⇒ Object
The access mode of the state file.
-
.server=(address) ⇒ Object
Call this to use a UUID Server.
-
.state_file(mode = 0644) ⇒ Object
Creates an empty state file in /var/tmp/ruby-uuid or the windows common application data directory using mode 0644.
-
.state_file=(path) ⇒ Object
Specify the path of the state file.
-
.validate(uuid) ⇒ Object
Returns true if
uuid
is in compact, default or urn formats.
Instance Method Summary collapse
-
#generate(format = :default) ⇒ Object
Generates a new UUID string using
format
. -
#iee_mac_address ⇒ Object
Uses system calls to get a mac address.
-
#initialize ⇒ UUID
constructor
Create a new UUID generator.
- #inspect ⇒ Object
-
#mac_address ⇒ Object
return iee_mac_address if available, pseudo_mac_address otherwise.
-
#next_sequence ⇒ Object
Updates the state file with a new sequence number.
-
#pseudo_mac_address ⇒ Object
Generate a pseudo MAC address because we have no pure-ruby way to know the MAC address of the NIC this system uses.
Constructor Details
#initialize ⇒ UUID
Create a new UUID generator. You really only need to do this once.
249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 |
# File 'lib/uuid.rb', line 249 def initialize @drift = 0 @last_clock = (Time.now.to_f * CLOCK_MULTIPLIER).to_i @mutex = Mutex.new state_file = self.class.state_file if state_file && File.size?(state_file) then next_sequence else @mac = mac_address fail "Cannot determine MAC address from any available interface, tried with #{mac_address}" if @mac == 0 @sequence = rand 0x10000 if state_file open_lock 'wb' do |io| write_state io end end end end |
Class Method Details
.generate(format = :default) ⇒ Object
Generates a new UUID string using format
. See FORMATS for a list of supported formats.
120 121 122 123 |
# File 'lib/uuid.rb', line 120 def self.generate(format = :default) @uuid ||= new @uuid.generate format end |
.generator ⇒ Object
Returns the UUID generator used by generate. Useful if you need to mess with it, e.g. force next sequence when forking (e.g. Unicorn, Resque):
after_fork do
UUID.generator.next_sequence
end
132 133 134 |
# File 'lib/uuid.rb', line 132 def self.generator @uuid ||= new end |
.mode ⇒ Object
The access mode of the state file. Set it with state_file.
112 113 114 |
# File 'lib/uuid.rb', line 112 def self.mode @mode end |
.server=(address) ⇒ Object
Call this to use a UUID Server. Expects address to bind to (SOCKET_NAME is a good default)
139 140 141 |
# File 'lib/uuid.rb', line 139 def self.server=(address) @uuid = Client.new(address) unless Client === @uuid end |
.state_file(mode = 0644) ⇒ Object
Creates an empty state file in /var/tmp/ruby-uuid or the windows common application data directory using mode 0644. Call with a different mode before creating a UUID generator if you want to open access beyond your user by default.
If the default state dir is not writable, UUID falls back to ~/.ruby-uuid.
State files are not portable across machines.
152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 |
# File 'lib/uuid.rb', line 152 def self.state_file(mode = 0644) return @state_file unless @state_file.nil? @mode = mode begin require 'Win32API' csidl_common_appdata = 0x0023 path = 0.chr * 260 get_folder_path = Win32API.new('shell32', 'SHGetFolderPath', 'LLLLP', 'L') get_folder_path.call 0, csidl_common_appdata, 0, 1, path state_dir = File.join(path.strip) rescue LoadError state_dir = File.join('', 'var', 'tmp') end if File.writable?(state_dir) then @state_file = File.join(state_dir, 'ruby-uuid') else @state_file = File.('.ruby-uuid', '~') end @state_file end |
.state_file=(path) ⇒ Object
Specify the path of the state file. Use this if you need a different location for your state file.
Set to false if your system cannot use a state file (e.g. many shared hosts).
185 186 187 |
# File 'lib/uuid.rb', line 185 def self.state_file=(path) @state_file = path end |
.validate(uuid) ⇒ Object
Returns true if uuid
is in compact, default or urn formats. Does not validate the layout (RFC 4122 section 4) of the UUID.
192 193 194 195 196 |
# File 'lib/uuid.rb', line 192 def self.validate(uuid) return true if uuid =~ /\A[\da-f]{32}\z/i return true if uuid =~ /\A(urn:uuid:)?[\da-f]{8}-([\da-f]{4}-){3}[\da-f]{12}\z/i end |
Instance Method Details
#generate(format = :default) ⇒ Object
Generates a new UUID string using format
. See FORMATS for a list of supported formats.
273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 |
# File 'lib/uuid.rb', line 273 def generate(format = :default) template = FORMATS[format] raise ArgumentError, "invalid UUID format #{format.inspect}" unless template # 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. clock = @mutex.synchronize do clock = (Time.new.to_f * CLOCK_MULTIPLIER).to_i & 0xFFFFFFFFFFFFFFF0 if clock > @last_clock then @drift = 0 @last_clock = clock elsif clock == @last_clock then drift = @drift += 1 if drift < 10000 then @last_clock += 1 else Thread.pass nil end else next_sequence @last_clock = clock end end until clock template % [ clock & 0xFFFFFFFF, (clock >> 32) & 0xFFFF, ((clock >> 48) & 0xFFFF | VERSION_CLOCK), @sequence & 0xFFFF, @mac & 0xFFFFFFFFFFFF ] end |
#iee_mac_address ⇒ Object
Uses system calls to get a mac address
231 232 233 234 235 236 237 |
# File 'lib/uuid.rb', line 231 def iee_mac_address begin Mac.addr.gsub(/:|-/, '').hex & 0x7FFFFFFFFFFF rescue 0 end end |
#inspect ⇒ Object
344 345 346 347 |
# File 'lib/uuid.rb', line 344 def inspect mac = ("%012x" % @mac).scan(/[0-9a-f]{2}/).join(':') "MAC: #{mac} Sequence: #{@sequence}" end |
#mac_address ⇒ Object
return iee_mac_address if available, pseudo_mac_address otherwise
242 243 244 245 |
# File 'lib/uuid.rb', line 242 def mac_address return iee_mac_address unless iee_mac_address == 0 return pseudo_mac_address end |
#next_sequence ⇒ Object
Updates the state file with a new sequence number.
320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 |
# File 'lib/uuid.rb', line 320 def next_sequence if self.class.state_file open_lock 'rb+' do |io| @mac, @sequence, @last_clock = read_state(io) io.rewind io.truncate 0 @sequence += 1 write_state io end else @sequence += 1 end rescue Errno::ENOENT open_lock 'w' do |io| write_state io end ensure @last_clock = (Time.now.to_f * CLOCK_MULTIPLIER).to_i @drift = 0 end |
#pseudo_mac_address ⇒ Object
Generate a pseudo MAC address because we have no pure-ruby way to know the MAC address of the NIC this system uses. Note that cheating with pseudo arresses here is completely legal: see Section 4.5 of RFC4122 for details.
This implementation is shamelessly stolen from
https://github.com/spectra/ruby-uuid/blob/master/uuid.rb
Thanks spectra.
208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 |
# File 'lib/uuid.rb', line 208 def pseudo_mac_address sha1 = ::Digest::SHA1.new 256.times do r = [rand(0x100000000)].pack "N" sha1.update r end str = sha1.digest r = rand 14 # 20-6 node = str[r, 6] || str if RUBY_VERSION >= "1.9.0" nnode = node.bytes.to_a nnode[0] |= 0x01 node = '' nnode.each { |s| node << s.chr } else node[0] |= 0x01 # multicast bit end node.bytes.collect{|b|b.to_s(16)}.join.hex & 0x7FFFFFFFFFFF end |