tupelo 0.1

data/example/balance-xfer-locking.rb

@@ -0,0 +1,50 @@
+require 'tupelo/app'
+
+Tupelo.application do |app|
+  app.child do |client|
+    client.write(
+      {name: "alice", balance: 1000},
+      {name: "bob", balance: 200}
+    )
+    10.times do |i|
+      alice = client.take(name: "alice", balance: Numeric)
+      client.log alice
+      alice = alice.dup
+      alice["balance"] -= 10
+      client.write_wait alice
+      sleep 0.1
+    end
+    
+    client.log client.read_all(name: /^(?:alice|bob)$/, balance: nil)
+  end
+  
+  app.child do |client|
+    sleep 0.3
+
+    src = client.take(name: "alice", balance: Numeric)
+    dst = client.take(name: "bob", balance: Numeric)
+
+    if src["balance"] < 500
+      abort "insufficient funds -- not attempting transfer"
+    end
+
+    sleep 0.3
+      # Even though we are outside of transaction, the delay doesn't matter,
+      # since this process possesses the tuples. So there is no failure.
+      # However, this has some disadvantages compared to the transaction
+      # implementation in the other examples: it's not atomic, tuples might
+      # be lost if the client exits, and more network hops (latency).
+    
+    src = src.dup
+    dst = dst.dup
+
+    src["balance"] -= 500
+    dst["balance"] += 500
+
+    w = client.write src, dst
+    client.log "attempting to set #{[src, dst]}"
+
+    w.wait
+    client.log client.read_all(name: /^(?:alice|bob)$/, balance: nil)
+  end
+end

data/example/balance-xfer-retry.rb

@@ -0,0 +1,55 @@
+require 'tupelo/app'
+
+Tupelo.application do |app|
+  app.child do |client|
+    client.write(
+      {name: "alice", balance: 1000},
+      {name: "bob", balance: 200}
+    )
+    10.times do |i|
+      alice = client.take(name: "alice", balance: Numeric)
+      client.log alice
+      alice = alice.dup
+      alice["balance"] -= 10
+      client.write_wait alice
+      sleep 0.1
+    end
+    
+    client.log client.read_all(name: /^(?:alice|bob)$/, balance: nil)
+  end
+  
+  app.child do |client|
+    client.transaction do |t|
+      src = t.take(name: "alice", balance: Numeric)
+      dst = t.take(name: "bob", balance: Numeric)
+
+      if src["balance"] < 500
+        abort "insufficient funds -- not attempting transfer"
+      end
+
+      src = src.dup
+      dst = dst.dup
+
+      src["balance"] -= 500
+      dst["balance"] += 500
+      
+      sleep 0.3
+        # force fail -- the tuples this client is trying to take
+        # will be gone when it wakes up
+      
+      client.log "attempting to set #{[src, dst]}"
+      t.write src, dst
+
+      if false # enable this to see how failures are retried
+        begin
+          t.commit.wait
+        rescue => ex
+          client.log "retrying after #{ex}"
+          raise
+        end
+      end
+    end
+    
+    client.log client.read_all(name: /^(?:alice|bob)$/, balance: nil)
+  end
+end

data/example/balance-xfer.rb

@@ -0,0 +1,33 @@
+require 'tupelo/app'
+
+Tupelo.application do |app|
+  app.child do |client|
+    client.write(
+      {name: "alice", balance: 1000},
+      {name: "bob", balance: 200}
+    )
+  end
+  
+  app.child do |client|
+    client.transaction do |t|
+      src = t.take(name: "alice", balance: Numeric)
+      dst = t.take(name: "bob", balance: Numeric)
+
+      if src["balance"] < 500
+        abort "insufficient funds -- not attempting transfer"
+      end
+
+      src = src.dup
+      dst = dst.dup
+
+      src["balance"] -= 500
+      dst["balance"] += 500
+
+      t.write src, dst
+    end
+    # transaction will block if balances have changed since the read.
+    # see balance-xfer-retry.rb
+    
+    client.log client.read_all(name: /^(?:alice|bob)$/, balance: nil)
+  end
+end

