spinoza 0.1 → 0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 868a9f9ccabcf28a96ace9484c9c0caf0bbacd26
-  data.tar.gz: 42d844a448adc075556b5933731bcb90e4a58356
+  metadata.gz: 8864d3908b3001de934f150becf1876972c78809
+  data.tar.gz: 7da59f8200f6b5d501842d950b98d9be440eb4ce
 SHA512:
-  metadata.gz: 4c178a4b1cf1e14cf538dec9602c4a25eca2f57a003a8f8db2b2b92fb9b55feb9014979db38caabc6af9ce2f7fc26dfda73b564da454599fb8b054f80132585b
-  data.tar.gz: ae5bcbdf391a45950d1d3aa4efc0ac52f10d99d413f0ee96e639c179ecb054a311ae14ab3448d0ecbc22976162e02e22d71a0cbb4088e091aa193decb7a1c86a
+  metadata.gz: f33925d0842233788b242cdde6d0d3c1311dff1d7d2e9349907516fd3ec95ba40b0961786e6f4e00accd3c8a01efe3e9732563758b3c640b34f6a4bb1b0745f7
+  data.tar.gz: 57e8c0075dc16a91180a89955f70c8548c310f10e4d0db444fa39a365c0be659174cb9ed7896bad64065263b7d31471a738d5eb7eb5f4dbad4e6f7364f4f7fd8

data/README.md

@@ -1,14 +1,77 @@
 spinoza
 =======
 
-A model of the Calvin distributed database.
+A model of the Calvin distributed database. The main purpose of this model is expository, rather than analysis for correctness or performance.
 
 Spinoza, like Calvin, was a philosopher who dealt in determinism.
 
-The model of the underlying computer and network system is in lib/spinoza/system.
-
 Calvin is developed by the Yale Databases group; the open-source releases are at https://github.com/yaledb.
 
