Class: Dbd::TimeStamp

Inherits:
Object
  • Object
show all
Defined in:
lib/dbd/time_stamp.rb

Overview

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.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ TimeStamp

Builds a new TimeStamp.

Parameters:

  • options (Hash{Symbol => Object}) (defaults to: {})

Options Hash (options):

  • :time (Time) — default: Time.now —

    force the time to this value

  • :larger_than (TimeStamp) — default: void —

    time_stamp must be larger than this



46
47
48
 
# File 'lib/dbd/time_stamp.rb', line 46

def initialize(options={})
  @time = options[:time] || new_time(options[:larger_than])
end

Instance Attribute Details

#time ⇒ Object (readonly)

Returns the value of attribute time.



38
39
40
 
# File 'lib/dbd/time_stamp.rb', line 38

def time
  @time
end

Class Method Details

.to_s_regexp ⇒ Object

regexp for the nanosecond granularity and in UTC

Can be used to validate input strings or in tests.



54
55
56
 
# File 'lib/dbd/time_stamp.rb', line 54

def self.to_s_regexp
  /\d{4}-\d\d-\d\d \d\d:\d\d:\d\d\.\d{9} UTC/
end

Instance Method Details

#+(seconds) ⇒ Object 



96
97
98
 
# File 'lib/dbd/time_stamp.rb', line 96

def +(seconds)
  TimeStamp.new(time: (@time + seconds))
end

#-(other) ⇒ Object 



100
101
102
 
# File 'lib/dbd/time_stamp.rb', line 100

def -(other)
  @time - other.time
end

#<(other) ⇒ Object 



88
89
90
 
# File 'lib/dbd/time_stamp.rb', line 88

def <(other)
  @time < other.time
end

#<=(other) ⇒ Object 



92
93
94
 
# File 'lib/dbd/time_stamp.rb', line 92

def <=(other)
  @time <= other.time
end

#==(other) ⇒ Object 



76
77
78
 
# File 'lib/dbd/time_stamp.rb', line 76

def ==(other)
  @time == other.time
end

#>(other) ⇒ Object 



84
85
86
 
# File 'lib/dbd/time_stamp.rb', line 84

def >(other)
  @time > other.time
end

#hash ⇒ Object 



80
81
82
 
# File 'lib/dbd/time_stamp.rb', line 80

def hash
  @time.hash
end

#to_s ⇒ Object

to a nanosecond granularity and in UTC



72
73
74
 
# File 'lib/dbd/time_stamp.rb', line 72

def to_s
  @time.strftime('%F %T.%N %Z')
end