dbd 0.0.1 → 0.0.2

data/lib/dbd/time_stamp.rb

@@ -0,0 +1,105 @@
+module Dbd
+
+  ##
+  # TimeStamp
+  #
+  # Each Fact has a time_stamp with a granularity of 1 ns. The small
+  # granularity is essential to allow enough "density" of Facts in a
+  # large fact stream. Since all Facts need to have a strictly
+  # monotonically increasing time_stamp, this causes a limitation of
+  # max 1_000_000_000 Facts per second in a fact stream.
+  #
+  # A second reason for a fine grained granularity of the time_stamp
+  # is to reduce the chance (but not to zero) for collisions between
+  # Facts when 2 (or more) fact streams with overlapping time ranges
+  # need to be merged. But, collisions are always possible and need
+  # to be handled (since this can be expensive, we need to avoid them).
+  #
+  # A practicaly problem with calculating a "randomized" time_stamp is
+  # that the system reports a Wall clock with a granularity of 1 us on
+  # MRI Ruby and only 1 ms on JRuby (see JSR 310). To solve this problem,
+  # some nifty tricks are needed to create more "randomized" time_stamps,
+  # while still guaranteeing, the strictly monotonic increase in an
+  # upredictable fact stream.
+  #
+  # Performance measurements show a typical 30 - 60 us delay between the
+  # consecutive created facts (on MRI and JRuby), so a randomization of
+  # e.g. 1 - 999 ns should not cause fundamental problems for the density
+  # of the facts (even if computers speed up a factor of 30 or an
+  # implementation in a faster language). Still this is an ad-hoc
+  # optimization at creation time and can be optimized without breaking
+  # the specification of the fact stream.
+  #
+  # A time_stamp does not need to represent the exact time of the
+  # creation of the fact, it only has to increase strictly monotic
+  # in a fact stream.
+  class TimeStamp
+
+    attr_reader :time
+
+    ##
+    # Builds a new TimeStamp.
+    #
+    # @param [Hash{Symbol => Object}] options
+    # @option options [Time] :time (Time.now) force the time to this value
+    # @option options [TimeStamp] :larger_than (void) time_stamp must be larger than this
+    def initialize(options={})
+      @time = options[:time] || new_time(options[:larger_than])
+    end
+
+    ##
+    # regexp for the nanosecond granularity and in UTC
+    #
+    # Can be used to validate input strings or in tests.
+    def self.to_s_regexp
+      /\d{4}-\d\d-\d\d \d\d:\d\d:\d\d\.\d{9} UTC/
+    end
+
+  private
+
+    def new_time(larger_than)
+      max_with_nil(Time.now.utc, (larger_than && larger_than.time)) + random_offset
+    end
+
+    def random_offset
+      Rational("#{1+rand(999)}/1_000_000_000")
+    end
+
+  public
+
+    ##
+    # to a nanosecond granularity and in UTC
+    def to_s
+      @time.strftime('%F %T.%N %Z')
+    end
+
+    def ==(other)
+      @time == other.time
+    end
+
+    def hash
+      @time.hash
+    end
+
+    def >(other)
+      @time > other.time
+    end
+
+    def <(other)
+      @time < other.time
+    end
+
+    def <=(other)
+      @time <= other.time
+    end
+
+    def +(seconds)
+      TimeStamp.new(time: (@time + seconds))
+    end
+
+    def -(other)
+      @time - other.time
+    end
+
+  end
+end

data/lib/dbd/version.rb

@@ -1,3 +1,3 @@
 module Dbd
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/spec/lib/dbd/fact/collection_spec.rb

@@ -98,8 +98,8 @@ module Dbd
 
       describe "validate that only 'newer' elements are added" do
         before(:each) do
-          fact_2_with_subject.stub(:time_stamp).and_return(Time.new(2013,05,9,12,0,0))
-          fact_3_with_subject.stub(:time_stamp).and_return(Time.new(2013,05,9,12,0,1))
+          fact_2_with_subject.stub(:time_stamp).and_return(TimeStamp.new(time: Time.new(2013,05,9,12,0,0)))
+          fact_3_with_subject.stub(:time_stamp).and_return(TimeStamp.new(time: Time.new(2013,05,9,12,0,1)))
         end
 
         it "adding an element with a newer time_stamp succeeds" do