data/example/boolean-match.rb

@@ -0,0 +1,32 @@
+require 'tupelo/app'
+
+class Tupelo::Client
+  class Or
+    attr_reader :templates
+
+    def initialize worker, templates
+      @templates = templates.map {|template| worker.make_template(template)}
+    end
+
+    def === obj
+      templates.any? {|template| template === obj}
+    end
+  end
+  
+  def or *templates
+    Or.new(worker, templates)
+  end
+end
+
+Tupelo.application do |app|
+  app.local do |client|
+    tm = client.or [0..2, String], [3..5, Hash]
+    
+    client.write(
+      [0, "a"], [1, {b: 0}], [2, "c"],
+      [3, "a"], [4, {b: 0}], [5, "c"]
+    ).wait
+
+    client.log client.read_all tm
+  end
+end

data/example/bounded-retry.rb

@@ -0,0 +1,35 @@
+require 'tupelo/app'
+
+N = 2
+K = 1
+
+Tupelo.application do |app|
+  (N+K).times do
+    app.child do |client|
+      catch :gave_up do
+        tries = 0
+
+        r = client.take [Integer] do |val|
+          tries += 1
+          if tries >= N
+            client.log "giving up on #{val}"
+            throw :gave_up
+          end
+          client.log "trying to take #{val}"
+        end
+
+        client.log "took #{r.inspect}"
+      end
+    end
+  end
+  
+  sleep 0.01
+
+  app.child do |client|
+    N.times do |i|
+      client.write [i]
+      client.log "wrote #{[i]}"
+      sleep 0.1
+    end
+  end
+end

data/example/broker-locking.rb

@@ -0,0 +1,43 @@
+# Clients attempt to pair up, using a distributed broker algorithm and a lock
+# tuple.
+
+require 'tupelo/app'
+
+N_PLAYERS = 10
+
+token = ["token"] # only the holder of the token can arrange games
+
+Tupelo.application do |app|
+  app.local do |client|
+    client.write token
+  end
+  
+  N_PLAYERS.times do
+    app.child do |client|
+      me = client.client_id
+
+      client.take token # bottleneck and fragile until 'client.write token'
+      other_player = client.read_nowait(name: nil)
+        # sleep 1 # program takes ~N_PLAYERS sec to finish
+
+      if other_player
+        client.take other_player
+        client.write(
+          player1: me,
+          player2: other_player["name"])
+        client.write token
+        you = other_player["name"]
+
+      else
+        client.write(name: me)
+        client.write token
+        game = client.read(
+          player1: nil,
+          player2: me)
+        you = game["player1"]
+      end
+
+      client.log "now playing with #{you}"
+    end
+  end
+end

data/example/broker-optimistic-async.rb

@@ -0,0 +1,33 @@
+require 'tupelo/app'
+
+N_PLAYERS = 10
+
+Tupelo.application do |app|
+  N_PLAYERS.times do
+    app.child do |client|
+      me = client.client_id
+      opponent = nil
+      client.write name: me
+      
+      arranging_game = client.transaction
+      arranging_game.async do |t|
+        t.take name: me
+        opponent = t.take name: nil
+        t.write(
+          player1: me,
+          player2: opponent)
+      end
+
+      Thread.new do
+        game = client.read(
+          player1: nil,
+          player2: me)
+        opponent = game["player1"]
+      end
+
+      wait
+      client.log "now playing with #{opponent}"
+      joining_game.cancel
+    end
+  end
+end

data/example/broker-optimistic.rb