+
+Structure
+=========
+
+The model of the underlying computer and network system is in [lib/spinoza/system](lib/spinoza/system).
+
+The Calvin model, implemented on the system models, is in [lib/spinoza/calvin](lib/spinoza/calvin). Other distributed transaction models could also be implemented on this layer.
+
+The transaction class, in [lib/spinoza/transaction.rb](lib/spinoza/transaction.rb), is mostly abstracted from these layers. It is very simplistic, intended to illustrate Calvin's replication and consistency characteristics.
+
+
+Running
+=======
+
+You will need ruby 2.0 or later, from http://ruby-lang.org, and the gems listed in the gemspec: 
+
+    sequel
+    sqlite3
+    rbtree
+
+You can also `gem install spinoza`, but it may not be up to date.
+
+To run the unit tests:
+
+    rake test
+
+Examples TBD.
+
+
+References
+==========
+
+* The Calvin papers:
+
+  * [The Case for Determinism in Database Systems](http://cs-www.cs.yale.edu/homes/dna/papers/determinism-vldb10.pdf)
+
+  * [Consistency Tradeoffs in Modern Distributed Database System Design](http://cs-www.cs.yale.edu/homes/dna/papers/abadi-pacelc.pdf)
+
+  * [Modularity and Scalability in Calvin](http://sites.computer.org/debull/A13june/calvin1.pdf)
+
+  * [Calvin: Fast Distributed Transactions for Partitioned Database Systems](http://www.cs.yale.edu/homes/dna/papers/calvin-sigmod12.pdf)
+
+  * [Lightweight Locking for Main Memory Database Systems](http://cs-www.cs.yale.edu/homes/dna/papers/vll-vldb13.pdf)
+
+
+To do
+=====
+
+* The performance and error modeling should optionally be statistical, with variation using some distribution.
+
+* Model IO latency and compute time, in addition to currently modeled network latency.
+
+* `Log#time_replicated` should be a function of the reading node and depend on the link characteristics between that node and the writing node.
+
+* Transactions, to be more realistic, should have dataflow dependencies among operations. (But only for non-key values, because Calvin splits dependent transactions.)
+
+* Transactions also need conditionals, or, at least, conditional abort, which is needed to support the splitting mentioned above.
+
+* For comparison, implement a 2-phase commit transaction processor on top of the Spinoza::System classes.
+
+* Output spacetime diagrams using graphviz.
+
+* See also 'TODO' in code.
+
+
 Contact
 =======
 

data/lib/spinoza/calvin/executor.rb

@@ -0,0 +1,107 @@
+require 'spinoza/common'
+
+# Represents the work performed in one thread. The scheduler assigns a sequence
+# of transactions to each of several executors. The executor handles the
+# transactions one at a time, in a series of substeps as data is received from
+# peers. Within an executor, the sequence of transactions and substeps is
+# totally ordered wrt the global timeline, but the sequences of two Executors
+# may interleave, which is how Calvin achieves some write concurrency.
+#
+# Does not have access to any subsystems except the node's Store and
+# communication with peer executors via the readcasters.
+#
+class Calvin::Executor
+  attr_reader :store
+  attr_reader :readcaster
+  attr_reader :task
+  
+  class StateError < StandardError; end
+  
+  # Represents the state of executing one transaction in this Executor, in
+  # the case where that execution involves waiting for data from peers.
+  class Task
+    attr_reader :txn
+    
+    # Accumulates results as they arrive locally and from peers.
+    attr_accessor :read_results
+    
+    # Set of tables the task is waiting for.
+    attr_accessor :remote_read_tables
+
+    def initialize txn, read_results: [], remote_read_tables: Set[]
+      @txn = txn
+      @read_results = read_results
+      @remote_read_tables = remote_read_tables
+    end
+  end
+  
+  def initialize store: nil, readcaster: nil
+    @store = store
+    @readcaster = readcaster
+    ready!
+  end
+  
+  def ready!
+    @task = nil
+  end
+  
+  def ready?
+    @task.nil?
+  end
+  
+  def assert_ready?
+    unless ready?
+      raise StateError, "cannot start new task -- already executing #{task}"
+    end
+  end
+
+  # Assumes all locks are held around this call.
+  def execute_transaction txn
+    assert_ready?
+
+    local_read_results = @readcaster.execute_local_reads txn
+    @readcaster.serve_reads txn, local_read_results
+
+    if passive? txn
+      result = local_read_results
+      ready!
+
+    elsif all_reads_are_local? txn
+      result = local_read_results
+      store.execute *txn.all_write_ops
+      ready!
+
+    else
+      @task = Task.new txn,
+        read_results: local_read_results,
+        remote_read_tables: txn.remote_read_tables(store)
+      result = false
+    end
+
+    return result
+  end
+  
+  def passive? txn
+    not txn.active? store
+  end
+
+  def all_reads_are_local? txn
+    txn.all_reads_are_local? store
+  end
+    
+  # Assumes all locks are held around this call.
+  def recv_remote_reads table, read_results
+    if task.remote_read_tables.include? table
+      task.remote_read_tables.delete table
+      task.read_results.concat read_results
+    # else this is a redundant message for this table, so ignore it
+    end
+
+    return false unless task.remote_read_tables.empty?
+
+    store.execute *task.txn.all_write_ops
+    result = task.read_results
+    ready!
+    result
+  end
+end

data/lib/spinoza/calvin/node.rb

@@ -0,0 +1,44 @@
+require 'spinoza/system/node'
+require 'spinoza/calvin/sequencer'
+require 'spinoza/calvin/scheduler'
+
+class Calvin::Node < Spinoza::Node
+  attr_reader :sequencer, :scheduler
+  attr_reader :log, :meta_log
+  
+  def initialize *tables, log: nil, meta_log: nil,
+      sequencer: nil, scheduler: nil, **rest
+    super *tables, **rest
+
+    @log = log
+    @meta_log = meta_log
+    @sequencer = sequencer || Calvin::Sequencer.new(node: self)
+    @scheduler = scheduler || Calvin::Scheduler.new(node: self)
+
+    on_transaction_finish &method(:default_output)
+  end
+
+  def default_output transaction, result
+    r = result.map {|rr| [rr.op.table, rr.val].join(":")}.join(", ")
+    puts "%07.6f [RESULT] #{transaction} => #{r}" % timeline.now
+  end
+
+  def recv msg: nil
+    scheduler.recv_peer_results **msg
+  end
+  
+  def read_batch batch_id
+    log.read batch_id, node: self
+  end
+  
+  def on_transaction_finish &b
+    @finished_transaction_handler = b
+  end
+
+  # Override this to put the result somewhere.
+  def finished_transaction transaction, result
+    if @finished_transaction_handler
+      @finished_transaction_handler[transaction, result]
+    end
+  end
+end

data/lib/spinoza/calvin/readcaster.rb

@@ -0,0 +1,50 @@
+require 'spinoza/common'
+require 'set'
+
+class Calvin::Readcaster
+  attr_reader :node
+  
+  def initialize node: nil
+    @node = node
+    @links = nil
+    @tables = node.tables
+  end
+  
+  def inspect
+    "<#{self.class} on #{node.inspect}>"
+  end
+
+  # Pre-computed map, by table, of which nodes might need data from this node:
+  # {table => Set[link, ...]} In other, words, excludes `table,link` pairs for
+  # which link.dst already has `table`.
+  def links
+    unless @links
+      @links = Hash.new {|h,k| h[k] = Set[]}
+      node.links.each do |there, link|
+        (@tables - there.tables).each do |table|
+          @links[table] << link
+        end
+      end
+    end
+    @links
+  end
+  
+  def execute_local_reads txn
+    local_reads = txn.all_read_ops.select {|r| @tables.include? r.table}
+    node.store.execute *local_reads
+  end
+  
+  def serve_reads txn, local_read_results
+    local_read_results.group_by {|r| r.op.table}.each do |table, results|
+      links[table].each do |link|
+        if txn.active?(link.dst)
+          send_read link, transaction: txn, table: table, read_results: results
+        end
+      end
+    end
+  end
+
+  def send_read link, **opts
+    link.send_message **opts
+  end
+end

data/lib/spinoza/calvin/scheduler.rb

@@ -0,0 +1,134 @@
+require 'spinoza/common'
+require 'spinoza/calvin/executor'
+require 'spinoza/calvin/readcaster'
+
+class Calvin::Scheduler
+  attr_reader :node
+
+  attr_reader :executors
+  attr_reader :idle_executors
+
+  # Maps { locally executing transaction => Executor }
+  attr_reader :ex_for_txn
+  
+  # Transactions to be executed, in order.
+  attr_reader :work_queue
+
+  def initialize node: raise, n_threads: 4
+    @node = node
+
+    @executors = n_threads.times.map {
+      Calvin::Executor.new(
+        store: node.store,
+        readcaster: Calvin::Readcaster.new(node: node))}
+
+    @idle_executors = @executors.dup
+    @ex_for_txn = {}
+    @work_queue = []
+    
+    node.meta_log.on_entry_available self, :handle_meta_log_entry
+  end
+
+  def inspect
+    "<#{self.class} on #{node.inspect}>"
+  end
+
+  def handle_meta_log_entry id: raise, node: raise, value: raise
+    batch_id = value
+    batch = node.read_batch(batch_id)
+    if batch
+      work_queue.concat batch
+      handle_next_transactions
+    else
+      # Log entry did not yet propagate to this node, even though MetaLog entry
+      # did propagate. Won't happen with default latency settings.
+      raise "TODO" ##
+    end
+  end
+
+  # Handle messages from peers. The only messages are the unidirectional
+  # broadcasts of read results.
+  def recv_peer_results transaction: raise, table: raise, read_results: raise
+    ex = ex_for_txn[transaction]
+    if ex
+      result = ex.recv_remote_reads table, read_results
+      if result
+        finish_transaction transaction, result
+        handle_next_transactions
+      end
+    else
+      ## TODO what if transaction hasn't started yet? Buffer? This won't
+      ## happen with our simplistic latency assumptions.
+      # The transaction has already finished locally, but another
+      # node is still sending out read results.
+    end
+  end
+
+  def handle_next_transactions
+    until work_queue.empty? or idle_executors.empty?
+      success = handle_next_transaction
+      break unless success
+    end
+  end
+  
+  def handle_next_transaction
+    ex = idle_executors.last
+    txn = work_queue.first
+    raise if ex_for_txn[txn]
+
+    lock_succeeded = try_lock(txn)
+    
+    if lock_succeeded
+      txn = work_queue.shift
+      result = ex.execute_transaction(txn)
+      if result
+        finish_transaction txn, result
+      else
+        idle_executors.pop
+        ex_for_txn[txn] = ex
+      end
+
+    else
+      node.lock_manager.unlock_all txn
+      # nothing to do until some executor finishes its current transaction
+      ## TODO optimization: attempt to reorder another txn to the head
+      ## of the work_queue where lock sets are disjoint.
+    end
+
+    lock_succeeded
+  end
+
+  def try_lock txn
+    lm = node.lock_manager
+    rset = txn.read_set
+    wset = txn.write_set
+
+    # get write locks first, so r/w on same key doesn't fail
+    wset.each do |table, keys|
+      keys.each do |key|
+        next if key == Spinoza::Transaction::INSERT_KEY
+        lm.lock_write [table, key], txn
+      end
+    end
+
+    rset.each do |table, keys|
+      keys.each do |key|
+        lm.lock_read [table, key], txn
+      end
+    end
+
+    true
+
+  rescue Spinoza::LockManager::ConcurrencyError
+    false
+  end
+
+  def finish_transaction transaction, result
+    ex = ex_for_txn.delete(transaction)
+    if ex
+      idle_executors.push ex
+    end
+    node.lock_manager.unlock_all transaction
+    node.finished_transaction transaction, result
+  end
+end

data/lib/spinoza/calvin/sequencer.rb

@@ -0,0 +1,74 @@
+require 'spinoza/system/model'
+
+# Accepts transaction requests from clients. The requests accepted in an epoch
+# are grouped as a batch, given a sequential id, and replicated to the
+# transaction schedulers on each node.
+class Calvin::Sequencer < Spinoza::Model
+  attr_reader :node
+
+  # ID used to construct UUID for batch.
+  attr_reader :id
+  
+  # Length of epoch in seconds.
+  attr_reader :dt_epoch
+
+  @seq_id = 0
+  class << self
+    def next_id
+      @seq_id += 1
+    end
+  end
+
+  def initialize node: raise, dt_epoch: 0.010
+    super timeline: node.timeline
+
+    @node = node
+    @dt_epoch = dt_epoch
+    @batch = []
+    @epoch = 0
+    @id = self.class.next_id
+
+    step_epoch
+  end
+  
+  def inspect
+    "<#{self.class} on #{node.inspect}>"
+  end
+
+  def step_epoch
+    unless @batch.empty?
+      batch_id = [@id, @epoch] # globally unique, but not ordered
+      log.write batch_id, @batch, node: node
+
+      log.when_durable batch_id,
+        actor: self,
+        action: :append_batch_to_meta_log,
+        batch_id: batch_id
+  
+      @batch = []
+    end
+    @epoch += 1
+
+    timeline.schedule Spinoza::Event[
+      time: time_now + dt_epoch,
+      actor: self,
+      action: :step_epoch
+    ]
+  end
+  
+  def append_batch_to_meta_log batch_id: batch_id
+    meta_log.append batch_id, node: node
+  end
+  
+  def log
+    node.log
+  end
+
+  def meta_log
+    node.meta_log
+  end
+
+  def accept_transaction txn
+    @batch << txn
+  end
+end