@@ -171,14 +171,16 @@ module Dbd
         end
       end
 
-      describe "validate that facts are valid? when loading in the Fact::Collection" do
+      describe "validate that facts do not have errors when loading in the Fact::Collection" do
         it "succeeds with a fact from factory" do
            subject << fact_2_with_subject # should_not raise_error
         end
 
-        it "raises FactError when fact.valid? is false" do
-           provenance_fact_context.stub(:valid?).and_return(false)
-           lambda { subject << provenance_fact_context } . should raise_error FactError
+        it "raises FactError with message when fact.errors has errors" do
+           provenance_fact_context.stub(:errors).and_return(["Error 1", "Error 2"])
+           lambda { subject << provenance_fact_context } . should raise_error(
+             FactError,
+             "Error 1, Error 2.")
         end
       end
 

data/spec/lib/dbd/fact_spec.rb

@@ -58,43 +58,55 @@ module Dbd
       end
     end
 
-    describe "time_stamp" do
-      it "can be set after creation" do
-        fact_1.time_stamp = Time.now
-      end
+    describe "time_stamp=" do
 
-      it "can be read back" do
-        time_now = Time.now
-        fact_1.time_stamp = time_now
-        fact_1.time_stamp.should == time_now
+      it "checks the type (too easy to try to give a Time arg" do
+        lambda { fact_1.time_stamp = Time.now } . should raise_error(ArgumentError)
       end
 
-      it "sees a difference of 2 nanoseconds" do
-        time_now = Time.now
-        fact_1.time_stamp = time_now + 0.000_000_002
-        fact_1.time_stamp.should > time_now
-      end
+      describe "set_once" do
 
-      it "raise a RuntimeError if trying to write it 2 times" do
-        time_now = Time.now
-        fact_1.time_stamp = time_now
-        lambda { fact_1.time_stamp = time_now } . should raise_error RuntimeError
+        let(:time_stamp_now) { TimeStamp.new }
+
+        it "can be set when nil" do
+          fact_1.time_stamp = time_stamp_now
+          fact_1.time_stamp.should == time_stamp_now
+        end
+
+        describe "setting it two times" do
+          it "with a different value raises a SetOnceError" do
+            fact_1.time_stamp = time_stamp_now
+            lambda { fact_1.time_stamp = (time_stamp_now+1) } . should raise_error SetOnceError
+          end
+        end
       end
     end
 
-    describe "valid?" do
-      it "the factory is valid?" do
-        fact_2_with_subject.should be_valid
+    describe "errors" do
+      it "the factory has no errors" do
+        fact_2_with_subject.errors.should be_empty
       end
 
-      it "without provenance_subject is not valid?" do
-        fact_2_with_subject.stub(:provenance_subject).and_return(nil)
-        fact_2_with_subject.should_not be_valid
+      describe "without provenance_subject" do
+
+        before(:each) do
+          fact_2_with_subject.stub(:provenance_subject).and_return(nil)
+        end
+
+        it "errors returns an array with 1 error message" do
+          fact_2_with_subject.errors.single.should match(/Provenance subject is missing/)
+        end
       end
 
-      it "without subject is not valid?" do
-        fact_2_with_subject.stub(:subject).and_return(nil)
-        fact_2_with_subject.should_not be_valid
+      describe "without subject" do
+
+        before(:each) do
+          fact_2_with_subject.stub(:subject).and_return(nil)
+        end
+
+        it "errors returns an array with an errorm message" do
+          fact_2_with_subject.errors.single.should match(/Subject is missing/)
+        end
       end
     end
 
@@ -124,32 +136,6 @@ module Dbd
       end
     end
 
-    describe "#dup_with_subject" do
-
-      let (:new_fact) do
-        fact_1.dup_with_subject(subject)
-      end
-
-      it "is a different instance" do
-        new_fact.should_not be_equal(fact_1)
-      end
-
-      it "is from the same class" do
-        new_fact.should be_a(fact_1.class)
-      end
-
-      it "has copied over the other attributes except :id, :time_stamp" do
-        (fact_1.class.attributes - [:id, :time_stamp, :subject]).each do |attr|
-           new_fact.send(attr).should == fact_1.send(attr)
-         end
-      end
-
-      it "has set the subject to the Resource subject" do
-        fact_1.subject.should_not == new_fact.subject # double check
-        new_fact.subject.should == subject
-      end
-    end
-
     describe "update_used_provenance_subjects" do
       it "sets the value for provenance_subject to true for a fact" do
         h = {}