@@ -0,0 +1,41 @@
+# The local control flow in this example is more complex than in
+# broker-locking.rb, but it has far fewer bottlenecks (try inserting some sleep
+# 1 calls), and it is not possible for a token to be lost (leaving the lock in a
+# locked state) if a process dies.
+
+require 'tupelo/app'
+
+N_PLAYERS = 10
+
+Tupelo.application do |app|
+  N_PLAYERS.times do
+    app.child do |client|
+      me = client.client_id
+      client.write name: me
+      you = nil
+      
+      1.times do
+        begin
+          t = client.transaction
+          if t.take_nowait name: me
+            you = t.take(name: nil)["name"]
+            t.write(
+              player1: me,
+              player2: you)
+            t.commit.wait
+            break
+          end
+        rescue Tupelo::Client::TransactionFailure => ex
+        end
+          
+        game = client.read_nowait(
+          player1: nil,
+          player2: me)
+        redo unless game
+        you = game["player1"]
+      end
+
+      client.log "now playing with #{you}"
+    end
+  end
+end

data/example/broker-queue.rb

@@ -0,0 +1,2 @@
+# more like how you would do it in redis, except that the queue is not stored in
+# the central server, so operations on it are not a bottleneck, FWIW

data/example/cancel.rb

@@ -0,0 +1,17 @@
+require 'tupelo/app'
+
+Tupelo.application do |app|
+  app.child do |client|
+    ats = (0..4).map do |i|
+      client.transaction.async do |t|
+        t.take ["start"]
+        t.write [i]
+      end
+    end
+    
+    [0,1,2,4].each {|i| ats[i].cancel}
+
+    client.write ["start"]
+    p client.take [Integer]
+  end
+end

data/example/concurrent-transactions.rb

@@ -0,0 +1,39 @@
+require 'tupelo/app'
+
+N = 100
+
+Tupelo.application do |app|
+  app.child do |client|
+    client.write [0, 0]
+
+    t1 = Thread.new do
+      N.times do
+        client.transaction do |t|
+          t.take ["reader ready"]
+          x, y = t.take [nil, nil]
+          t.write [x+1, y]
+          t.write ["data ready"]
+        end
+      end
+    end
+    
+    t2 = Thread.new do
+      N.times do
+        client.transaction do |t|
+          t.take ["reader ready"]
+          x, y = t.take [nil, nil]
+          t.write [x, y+1]
+          t.write ["data ready"]
+        end
+      end
+    end
+    
+    loop do
+      client.write ["reader ready"]
+      client.take ["data ready"]
+      x, y = client.read [nil, nil]
+      client.log "%3d %3d" % [x, y]
+      break if x == N and y == N
+    end
+  end
+end

data/example/custom-class.rb

@@ -0,0 +1,29 @@
+class Foo
+  attr_accessor :x
+
+  # This method is necessary for #take to work correctly.
+  def == other
+    other.class == Foo and other.x == x
+  end
+end
+
+require 'tupelo/app'
+
+# Must use marshal or yaml -- msgpack and json do not support custom classes.
+Tupelo.application blob_type: 'marshal' do |app|
+  app.child do |client|
+    f = Foo.new; f.x = 3
+    p f
+
+    client.write [f]
+
+    p client.read [nil]
+    p client.read [Foo]
+    p client.read [f]
+
+    p client.take [Foo]
+
+    client.write [f]
+    p client.take [f]
+  end  
+end

data/example/custom-search.rb

@@ -0,0 +1,27 @@
+require 'tupelo/app'
+
+class MyClient < Tupelo::Client
+  # A custom search method. Note this is not the same as using a custom
+  # data structure for the tuplespace, which can be much more efficient than
+  # the default linear search.
+  def read_all_diagonal val, &bl
+    diag_matcher = proc {|t| t.all? {|v| v == val} }
+      # Note that Proc#===(t) calls the proc on t. It's convenient, but not
+      # essential to this example. We could also define a custom class with any
+      # implementation of #===.
+
+    read_all diag_matcher, &bl
+  end
+end
+
+Tupelo.application do |app|
+  app.local MyClient do |client|
+    client.write [41, 42, 43]
+    client.write [42, 42, 42]
+    client.write [42, 42]
+    client.write_wait [42] # make sure all writes up to this one have completed
+
+    client.log client.read_all [nil, nil, nil]
+    client.log client.read_all_diagonal 42
+  end
+end

