torid 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e6dacf1ffa7be13c30286d37766f06b04cfef520
+  data.tar.gz: eb17f8af92781af966f8575148346990b0c055a5
+SHA512:
+  metadata.gz: ab397dcae732b089f5f5eba45c17dd1362fb4928a48fa30b9275c226e91cacd37f6c6248dd6dc26cc1d6ebe56b188f4d6e313670312a8f6811cea60f6c7b5f7e
+  data.tar.gz: 0265870e23051dfce0d1953c336447bd82e45129d34ca3156fcc4f4f701d329faad1e0f0b03612b4188189481734ba625f94ac2895f8dae54a1276fcff9048e2

data/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Hi there!
+
+I see you are interested in contributing. That is wonderful. I love
+contributions.
+
+I guarantee that there are bugs in this software. And I guarantee that there is
+a feature you want that is not in here yet. As such, any and all bugs reports
+are gratefully accepted, bugfixes even more so. Helping out with bugs is the
+easiest way to contribute.
+
+
+## The Quick Version
+
+* Have a [GitHub Account][].
+* Search the [GitHub Issues][] and see if your issue already present. If so
+  add your comments, :thumbsup:, etc.
+* Issue not there? Not a problem, open up a [new issue][].
+    * **Bug reports** please be as detailed as possible. Include:
+        * full ruby engine and version: `ruby -e 'puts RUBY_DESCRIPTION'`
+        * operating system and version
+        * version of torid `ruby -rubygems -e "require 'torid'; puts Torid::VERSION"`
+        * as much detail about the bug as possible so I can replicate it. Feel free
+          to link in a [gist][]
+    * **New Feature**
+        * What the new feature should do.
+        * What benefit the new feature brings to the project.
+* Fork the [repo][].
+* Create a new branch for your issue: `git checkout -b issue/my-issue`
+* Lovingly craft your contribution:
+    * `rake develop` to get started, or if you prefer bundler `rake develop:using_bundler && bundle`.
+    * `rake test` to run tests
+* Make sure that `rake test` passes. It's important, I said it twice.
+* Add yourself to the contributors section below.
+* Submit your [pull request][].
+
+# Contributors
+
+* [Jeremy Hinegardner](https://github.com/copiousfreetime)
+* [Kevin Barnes](https://github.com/vinbarnes)
+
+[GitHub Account]: https://github.com/signup/free "GitHub Signup"
+[GitHub Issues]:  https://github.com/copiousfreetime/torid/issues "Torid Issues"
+[new issue]:      https://github.com/copiousfreetime/torid/issues/new "New Torid Issue"
+[gist]:           https://gist.github.com/ "New Gist"
+[repo]:           https://github.com/copiousfreetime/torid "Torid Repo"
+[pull request]:   https://help.github.com/articles/using-pull-requests "Using Pull Requests"

data/HISTORY.md

@@ -0,0 +1,5 @@
+# Torid Changelog
+## Version 1.0.0
+
+* Initial Release - Yeah!
+

data/LICENSE

@@ -0,0 +1,16 @@
+ISC LICENSE - http://opensource.org/licenses/isc-license.txt
+
+Copyright (c) 2013 Jeremy Hinegardner
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+

data/Manifest.txt

@@ -0,0 +1,18 @@
+CONTRIBUTING.md
+HISTORY.md
+LICENSE
+Manifest.txt
+README.md
+Rakefile
+lib/torid.rb
+lib/torid/clock.rb
+lib/torid/generator.rb
+lib/torid/uuid.rb
+tasks/default.rake
+tasks/this.rb
+test/test_clock.rb
+test/test_generator.rb
+test/test_helper.rb
+test/test_torid.rb
+test/test_uuid.rb
+test/test_version.rb

data/README.md

@@ -0,0 +1,100 @@
+## Torid
+
+* [Homepage](https://github.com/copiousfreetime/torid/)
+* [Github Project](https://github.com/copiousfreetime/torid)
+* email jeremy at copiousfreetime dot org
+
+## DESCRIPTION
+
+Temporally Ordered IDs. Generate universally unique identifiers (UUID)
+that sort lexically in time order.
+
+Torid exists to solve the problem of generating UUIDs that when ordered
+lexically, they are also ordered temporally. I needed a way to generate ids for
+events that are entering a system with the following criteria:
+
+1. Fast ID generation
+2. No central coordinating server/system
+3. No local storage
+4. Library code, that is multiple apps on the same machine can use the same code
+   and they will not generate duplicate ids
+5. Eventually stored in a UUID field in a database. So 128bit ids are totally
+   fine.
+
+The IDs that Torid generates are 128bit IDs made up of 2, 64bit parts.
+
+* 64bit microsecond level UNIX timestamp
+* 64bit hash of the system hostname, process id and a random value.
+
+## EXAMPLES
+
+#### Using the defaults
+
+```ruby
+require 'torid'
+
+uuid = Torid.uuid
+uuid.to_s         # => "0004fda4-318e-f380-5a45-5321cd065b02"
+uuid.bytes        # => "\x00\x04\xFD\xA41\x8E\xF3\x80ZES!\xCD\x06[\x02"
+```
+
+#### Using your own instance of a Generator
+
+```ruby
+require 'torid'
+
+generator = Torid::Generator.new
+uuid      = generator.next
+
+uuid.to_s        # => "0004fda4-3f42-3d01-4731-5a4aa8ddd6c3"
+uuid.bytes       # => "\x00\x04\xFD\xA4?B=\x01G1ZJ\xA8\xDD\xD6\xC3"
+```
+
+## CREDITS / RESOURCES
+
+The vast majority of the credit and research stems from:
+
+* [jondot's](https://github.com/jondot) blog post on [Fast ID Generation](http://blog.paracode.com/2012/04/16/fast-id-generation-part-1/) served to solidify my thoughts on the criteria I needed in an ID generation system. 
+* This let me to [Boundary's Flake](http://boundary.com/blog/2012/01/12/flake-a-decentralized-k-ordered-unique-id-generator-in-erlang/)
+* [James Golick's](https://github.com/jamesgolick) [lexical_uuid](https://github.com/jamesgolick/lexical_uuid), which if I had found a day earlier, I might be using instead of creating this.
+
+You could consider Torid to be a reimplementation of [lexical_uuid](https://github.com/jamesgolick/lexical_uuid). It definately steals some code from it and [simple_uuid](https://github.com/cassandra-rb/simple_uuid)
+
+Blog posts around ID generation:
+
+* [Wikipedia UUID](http://en.wikipedia.org/wiki/Universally_unique_identifier)
+* [RFC 4122](http://tools.ietf.org/html/rfc4122)
+* [Fast ID Generation Part I](http://blog.paracode.com/2012/04/16/fast-id-generation-part-1/)
+* [Boundary's Flake Project](http://boundary.com/blog/2012/01/12/flake-a-decentralized-k-ordered-unique-id-generator-in-erlang/)
+* [Flickr's Ticket Server](http://code.flickr.net/2010/02/08/ticket-servers-distributed-unique-primary-keys-on-the-cheap/)
+* [Twitter Snowflake](https://blog.twitter.com/2010/announcing-snowflake)
+* [Sharding & ID's at Instagram](http://instagram-engineering.tumblr.com/post/10853187575/sharding-ids-at-instagram)
+
+Libraries implementing similar approaches:
+
+* [simple_uuid](https://github.com/cassandra-rb/simple_uuid)
+* [uuid](https://github.com/assaf/uuid)
+* [flake](http://github.com/boundary/flake)
+* [BSON Object ID](https://github.com/mongodb/bson-ruby/blob/master/lib/bson/object_id.rb) and in [C](https://github.com/mongodb/bson-ruby/blob/master/ext/bson/native.c)
+* [ffi-uuid](https://github.com/mmullis/ffi-uuid)
+* [lexical_uuid](https://github.com/jamesgolick/lexical_uuid)
+
+## ISC LICENSE
+
+http://opensource.org/licenses/isc-license.txt
+
+Copyright (c) 2014 Jeremy Hinegardner
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+

data/Rakefile

@@ -0,0 +1,17 @@
+# vim: syntax=ruby
+load 'tasks/this.rb'
+
+This.name     = "torid"
+This.author   = "Jeremy Hinegardner"
+This.email    = "jeremy@copiousfreetime.org"
+This.homepage = "http://github.com/copiousfreetime/#{ This.name }"
+
+This.ruby_gemspec do |spec|
+  spec.add_dependency( 'fnv', '~> 0.2' )
+
+  spec.add_development_dependency( 'rake'     , '~> 10.1')
+  spec.add_development_dependency( 'minitest' , '~> 5.0' )
+  spec.add_development_dependency( 'rdoc'     , '~> 4.0' )
+end
+
+load 'tasks/default.rake'

data/lib/torid.rb

@@ -0,0 +1,22 @@
+# Torid - Temporally Ordered IDs. Generate universally unique identifiers (UUID)
+# that sort lexically in time order.
+module Torid
+  # Public: The Version of the Torid library as a String
+  VERSION = "1.0.0"
+
+  # Public: return the next Torid::UUID from the default Generator
+  #
+  # This is just a shortcut to Torid::Generator.next
+  #
+  # Example:
+  #
+  #   Torid.uuid # => Torid::UUID
+  #
+  # Returns a Torid::UUID
+  def self.uuid
+    Torid::Generator.next
+  end
+end
+require 'torid/clock'
+require 'torid/uuid'
+require 'torid/generator'

data/lib/torid/clock.rb

@@ -0,0 +1,65 @@
+require 'thread'
+module Torid
+  # Internal: A source for non-duplicate microsecond timestamps.
+  #
+  # Clock generates microsecond UNIX timestamps and guarantees that once a Clock
+  # instance is created, `Clock#tick` will never return the same value twice for
+  # that instance.
+  #
+  # This is effectively a reimplementation of
+  # https://github.com/jamesgolick/lexical_uuid/blob/master/lib/increasing_microsecond_clock.rb
+  # combined with
+  # https://github.com/jamesgolick/lexical_uuid/blob/master/lib/time_ext.rb
+  #
+  class Clock
+
+    # Internal: Return the current microsecond UNIX timstamp
+    #
+    # Example:
+    #
+    #   Clock.stamp => 1404774462369341
+    #
+    # Returns an Integer
+    def self.stamp
+      now = Time.now
+      (now.to_f * 1_000_000).floor
+    end
+
+    # Internal: Create a new Clock
+    #
+    # prev_stamp - An initial value for the previous timestamp (default:
+    #              Clock.stamp)
+    # mutex      - The synchronizing object to use
+    def initialize( prev_stamp = Clock.stamp, mutex = Mutex.new )
+      @prev_stamp = prev_stamp
+      @mutex      = mutex
+    end
+
+    # Internal: Return the next tick of the clock.
+    #
+    # Return the next tick of the clock, which will be a Clock.stamp value. This
+    # method will continue to return ever increasing values from when it was
+    # created.
+    #
+    # Returns an Integer.
+    def tick
+      @mutex.synchronize do
+        new_stamp   = Clock.stamp
+        @prev_stamp = if new_stamp > @prev_stamp then
+          new_stamp
+        else
+          @prev_stamp + 1
+        end
+      end
+    end
+
+    # Internal: The default instance to use for generating ticks
+    @instance = Clock.new
+
+    # Internal: Return the next `#tick` of the default Clock.
+    #
+    def self.tick
+      @instance.tick
+    end
+  end
+end

data/lib/torid/generator.rb

@@ -0,0 +1,82 @@
+require 'fnv'
+require 'socket'
+require 'securerandom'
+require 'torid/clock'
+require 'torid/uuid'
+
+module Torid
+  # Public: A class that will generate unique identifiers.
+  #
+  # Torid::Generator is the class that is used to generate Torid::UUID
+  # instances.
+  #
+  # Example:
+  #
+  #   Torid::Generator.next # => Torid::UUID
+  #
+  #   generator = Torid::Generator.new
+  #   generator.next                    # => Torid::UUID
+  #
+  class Generator
+    # Internal: The Clock instance used to get 64bit timestamps
+    attr_reader :clock
+
+    # Internal: The Node id of this instance
+    attr_reader :node_id
+
+    # Internal: Create a new Torid UUID Generator
+    #
+    # clock   - an object that responds to `#tick` and returns a 64bit integer.
+    #           (default: Torid::Clock)
+    # node_id - the 64bit node id of this node. (default: Generator.node_id)
+    #
+    def initialize( clock = Torid::Clock, node_id = Generator.node_id )
+      @clock   = clock
+      @node_id = node_id
+    end
+
+    # Public: Return the next UUID from this generator
+    #
+    # Returns Torid::UUID
+    def next
+      Torid::UUID.new( @clock.tick, @node_id )
+    end
+
+
+    # Internal: Generate a unique node identifier.
+    #
+    # Uses the first hostname of the system, the process id, some random bytes
+    # and hashes them all together using the non-cryptographic FNV hash.
+    #
+    # http://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function
+    #
+    # This method is copeid from
+    # https://github.com/jamesgolick/lexical_uuid/blob/master/lib/lexical_uuid.rb#L14
+    # with the random bytes added by me.
+    #
+    # Returns a 64 bit Integer
+    def self.create_node_id
+      hostname = Socket.gethostbyname( Socket.gethostname ).first
+      pid      = Process.pid
+      random   = SecureRandom.hex( 16 )
+      FNV.new.fnv1a_64("#{hostname}-#{pid}-#{random}")
+    end
+
+    # Internal: The default generator used by the system.
+    @instance = ::Torid::Generator.new( Torid::Clock, Generator.create_node_id )
+
+    # Public: Return the node id of the default Generator instance
+    #
+    # Returns a 64 bit Integer
+    def self.node_id
+      @instance.node_id
+    end
+
+    # Public: Return the next UUID from the default Generator
+    #
+    # Returns a Torid::UUID
+    def self.next
+      @instance.next
+    end
+  end
+end

data/lib/torid/uuid.rb

@@ -0,0 +1,138 @@
+module Torid
+  # Public: Represents a UUID generated by Torid
+  #
+  # Torid::UUID wraps 2 64bit Integer values and can convert them back and forth
+  # between raw bytes and the canonical UUID form of 32 lowercase hexadecimal
+  # lowercase hexadecimal digits, displayed in five groups separated by hyphens,
+  # in the form 8-4-4-4-12 for a total of 36 characters (32 alphanumeric
+  # characters and four hyphens)
+  #
+  # Since internally, Torid::UUID's represent a 64bit microsecond timestamp and
+  # a 'node_id', those data fields are also able to be returned as a Time
+  # instance or an Integer respectively.
+  #
+  # Examples
+  #
+  #   uuid = Torid.uuid
+  #   uuid.to_s  # => "0004fda3-8c73-5e0f-bae4-e9c86e3684a5"
+  #   uuid.bytes # => "\x00\x04\xFD\xA3\x8Cs^\x0F\xBA\xE4\xE9\xC8n6\x84\xA5"
+  #
+  #   uuid.timestamp # => Time
+  #   uuid.node_id   # => Integer
+  class UUID
+
+    # Public: Create a Torid::UUID from an existing String.
+    #
+    # The String can either be a 16 byte binary string, or a 36byte hexadecimal
+    # UUID in the 8-4-4-4-12 format.
+    #
+    # Examples
+    #
+    #   Torid::UUID.from( "0004fda3-8c73-5e0f-bae4-e9c86e3684a5" )                 # => Torid::UUID
+    #   Torid::UUID.from( "\x00\x04\xFD\xA3\x8Cs^\x0F\xBA\xE4\xE9\xC8n6\x84\xA5" ) # => Torid::UUID
+    #
+    # Returns a Torid::UUID
+    # Raises ArgumentError if the String is not convertable to a UUID.
+    def self.from( str )
+      case str.bytesize
+      when 36
+        from_string( str )
+      when 16
+        from_bytes( str )
+      else
+        raise ArgumentError, "UUID can only be loaded from a 16 byte binary string or a 36 byte formatted UUID string."
+      end
+    end
+
+    # Internal: Create a new UUID from an existing string in the 8-4-4-4-12 format
+    #
+    # Copied from lexical_uuid
+    #
+    # Returns a Torid::UUID
+    def self.from_string( str )
+      hex   = str.split('-').join
+      bytes = Array( hex ).pack("H32")
+      from_bytes( bytes )
+    end
+
+    # Internal: Create a new UUID from an existing 16 byte String
+    #
+    # Copied from lexical_uuid
+    #
+    # Returns a Torid::UUID
+    def self.from_bytes( bytes )
+      time_high, time_low, node_high, node_low = bytes.unpack("NNNN")
+      timestamp = ( time_high << 32 ) | time_low
+      node_id   = ( node_high << 32 ) | node_low
+      new( timestamp, node_id )
+    end
+
+    # Public: The 64bit microsecond UNIX timestamp
+    attr_reader :timestamp
+
+    # Public: The 64bit node id
+    attr_reader :node_id
+
+    # Internal: Create a new UUID.
+    #
+    # UUID's should only be created by calling one of the public methods that
+    # generate id's. See `Torid.uuid` or `Torid::Generator.next`. This
+    # constructor should not be called by users of this library.
+    #
+    # timestamp - an Integer value representing UNIX timestamp in microseconds
+    # node_id   - an Integer value representing the unique node id where this
+    #             UUID is generatoed
+    #
+    def initialize( timestamp = nil, node_id = nil )
+      @timestamp = timestamp
+      @node_id   = node_id
+      @bytes     = nil
+      @time      = nil
+    end
+
+    # Public: Return the Time value the internal microsecond timestamp
+    # represents.
+    #
+    # Examples
+    #
+    #   uuid.time # => Time
+    #
+    # Returns a Time instance
+    def time
+      @time ||= Time.at( timestamp / 1_000_000.0 )
+    end
+
+    # Public: Return the UUID as 16 bytes of raw data.
+    #
+    # Copied from lexical_uuid
+    #
+    # Examples
+    #
+    #   uuid.bytes # => "\x00\x04\xFD\xA3\x8Cs^\x0F\xBA\xE4\xE9\xC8n6\x84\xA5"
+    #
+    # Returns a binary String
+    def bytes
+      @bytes ||= [ @timestamp >> 32,
+                   @timestamp & 0xFFFF_FFFF,
+                   @node_id   >> 32,
+                   @node_id   & 0xFFFF_FFFF ].pack("NNNN")
+    end
+
+    # Public: Return the hexadecimal UUID string representation. This is the
+    # standard 8-4-4-4-12 UUID string representation.
+    #
+    # Copied from simple_uuid via lexical_uuid.
+    #
+    # Examples
+    #
+    #   uuid.to_s  # => "0004fda3-8c73-5e0f-bae4-e9c86e3684a5"
+    #
+    # Returns a String
+    def to_s
+      elements     = bytes.unpack("NnnCCa6")
+      node         = elements[-1].unpack('C*')
+      elements[-1] = '%02x%02x%02x%02x%02x%02x' % node
+      "%08x-%04x-%04x-%02x%02x-%s" % elements
+    end
+  end
+end

data/tasks/default.rake

@@ -0,0 +1,276 @@
+# vim: syntax=ruby
+require 'rake/clean'
+require 'digest'
+#------------------------------------------------------------------------------
+# If you want to Develop on this project just run 'rake develop' and you'll
+# have all you need to get going. If you want to use bundler for development,
+# then run 'rake develop:using_bundler'
+#------------------------------------------------------------------------------
+namespace :develop do
+
+  # Install all the development and runtime dependencies of this gem using the
+  # gemspec.
+  task :default do
+    require 'rubygems/dependency_installer'
+    installer = ::Gem::DependencyInstaller.new
+
+    This.set_coverage_gem
+
+    puts "Installing gem depedencies needed for development"
+    This.platform_gemspec.dependencies.each do |dep|
+      if dep.matching_specs.empty? then
+        puts "Installing : #{dep}"
+        installer.install dep
+      else
+        puts "Skipping   : #{dep} -> already installed #{dep.matching_specs.first.full_name}"
+      end
+    end
+    puts "\n\nNow run 'rake test'"
+  end
+
+  # Create a Gemfile that just references the gemspec
+  file 'Gemfile' => :gemspec do
+    File.open( "Gemfile", "w+" ) do |f|
+      f.puts "# DO NOT EDIT - This file is automatically generated"
+      f.puts "# Make changes to Manifest.txt and/or Rakefile and regenerate"
+      f.puts 'source "https://rubygems.org/"'
+      f.puts 'gemspec'
+    end
+  end
+
+  desc "Create a bundler Gemfile"
+  task :using_bundler => 'Gemfile' do
+    puts "Now you can 'bundle'"
+  end
+
+  # Gemfiles are build artifacts
+  CLOBBER << FileList['Gemfile*']
+end
+desc "Boostrap development"
+task :develop => "develop:default"
+
+#------------------------------------------------------------------------------
+# Minitest - standard TestTask
+#------------------------------------------------------------------------------
+begin
+  require 'rake/testtask'
+  Rake::TestTask.new( :test ) do |t|
+    t.ruby_opts    = %w[ -w -rubygems ]
+    t.libs         = %w[ lib spec test ]
+    t.pattern      = "{test,spec}/**/{test_*,*_spec}.rb"
+  end
+
+  task :test_requirements
+  task :test => :test_requirements
+  task :default => :test
+rescue LoadError
+  This.task_warning( 'test' )
+end
+
+#------------------------------------------------------------------------------
+# RDoc - standard rdoc rake task, although we must make sure to use a more
+#        recent version of rdoc since it is the one that has 'tomdoc' markup
+#------------------------------------------------------------------------------
+begin
+  gem 'rdoc' # otherwise we get the wrong task from stdlib
+  require 'rdoc/task'
+  RDoc::Task.new do |t|
+    t.markup   = 'tomdoc'
+    t.rdoc_dir = 'doc'
+    t.main     = 'README.md'
+    t.title    = "#{This.name} #{This.version}"
+    t.rdoc_files.include( FileList['*.{rdoc,md,txt}'], FileList['ext/**/*.c'],
+                          FileList['lib/**/*.rb'] )
+  end
+rescue StandardError, LoadError
+  This.task_warning( 'rdoc' )
+end
+
+#------------------------------------------------------------------------------
+# Coverage - optional code coverage, rcov for 1.8 and simplecov for 1.9, so
+#            for the moment only rcov is listed.
+#------------------------------------------------------------------------------
+if RUBY_VERSION < "1.9.0"
+  begin
+   require 'rcov/rcovtask'
+   Rcov::RcovTask.new( 'coverage' ) do |t|
+     t.libs      << 'spec'
+     t.pattern   = 'spec/**/*_spec.rb'
+     t.verbose   = true
+     t.rcov_opts << "-x ^/"           # remove all the global files
+     t.rcov_opts << "--sort coverage" # so we see the worst files at the top
+   end
+  rescue LoadError
+   This.task_warning( 'rcov' )
+  end
+else
+  begin
+    require 'simplecov'
+    desc 'Run tests with code coverage'
+    task :coverage do
+      ENV['COVERAGE'] = 'true'
+      Rake::Task[:test].execute
+    end
+    CLOBBER << FileList["coverage"]
+  rescue LoadError
+    This.task_warning( 'simplecov' )
+  end
+end
+
+#------------------------------------------------------------------------------
+# Manifest - We want an explicit list of thos files that are to be packaged in
+#            the gem. Most of this is from Hoe.
+#------------------------------------------------------------------------------
+namespace 'manifest' do
+  desc "Check the manifest"
+  task :check => :clean do
+    files = FileList["**/*", ".*"].exclude( This.exclude_from_manifest ).to_a.sort
+    files = files.select{ |f| File.file?( f ) }
+
+    tmp = "Manifest.tmp"
+    File.open( tmp, 'w' ) do |f|
+      f.puts files.join("\n")
+    end
+
+    begin
+      sh "diff -du Manifest.txt #{tmp}"
+    ensure
+      rm tmp
+    end
+    puts "Manifest looks good"
+  end
+
+  desc "Generate the manifest"
+  task :generate => :clean do
+    files = %x[ git ls-files ].split("\n").sort
+    files.reject! { |f| f =~ This.exclude_from_manifest }
+    File.open( "Manifest.txt", "w" ) do |f|
+      f.puts files.join("\n")
+    end
+  end
+end
+
+#------------------------------------------------------------------------------
+# Fixme - look for fixmes and report them
+#------------------------------------------------------------------------------
+namespace :fixme do
+  task :default => 'manifest:check' do
+    This.manifest.each do |file|
+      next if file == __FILE__
+      next unless file =~ %r/(txt|rb|md|rdoc|css|html|xml|css)\Z/
+      puts "FIXME: Rename #{file}" if file =~ /fixme/i
+      IO.readlines( file ).each_with_index do |line, idx|
+        prefix = "FIXME: #{file}:#{idx+1}".ljust(42)
+        puts "#{prefix} => #{line.strip}" if line =~ /fixme/i
+      end
+    end
+  end
+
+  def fixme_project_root
+    This.project_path( '../fixme' )
+  end
+
+  def fixme_project_path( subtree )
+    fixme_project_root.join( subtree )
+  end
+
+  def local_fixme_files
+    This.manifest.select { |p| p =~ %r|^tasks/| }
+  end
+
+  def outdated_fixme_files
+    local_fixme_files.reject do |local|
+      upstream     = fixme_project_path( local )
+      Digest::SHA256.file( local ) == Digest::SHA256.file( upstream )
+    end
+  end
+
+  def fixme_up_to_date?
+    outdated_fixme_files.empty?
+  end
+
+  desc "See if the fixme tools are outdated"
+  task :outdated => :release_check do
+    if fixme_up_to_date? then
+      puts "Fixme files are up to date."
+    else
+      outdated_fixme_files.each do |f|
+        puts "#{f} is outdated"
+      end
+    end
+  end
+
+  desc "Update outdated fixme files"
+  task :update => :release_check do
+    if fixme_up_to_date? then
+      puts "Fixme files are already up to date."
+    else
+      puts "Updating fixme files:"
+      outdated_fixme_files.each do |local|
+        upstream = fixme_project_path( local )
+        puts "  * #{local}"
+        FileUtils.cp( upstream, local )
+      end
+      puts "Use your git commands as appropriate."
+    end
+  end
+end
+desc "Look for fixmes and report them"
+task :fixme => "fixme:default"
+
+#------------------------------------------------------------------------------
+# Gem Specification
+#------------------------------------------------------------------------------
+# Really this is only here to support those who use bundler
+desc "Build the #{This.name}.gemspec file"
+task :gemspec do
+  File.open( This.gemspec_file, "wb+" ) do |f|
+    f.puts "# DO NOT EDIT - This file is automatically generated"
+    f.puts "# Make changes to Manifest.txt and/or Rakefile and regenerate"
+    f.write This.platform_gemspec.to_ruby
+  end
+end
+
+# the gemspec is also a dev artifact and should not be kept around.
+CLOBBER << This.gemspec_file.to_s
+
+# .rbc files from ruby 2.0
+CLOBBER << FileList["**/*.rbc"]
+
+# The standard gem packaging task, everyone has it.
+require 'rubygems/package_task'
+::Gem::PackageTask.new( This.platform_gemspec ) do
+  # nothing
+end
+
+#------------------------------------------------------------------------------
+# Release - the steps we go through to do a final release, this is pulled from
+#           a compbination of mojombo's rakegem, hoe and hoe-git
+#
+# 1) make sure we are on the master branch
+# 2) make sure there are no uncommitted items
+# 3) check the manifest and make sure all looks good
+# 4) build the gem
+# 5) do an empty commit to have the commit message of the version
+# 6) tag that commit as the version
+# 7) push master
+# 8) push the tag
+# 7) pus the gem
+#------------------------------------------------------------------------------
+task :release_check do
+  unless `git branch` =~ /^\* master$/
+    abort "You must be on the master branch to release!"
+  end
+  unless `git status` =~ /^nothing to commit/m
+    abort "Nope, sorry, you have unfinished business"
+  end
+end
+
+desc "Create tag v#{This.version}, build and push #{This.platform_gemspec.full_name} to rubygems.org"
+task :release => [ :release_check, 'manifest:check', :gem ] do
+  sh "git commit --allow-empty -a -m 'Release #{This.version}'"
+  sh "git tag -a -m 'v#{This.version}' v#{This.version}"
+  sh "git push origin master"
+  sh "git push origin v#{This.version}"
+  sh "gem push pkg/#{This.platform_gemspec.full_name}.gem"
+end

data/tasks/this.rb

@@ -0,0 +1,214 @@
+require 'pathname'
+
+# Public: A Class containing all the metadata and utilities needed to manage a
+# ruby project.
+class ThisProject
+  # The name of this project
+  attr_accessor :name
+
+  # The author's name
+  attr_accessor :author
+
+  # The email address of the author(s)
+  attr_accessor :email
+
+  # The homepage of this project
+  attr_accessor :homepage 
+
+  # The regex of files to exclude from the manifest
+  attr_accessor :exclude_from_manifest
+
+  # The hash of Gem::Specifications keyed' by platform
+  attr_accessor :gemspecs
+
+  # Public: Initialize ThisProject
+  #
+  # Yields self
+  def initialize(&block)
+    @exclude_from_manifest = %r/\.(git|DS_Store)|^(doc|coverage|pkg|tmp|Gemfile(\.lock)?)|^[^\/]+\.gemspec|\.(swp|jar|bundle|so|rvmrc)$|~$/
+    @gemspecs              = Hash.new
+    yield self if block_given?
+  end
+
+  # Public: return the version of ThisProject
+  #
+  # Search the ruby files in the project looking for the one that has the
+  # version string in it. This does not eval any code in the project, it parses
+  # the source code looking for the string.
+  #
+  # Returns a String version
+  def version
+    [ "lib/#{ name }.rb", "lib/#{ name }/version.rb" ].each do |v|
+      path = project_path( v )
+      line = path.read[/^\s*VERSION\s*=\s*.*/]
+      if line then
+        return line.match(/.*VERSION\s*=\s*['"](.*)['"]/)[1]
+      end
+    end
+  end
+
+  # Internal: Return a section of an RDoc file with the given section name
+  #
+  # path         - the relative path in the project of the file to parse
+  # section_name - the section out of the file from which to parse data
+  #
+  # Retuns the text of the section as an array of paragrphs.
+  def section_of( file, section_name )
+    re    = /^[=#]+ (.*)$/
+    sectional = project_path( file )
+    parts = sectional.read.split( re )[1..-1]
+    parts.map! { |p| p.strip }
+
+    sections = Hash.new
+    Hash[*parts].each do |k,v|
+      sections[k] = v.split("\n\n")
+    end
+    return sections[section_name]
+  end
+
+  # Internal: print out a warning about the give task
+  def task_warning( task )
+    warn "WARNING: '#{task}' tasks are not defined. Please run 'rake develop'"
+  end
+
+  # Internal: Return the full path to the file that is relative to the project
+  # root.
+  #
+  # path - the relative path of the file from the project root
+  #
+  # Returns the Pathname of the file
+  def project_path( *relative_path )
+    project_root.join( *relative_path )
+  end
+
+  # Internal: The absolute path of this file
+  #
+  # Returns the Pathname of this file.
+  def this_file_path
+    Pathname.new( __FILE__ ).expand_path
+  end
+
+  # Internal: The root directory of this project
+  #
+  # This is defined as being the directory that is in the path of this project
+  # that has the first Rakefile
+  #
+  # Returns the Pathname of the directory
+  def project_root
+    this_file_path.ascend do |p|
+      rakefile = p.join( 'Rakefile' )
+      return p if rakefile.exist?
+    end
+  end
+
+  # Internal: Returns the contents of the Manifest.txt file as an array
+  #
+  # Returns an Array of strings
+  def manifest
+    manifest_file = project_path( "Manifest.txt" )
+    abort "You need a Manifest.txt" unless manifest_file.readable?
+    manifest_file.readlines.map { |l| l.strip }
+  end
+
+  # Internal: Return the files that define the extensions
+  #
+  # Returns an Array
+  def extension_conf_files
+    manifest.grep( /extconf.rb\Z/ )
+  end
+
+  # Internal: Returns the gemspace associated with the current ruby platform
+  def platform_gemspec
+    gemspecs[platform]
+  end
+
+  def core_gemspec
+    Gem::Specification.new do |spec|
+      spec.name        = name
+      spec.version     = version
+      spec.author      = author
+      spec.email       = email
+      spec.homepage    = homepage
+
+      spec.summary     = summary
+      spec.description = description
+      spec.license     = license
+
+      spec.files       = manifest
+      spec.executables = spec.files.grep(/^bin/) { |f| File.basename(f) }
+      spec.test_files  = spec.files.grep(/^spec/)
+
+      spec.extra_rdoc_files += spec.files.grep(/(txt|rdoc|md)$/)
+      spec.rdoc_options = [ "--main"  , 'README.md',
+                            "--markup", "tomdoc" ]
+    end
+  end
+
+  # Internal: Return the gemspec for the ruby platform
+  def ruby_gemspec( core = core_gemspec, &block )
+    yielding_gemspec( 'ruby', core, &block )
+  end
+
+  # Internal: Return the gemspec for the jruby platform
+  def java_gemspec( core = core_gemspec, &block )
+    yielding_gemspec( 'java', core, &block )
+  end
+
+  # Internal: give an initial spec and a key, create a new gemspec based off of
+  # it.
+  #
+  # This will force the new gemspecs 'platform' to be that of the key, since the
+  # only reason you would have multiple gemspecs at this point is to deal with
+  # different platforms.
+  def yielding_gemspec( key, core )
+    spec = gemspecs[key] ||= core.dup
+    spec.platform = key
+    yield spec if block_given?
+    return spec
+  end
+
+  # Internal: Set the recovery gem development dependency
+  #
+  # These are dynamically set since they cannot be hard coded as there is 
+  # no way to ship them correctly in the gemspec
+  #
+  # Returns nothing.
+  def set_coverage_gem
+    if RUBY_VERSION < "1.9.0"
+      platform_gemspec.add_development_dependency( 'rcov', '~> 1.0.0' )
+    else
+      platform_gemspec.add_development_dependency( 'simplecov', '~> 0.8.2' )
+    end
+  end
+
+  # Internal: Return the platform of ThisProject at the current moment in time.
+  def platform
+    (RUBY_PLATFORM == "java") ? 'java' : Gem::Platform::RUBY
+  end
+
+  # Internal: Return the DESCRIPTION section of the README.rdoc file
+  def description_section
+    section_of( 'README.md', 'DESCRIPTION')
+  end
+ 
+ # Internal: Return the summary text from the README 
+  def summary
+    description_section.first
+  end
+
+  # Internal: Return the full description text from the README
+  def description
+    description_section.join(" ").tr("\n", ' ').gsub(/[{}]/,'').gsub(/\[[^\]]+\]/,'') # strip rdoc
+  end
+
+  def license
+    "ISC"
+  end
+
+  # Internal: The path to the gemspec file
+  def gemspec_file
+    project_path( "#{ name }.gemspec" )
+  end
+end
+
+This = ThisProject.new

data/test/test_clock.rb

@@ -0,0 +1,20 @@
+require 'test_helper'
+require 'torid/clock'
+
+module Torid
+  class ClockTest < ::Minitest::Test
+    def test_tick_is_after_stamp
+      stamp = Clock.stamp
+      tick  = Clock.tick
+      assert( tick > stamp )
+    end
+
+    def test_tick_follows_clock_not_time
+      stamp  = Clock.stamp
+      future = stamp + 10_000_000 
+      clock  = Clock.new( future )
+      tick   = clock.tick
+      assert_equal( future + 1, tick )
+    end
+  end
+end

data/test/test_generator.rb

@@ -0,0 +1,42 @@
+require 'test_helper'
+require 'torid/generator'
+
+module Torid
+  class GeneratorTest < ::Minitest::Test
+
+    def test_can_set_clock_on_initialize
+      g = Torid::Generator.new( 'clock' )
+      assert_equal( 'clock', g.clock )
+    end
+
+    def test_can_set_node_id_on_initialize
+      g = Torid::Generator.new( 'clock', 'node-id' )
+      assert_equal( 'clock', g.clock )
+      assert_equal( 'node-id', g.node_id)
+    end
+
+    def test_default_clock_is_set_on_initializes
+      g = Torid::Generator.new
+      assert_equal( Torid::Clock, g.clock )
+    end
+
+    def test_default_node_id_is_set_on_initialize
+      g = Torid::Generator.new
+      assert( g.node_id > 0 )
+    end
+
+    def test_clocks_tick_is_called_on_next
+      clock = ::Minitest::Mock.new
+      clock.expect( :tick, 42 )
+      g = Torid::Generator.new( clock )
+      g.next
+      clock.verify
+    end
+
+    def test_default_instance_creates_uuid
+      uuid = Torid::Generator.next
+      assert_instance_of( Torid::UUID, uuid )
+    end
+  end
+end
+

data/test/test_helper.rb

@@ -0,0 +1,5 @@
+require 'simplecov' rescue nil
+SimpleCov.start if ENV['COVERAGE']
+gem 'minitest'
+require 'minitest/autorun'
+require 'minitest/pride'

data/test/test_torid.rb

@@ -0,0 +1,12 @@
+require 'test_helper'
+require 'torid'
+
+module Torid
+  class ToridTest < ::Minitest::Test
+    def test_torid_generates_uuid
+      uuid = Torid.uuid
+      assert_instance_of( Torid::UUID, uuid)
+      assert_equal( Torid::Generator.node_id, uuid.node_id )
+    end
+  end
+end

data/test/test_uuid.rb

@@ -0,0 +1,58 @@
+require 'test_helper'
+require 'torid/uuid'
+
+module Torid
+  class UUIDTest < ::Minitest::Test
+
+    def setup
+      @timestamp = 1404617330909742
+      @node_id   = 42
+      @bytes     = [ @timestamp >> 32, @timestamp & 0xFFFF_FFFF,
+                     @node_id   >> 32, @node_id   & 0XFFFF_FFFF ].pack("NNNN")
+      @guid      = "0004fd7d-f50d-e22e-0000-00000000002a"
+    end
+
+    def test_round_trips_bytes
+      uuid = ::Torid::UUID.from( @bytes)
+      assert_equal( @bytes, uuid.bytes )
+    end
+
+    def test_extracts_timestamp_from_bytes
+      uuid = ::Torid::UUID.from( @bytes)
+      assert_equal( @timestamp, uuid.timestamp )
+    end
+
+    def test_extracts_node_id_from_bytes
+      uuid = ::Torid::UUID.from( @bytes)
+      assert_equal( @node_id , uuid.node_id )
+    end
+
+    def test_round_trips_uuid_string
+      uuid = ::Torid::UUID.from( @guid )
+      assert_equal( uuid.to_s, uuid.to_s )
+    end
+
+    def test_extracts_timestamp_from_uuid
+      uuid = ::Torid::UUID.from( @guid )
+      assert_equal( @timestamp, uuid.timestamp )
+    end
+
+    def test_extracts_node_id_from_uuid
+      uuid = ::Torid::UUID.from( @guid )
+      assert_equal( @node_id , uuid.node_id )
+    end
+
+    def test_create_from_raises_error
+      assert_raises( ArgumentError ) do
+        ::Torid::UUID.from( "abcdef" )
+      end
+    end
+
+    def test_creates_a_time_from_uuid
+      time = Time.at( @timestamp / 1_000_000.0 )
+      uuid = ::Torid::UUID.from( @guid )
+      assert_equal( time, uuid.time )
+    end
+
+  end
+end

data/test/test_version.rb

@@ -0,0 +1,11 @@
+require 'test_helper'
+require 'torid'
+
+module Torid
+  class VersionTest < ::Minitest::Test
+    def test_has_the_proper_format
+      assert_match( /\A\d+\.\d+\.\d+\Z/, Torid::VERSION)
+      assert_match( /\A\d+\.\d+\.\d+\Z/, Torid::VERSION.to_s)
+    end
+  end
+end

metadata

@@ -0,0 +1,135 @@
+--- !ruby/object:Gem::Specification
+name: torid
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Jeremy Hinegardner
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-07-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fnv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.1'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+description: 'Temporally Ordered IDs. Generate universally unique identifiers (UUID)
+  that sort lexically in time order. Torid exists to solve the problem of generating
+  UUIDs that when ordered lexically, they are also ordered temporally. I needed a
+  way to generate ids for events that are entering a system with the following criteria:
+  1. Fast ID generation 2. No central coordinating server/system 3. No local storage
+  4. Library code, that is multiple apps on the same machine can use the same code    and
+  they will not generate duplicate ids 5. Eventually stored in a UUID field in a database.
+  So 128bit ids are totally    fine. The IDs that Torid generates are 128bit IDs made
+  up of 2, 64bit parts. * 64bit microsecond level UNIX timestamp * 64bit hash of the
+  system hostname, process id and a random value.'
+email: jeremy@copiousfreetime.org
+executables: []
+extensions: []
+extra_rdoc_files:
+- CONTRIBUTING.md
+- HISTORY.md
+- Manifest.txt
+- README.md
+files:
+- CONTRIBUTING.md
+- HISTORY.md
+- LICENSE
+- Manifest.txt
+- README.md
+- Rakefile
+- lib/torid.rb
+- lib/torid/clock.rb
+- lib/torid/generator.rb
+- lib/torid/uuid.rb
+- tasks/default.rake
+- tasks/this.rb
+- test/test_clock.rb
+- test/test_generator.rb
+- test/test_helper.rb
+- test/test_torid.rb
+- test/test_uuid.rb
+- test/test_version.rb
+homepage: http://github.com/copiousfreetime/torid
+licenses:
+- ISC
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--main"
+- README.md
+- "--markup"
+- tomdoc
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Temporally Ordered IDs. Generate universally unique identifiers (UUID) that
+  sort lexically in time order.
+test_files: []