data/spec/lib/dbd/graph_spec.rb

@@ -48,21 +48,64 @@ module Dbd
         end
       end
 
-      describe "sets the time_stamp and adds 2 nanoseconds if needed" do
-        it "sets the time_stamp" do
-          data_fact.time_stamp.should be_nil # assert pre condition
+      describe "sets the time_stamp and adds a random time (1..999 nanoseconds) if needed" do
+
+        # NOTE: reduced the far_future from 2500 to 2250 as work around for
+        #       http://jira.codehaus.org/browse/JRUBY-7095
+        let(:far_future) { TimeStamp.new(time: Time.new(2250,1,1,12,0,0).utc) }
+
+        it "don't touch the time_stamp if already set" do
+          data_fact.time_stamp = far_future
           subject << data_fact
-          subject.first.time_stamp.should be_a(Time)
+          subject.first.time_stamp.should == far_future
         end
 
-        it "sets a slightly higher time_stamp if smaller or equal then newest_time_stamp" do
-          subject
-          subject.newest_time_stamp
-          far_future = Time.new(2200,1,1,12,0,0).utc
-          subject.stub(:newest_time_stamp).and_return(far_future)
-          subject << data_fact
-          subject.first.time_stamp.should > far_future
-          subject.first.time_stamp.should < far_future + 0.000_000_005
+        describe "sets the time_stamp if not yet set" do
+
+          let(:near_future) { Time.now.utc + 100}
+          let(:fake_time_stamp) { TimeStamp.new(time: near_future) }
+
+          before(:each) do
+            # get this before setting the stub
+            fake_time_stamp # get this before setting the stub
+          end
+
+          it "sets it (to TimeStamp.new)" do
+            TimeStamp.stub(:new).and_return(fake_time_stamp)
+            data_fact.time_stamp.should be_nil # assert pre-condition
+            subject << data_fact
+            subject.first.time_stamp.should == fake_time_stamp
+          end
+
+          it "sends a slightly higher time_stamp than newest_time_stamp if Time.now <= newest_time_stamp" do
+            subject.stub(:newest_time_stamp).and_return(fake_time_stamp)
+            subject << data_fact
+            subject.first.time_stamp.should > fake_time_stamp
+            (subject.first.time_stamp - fake_time_stamp).should < Rational('1/1000_000') # 1 us
+          end
+        end
+      end
+
+      describe "a ProvenanceResource and a Resource" do
+
+        let(:provenance_resource) { Factories::ProvenanceResource.provenance_resource }
+        let(:resource) { Factories::Resource.facts_resource(provenance_resource.subject) }
+
+        it "does not fail" do
+          subject << provenance_resource
+        end
+
+        it "Adds the facts from the provenance_resource to the graph" do
+          subject << provenance_resource
+          subject.size.should == 2
+        end
+
+        it "Adds the facts from the provenance_resource and the resource to the graph" do
+          subject << provenance_resource
+          subject << resource
+          subject.size.should == 4
+          subject.first.should be_a(ProvenanceFact)
+          subject.last.class.should == Fact
         end
       end
     end
@@ -107,7 +150,7 @@ module Dbd
         end
 
         it "has time_stamp as second value" do
-          first_line.split(',')[1].should match(/"\d{4}-\d\d-\d\d \d\d:\d\d:\d\d UTC"/)
+          first_line.split(',')[1].should match(TimeStamp.to_s_regexp)
         end
 
         it "has an empty third value (signature of a provenance_fact)" do
@@ -174,7 +217,7 @@ module Dbd
         end
 
         it "has time_stamp as second value" do
-          first_line.split(',')[1].should match(/"\d{4}-\d\d-\d\d \d\d:\d\d:\d\d UTC"/)
+          first_line.split(',')[1].should match(TimeStamp.to_s_regexp)
         end
 
         it "has provenance_fact_1.subject as third value" do

data/spec/lib/dbd/performance_spec.rb