data/example/fail-and-retry.rb

@@ -0,0 +1,29 @@
+require 'tupelo/app'
+
+Tupelo.application do |app|
+  2.times do
+    app.child do |client|
+      begin
+        # the block is re-executed for the client that fails to take [1]
+        # this is also true in the transaction do...end construct.
+        t = client.transaction
+        r = t.take [Integer]
+        client.log "trying to take #{r.inspect}"
+        t.commit.wait
+        client.log "took #{r.inspect}"
+      rescue Tupelo::Client::TransactionFailure => ex
+        client.log "#{ex} -- retrying"
+        retry
+        # manually emulate the effect of transaction do...end
+      end
+    end
+  end
+  
+  app.child do |client|
+    client.write [1]
+    client.log "wrote #{[1]}"
+    sleep 0.1
+    client.write [2]
+    client.log "wrote #{[2]}"
+  end
+end

data/example/hash-tuples.rb

@@ -0,0 +1,53 @@
+# Tuples can be sets of key-value pairs, rather than arrays.
+#
+# Caution:
+#
+# - when blob_type is json, (by using the --json switch, or by passing
+#   blob_type: 'json' to #application), the keys of these hashes must be
+#   strings. That's just a JSON thing.
+#
+# - ruby has some syntax quirks:
+#
+#   - these are the same
+#        write foo: 1, bar: 2
+#        write({foo: 1, bar: 2})
+#     but this is a syntax error:
+#        write {foo: 1, bar: 2}
+#
+#   - {x: 1} is short for {:x => 1}, rather than {"x" => 1}
+#
+#     tupelo kind of hides this issue: you can use {x: 1} as a template
+#     to match tuples like {"x" => 1}. And you can write tuples using
+#     either notation. However, the tuple will still behave like this:
+#
+#       write x: 1
+#       t = take x: nil
+#       t["x"] == 1 # ==> true
+#       t[:x] == 1  # ==> false
+#
+#     In future API, it might be possible to access values like this:
+#
+#       t.x == 1    # ==> true
+#
+# - matching ops succeed only if the key sets are equal, so
+#   you have to read or take using a template that has the same keys as the
+#   target tuple -- see below.
+
+require 'tupelo/app'
+
+Tupelo.application do |app|
+  app.child do |client|
+    client.write x: 1, y: 2
+  end
+  
+  app.child do |client|
+    t = client.take x: Numeric, y: Numeric
+    client.write x: t["x"], y: t["y"], sum: t["x"] + t["y"]
+    client.log "sum result: #{client.read x: nil, y: nil, sum: nil}"
+    
+    # N.B.: these are all empty, for the reason given above.
+    client.log client.read_all x: nil
+    client.log client.read_all y: nil
+    client.log client.read_all x: nil, y: nil, z: nil
+  end
+end

data/example/increment.rb

@@ -0,0 +1,21 @@
+require 'tupelo/app'
+
+N = 5
+
+Tupelo.application do |app|
+  N.times do |i|
+    app.child do |client|
+      client.transaction do |t|
+        n, s = t.take [Numeric, String]
+        #sleep rand # No race conditions here!
+        t.write [n + 1, s + "\n  incremented by client #{i}"]
+      end
+    end
+  end
+
+  app.child do |client|
+    client.write [0, "started with 0"]
+    n, s = client.take [N, String]
+    puts s, "result is #{n}"
+  end
+end

data/example/lock-mgr-with-queue.rb