@@ -0,0 +1,41 @@
+require 'spec_helper'
+require 'benchmark'
+
+module Dbd
+  describe "performance" do
+
+    include Benchmark
+
+    def new_subject
+      Fact.new_subject
+    end
+
+    let(:provenance_fact_1) { Factories::ProvenanceFact.context(new_subject) }
+
+    NUMBER_OF_FACTS = 10_000
+
+    describe "#{NUMBER_OF_FACTS} facts" do
+      it "reports and checks the used time" do
+        graph = Graph.new
+        graph << provenance_fact_1
+        # Rehearsal
+        NUMBER_OF_FACTS.times do |counter|
+          data_fact = Factories::Fact.data_fact(provenance_fact_1, new_subject)
+          graph << data_fact
+        end
+        # Actual
+        start = Time.now
+        NUMBER_OF_FACTS.times do |counter|
+          data_fact = Factories::Fact.data_fact(provenance_fact_1, new_subject)
+          graph << data_fact
+        end
+        duration = Time.now - start
+        puts "\nDuration for inserting #{NUMBER_OF_FACTS} facts in the in-memory graph was #{duration*1000_000/NUMBER_OF_FACTS} us PER FACT"
+        graph.size.should == 2 * NUMBER_OF_FACTS + 1
+        duration.should < 0.000_15 * NUMBER_OF_FACTS
+        # typ. 37 us on Mac Ruby 2.0.0
+        # typ. 60 us on Mac jruby 1.7.3
+      end
+    end
+  end
+end

data/spec/lib/dbd/provenance_fact_spec.rb

@@ -48,34 +48,32 @@ module Dbd
         end
       end
 
-      describe "valid?" do
-        it "the factory isi valid?" do
-          provenance_fact_1.should be_valid
-        end
+      describe "errors" do
 
-        it "with ! provenance_subject is not valid?" do
-          provenance_fact_1.stub(:provenance_subject).and_return(subject)
-          provenance_fact_1.should_not be_valid
+        it "the factory has no errors" do
+          provenance_fact_1.errors.should be_empty
         end
 
-        it "without subject is not valid?" do
-          provenance_fact_1.stub(:subject).and_return(nil)
-          provenance_fact_1.should_not be_valid
-        end
-      end
+        describe "with a provenance_subject" do
 
-      describe "#dup_with_subject" do
+          before(:each) do
+            provenance_fact_1.stub(:provenance_subject).and_return(subject)
+          end
 
-        let (:new_fact) do
-          provenance_fact_1.dup_with_subject(subject)
+          it "errors returns an array with 1 error message" do
+            provenance_fact_1.errors.single.should match(/Provenance subject should not be present in Provenance Fact/)
+          end
         end
 
-        it "is a different instance" do
-          new_fact.should_not be_equal(provenance_fact_1)
-        end
+        describe "without subject" do
+
+          before(:each) do
+            provenance_fact_1.stub(:subject).and_return(nil)
+          end
 
-        it "is from the same class" do
-          new_fact.should be_a(provenance_fact_1.class)
+          it "errors returns an array with an error message" do
+            provenance_fact_1.errors.single.should match(/Subject is missing/)
+          end
         end
       end
 

data/spec/lib/dbd/provenance_resource_spec.rb

@@ -47,17 +47,19 @@ module Dbd
       let(:fact_1) { Factories::Fact.fact_1(provenance_resource_subject) }
 
       describe "data facts" do
-        it "with correct subject" do
+        it "with correct subject it works" do
           provenance_resource << provenance_fact_context_with_correct_subject
           provenance_resource.first.subject.should == provenance_resource_subject
         end
 
-        it "with incorrect subject it raise SubjectError" do
+        it "with incorrect subject it raises SubjectError" do
           lambda { provenance_resource << provenance_fact_context_with_incorrect_subject } .
-            should raise_error SubjectError
+            should raise_error SetOnceError,
+              "Value of subject was #{provenance_fact_context_with_incorrect_subject.subject}, " \
+              "trying to set it to #{provenance_resource.subject}"
         end
 
-        it "with nil subject" do
+        it "with nil subject it sets the subject" do
           provenance_resource << provenance_fact_context
           provenance_resource.first.subject.should == provenance_resource_subject
         end
@@ -67,7 +69,7 @@ module Dbd
           provenance_resource.first.provenance_subject.should be_nil
         end
 
-        it "with incorrect provenance_subjecti ProvenanceError" do
+        it "with incorrect provenance_subject it raises ProvenanceError" do
           lambda { provenance_resource << fact_1 } .
             should raise_error ProvenanceError
         end