@@ -0,0 +1,75 @@
+# This is like lock-mgr.rb, but by using a queue, we avoid the thundering herd
+# problem. You can observe this by seeing "FAILED" in the output of the former
+# but not in the latter. This means that competing offers are resolved by the
+# queue, rather than by propagating them to all clients.
+
+require 'tupelo/app'
+
+N = 3
+
+Tupelo.application do |app|
+  app.child do |client| # a debugger client, to see what's happening
+    note = client.notifier
+    puts "%4s %4s %10s %s" % %w{ tick cid status operation }
+    loop do
+      status, tick, cid, op = note.wait
+      unless status == :attempt
+        s = status == :failure ? "FAILED" : ""
+        puts "%4d %4d %10s %p" % [tick, cid, s, op]
+      end
+    end
+  end
+  
+  app.child do |client| # the lock manager
+    client.log.progname << " (lock mgr)"
+    waiters = Queue.new
+
+    Thread.new do
+      loop do
+        _, _, client_id, duration =
+          client.take ["request", "resource", nil, nil]
+        waiters << [client_id, duration]
+      end
+    end
+
+    loop do
+      client_id, duration = waiters.pop
+      client.write ["resource", client_id, duration]
+      begin
+        client.take ["done", "resource", client_id], timeout: duration
+      rescue TimeoutError
+        client.log "forcing client #{client_id} to stop using resource."
+      end
+      client.take ["resource", client_id, duration]
+    end
+    # exercise for reader: make this work with 2 or more resources
+    # exercise: rewrite this with hash tuples instead of array tuples
+  end
+  
+  N.times do |i|
+    app.child do |client|
+      client.write ["request", "resource", client.client_id, 0.5]
+      
+      10.times do |j|
+        # Now we are ouside of transaction, but still no other client may use
+        # "resource" until lock expires (or is otherwise removed), as long
+        # as all clients follow the read protocol below.
+        sleep 0.2
+
+        client.transaction do |t|
+          t.read ["resource", client.client_id, nil]
+          t.write ["c#{client.client_id}##{j}"]
+        end
+      end
+    end
+  end
+  
+  app.child do |client|
+    # This client never even tries to lock the resource, so it cannot write.
+    client.transaction do |t|
+      t.read ["resource", client.client_id, nil]
+      t.write ["c#{client.client_id}##{j}"]
+    end
+    client.log.error "should never get here"
+  end
+end

data/example/lock-mgr.rb

@@ -0,0 +1,62 @@
+require 'tupelo/app'
+
+N = 3
+
+Tupelo.application do |app|
+  app.child do |client| # a debugger client, to see what's happening
+    note = client.notifier
+    puts "%4s %4s %10s %s" % %w{ tick cid status operation }
+    loop do
+      status, tick, cid, op = note.wait
+      unless status == :attempt
+        s = status == :failure ? "FAILED" : ""
+        puts "%4d %4d %10s %p" % [tick, cid, s, op]
+      end
+    end
+  end
+  
+  app.child do |client| # the lock manager
+    loop do
+      client.write ["resource", "none"]
+      lock_id, client_id, duration = client.read ["resource", nil, nil]
+      sleep duration
+      client.take [lock_id, client_id, duration]
+        # optimization: combine take and write in a transaction, just to
+        # reduce delay
+    end
+    # exercise for reader: make this work with 2 or more resources
+    # exercise: rewrite this with hash tuples instead of array tuples
+  end
+  
+  N.times do |i|
+    app.child do |client|
+      client.transaction do |t|
+        t.take ["resource", "none"]
+        t.write ["resource", client.client_id, 0.5]
+      end
+      # Thundering herd -- all N clients can respond at the same time.
+      # A better example would have a queue -- see lock-mgr-with-queue.rb.
+      
+      10.times do |j|
+        # Now we are ouside of transaction, but still no other client may use
+        # "resource" until lock expires (or is otherwise removed), as long
+        # as all clients follow the read protocol below.
+        sleep 0.2
+
+        client.transaction do |t|
+          t.read ["resource", client.client_id, nil]
+          t.write ["c#{client.client_id}##{j}"]
+        end
+      end
+    end
+  end
+  
+  app.child do |client|
+    # This client never even tries to lock the resource, so it cannot write.
+    client.transaction do |t|
+      t.read ["resource", client.client_id, nil]
+      t.write ["c#{client.client_id}##{j}"]
+    end
+    client.log.error "should never get here"
+  end
+end