agent 0.1.0 → 0.9.0

data/examples/agent-workers.rb

@@ -0,0 +1,51 @@
+project_lib_path = File.expand_path(File.join(File.dirname(__FILE__), "..", "lib"))
+$LOAD_PATH.unshift(project_lib_path)
+require 'agent'
+
+# First, we declare a new Ruby struct, which will encapsulate several arguments, and then
+# declare a clientRequests channel, which will carry our Request struct. Nothing unusual,
+# except that we also set the size of our channel to two – we’ll see why in a
+# second.
+
+Request = Struct.new(:args, :resultChan)
+clientRequests = channel!(Request, 2)
+
+# Now, we create a new worker block, which takes in a “reqs” object, calls receive on it
+# (hint, req’s is a Channel!), sleeps for a bit, and then sends back a timestamped
+# result. With the help of some Ruby syntax sugar, we then start two workers by passing
+# this block to our go function.
+
+worker = Proc.new do |reqs|
+  loop do
+    req = reqs.receive[0]
+    sleep 1.0
+    req.resultChan << [Time.now, req.args + 1].join(' : ')
+  end
+end
+
+# start two workers
+go!(clientRequests, &worker)
+go!(clientRequests, &worker)
+
+# The rest is simple, we create two distinct requests, which carry a number and a reply
+# channel, and pass them to our clientRequests pipe, on which our workers are waiting.
+# Once dispatched, we simply call receive and wait for the results!
+
+req1 = Request.new(1, channel!(String))
+req2 = Request.new(2, channel!(String))
+
+clientRequests << req1
+clientRequests << req2
+
+# retrieve results
+puts req1.resultChan.receive[0]  # => 2010-11-28 23:31:08 -0500 : 2
+puts req2.resultChan.receive[0]  # => 2010-11-28 23:31:08 -0500 : 3
+
+# Notice something interesting? Both results came back with the same timestamp! Our
+# clientRequests channel allowed for up to two messages in the pipe, which our workers
+# immediately received, executed, and returned the results.  Once again, not a thread
+# or a mutex in sight.
+
+clientRequests.close
+req1.resultChan.close
+req2.resultChan.close

data/examples/producer-consumer.rb

@@ -0,0 +1,15 @@
+project_lib_path = File.expand_path(File.join(File.dirname(__FILE__), "..", "lib"))
+$LOAD_PATH.unshift(project_lib_path)
+require 'agent'
+
+c = channel!(Integer)
+
+go!(c) do |c|
+  i = 0
+  loop { c << i+= 1 }
+end
+
+p c.receive[0] # => 1
+p c.receive[0] # => 2
+
+c.close

data/lib/agent.rb

@@ -1,15 +1 @@
-require 'agent/channel'
-require 'agent/transport/queue'
-
-module Kernel
-  def go(*args, &blk)
-    Thread.new do
-      begin
-        blk.call(*args)
-      rescue Exception => e
-        p e
-        p e.backtrace
-      end
-    end
-  end
-end
+require "agent/all"

data/lib/agent/all.rb

@@ -0,0 +1,22 @@
+require "thread"
+
+require "agent/version"
+require "agent/errors"
+require "agent/error"
+require "agent/once"
+require "agent/blocking_once"
+require "agent/pop"
+require "agent/push"
+require "agent/notifier"
+require "agent/uuid"
+require "agent/wait_group"
+require "agent/go"
+require "agent/queues"
+require "agent/queue"
+require "agent/queue/buffered"
+require "agent/queue/unbuffered"
+require "agent/channel"
+require "agent/selector"
+require "agent/kernel/channel"
+require "agent/kernel/go"
+require "agent/kernel/select"

data/lib/agent/blocking_once.rb

@@ -0,0 +1,26 @@
+require "agent/errors"
+
+module Agent
+  class BlockingOnce < Once
+    def perform
+      @mutex.synchronize do
+        return nil, error if @performed
+
+        begin
+          value      = yield
+          @performed = true
+          return value, nil
+        rescue Errors::Rollback
+          return nil, rollback_error
+        end
+      end
+    end
+
+  protected
+
+    def rollback_error
+      @rollback_error ||= Error.new("rolled back")
+    end
+
+  end
+end

data/lib/agent/channel.rb

@@ -1,74 +1,121 @@
-# Channels combine communication—the exchange of a value—with synchronization—guaranteeing
-# that two calculations (goroutines) are in a known state.
-# - http://golang.org/doc/effective_go.html#channels
+require "agent/uuid"
+require "agent/push"
+require "agent/pop"
+require "agent/queues"
+require "agent/errors"
 
 module Agent
+  def self.channel!(*args)
+    Channel.new(*args)
+  end
+
   class Channel
-    attr_reader :name, :transport, :chan
+    attr_reader :name, :direction, :type, :max
+
+    def initialize(*args)
+      opts         = args.last.is_a?(Hash) ? args.pop : {}
+      @type        = args.shift
+      @max         = args.shift  || 0
+      @closed      = false
+      @name        = opts[:name] || UUID.generate
+      @direction   = opts[:direction] || :bidirectional
+      @close_mutex = Mutex.new
+      @queue       = Queues.register(@name, @type, @max)
+    end
 
-    def initialize(opts = {})
-      @state      = :active
-      @name       = opts[:name]
-      @max        = opts[:size] || 1
-      @type       = opts[:type]
-      @direction  = opts[:direction] || :bidirectional
-      @transport  = opts[:transport] || Agent::Transport::Queue
+    def queue
+      q = @queue
+      raise Errors::ChannelClosed unless q
+      q
+    end
 
-      raise NoName  if @name.nil?
-      raise Untyped if @type.nil?
 
-      @chan = @transport.new(@name, @max)
-    end
+    # Serialization methods
 
     def marshal_load(ary)
-      @state, @name, @type, @direction, @transport = *ary
-      @chan = @transport.new(@name)
+      @closed, @name, @max, @type, @direction = *ary
+      @queue = Queues[@name]
+      @closed = @queue.nil? || @queue.closed?
       self
     end
 
     def marshal_dump
-      [@state, @name, @type, @direction, @transport]
+      [@closed, @name, @max, @type, @direction]
     end
 
-    def send(msg)
-      check_direction(:send)
-      check_type(msg)
 
-      @chan.send(Marshal.dump(msg))
+    # Sending methods
+
+    def send(object, options={})
+      check_direction(:send)
+      queue.push(object, options)
     end
     alias :push :send
     alias :<<   :send
 
-    def receive
-      check_direction(:receive)
+    def push?; queue.push?; end
+    alias :send? :push?
+
 
-      msg = Marshal.load(@chan.receive)
-      check_type(msg)
+    # Receiving methods
 
-      msg
+    def receive(options={})
+      check_direction(:receive)
+      queue.pop(options)
     end
     alias :pop  :receive
 
-    def closed?; @state == :closed; end
+    def pop?; queue.pop?; end
+    alias :receive? :pop?
+
+
+    # Closing methods
+
     def close
-      @chan.close
-      @state = :closed
+      @close_mutex.synchronize do
+        raise Errors::ChannelClosed if @closed
+        @closed = true
+        @queue.close
+        @queue = nil
+        Queues.delete(@name)
+      end
+    end
+    def closed?; @closed; end
+    def open?;   !@closed;   end
+
+    def remove_operations(operations)
+      # ugly, but it overcomes the race condition without synchronization
+      # since instance variable access is atomic.
+      q = @queue
+      q.remove_operations(operations) if q
     end
 
-    private
+    def as_send_only
+      as_direction_only(:send)
+    end
+
+    def as_receive_only
+      as_direction_only(:receive)
+    end
 
-      def check_type(msg)
-        raise InvalidType if !msg.is_a? @type
-      end
 
-      def check_direction(direction)
-        return if @direction == :bidirectional
-        raise InvalidDirection if @direction != direction
+  private
+
+    def as_direction_only(direction)
+      @close_mutex.synchronize do
+        raise Errors::ChannelClosed if @closed
+        channel!(@type, @max, :name => @name, :direction => direction)
       end
+    end
+
+    def check_type(object)
+      raise Errors::InvalidType unless object.is_a?(@type)
+    end
+
+    def check_direction(direction)
+      return if @direction == :bidirectional
+      raise Errors::InvalidDirection if @direction != direction
+    end
 
-      class InvalidDirection < Exception; end
-      class NoName < Exception; end
-      class Untyped < Exception; end
-      class InvalidType < Exception; end
   end
 end

data/lib/agent/error.rb

@@ -0,0 +1,15 @@
+module Agent
+  class Error
+    def initialize(message)
+      @message = message
+    end
+
+    def to_s
+      @message
+    end
+
+    def message?(message)
+      @message == message
+    end
+  end
+end

data/lib/agent/errors.rb

@@ -0,0 +1,14 @@
+module Agent
+  module Errors
+    class BlockMissing < Exception; end
+    class ChannelClosed < Exception; end
+    class InvalidDirection < Exception; end
+    class Untyped < Exception; end
+    class InvalidType < Exception; end
+    class Rollback < Exception; end
+    class InvalidQueueSize < Exception; end
+    class NotImplementedError < Exception; end
+    class DefaultCaseAlreadyDefinedError < Exception; end
+    class NegativeWaitGroupCount < Exception; end
+  end
+end

data/lib/agent/go.rb

@@ -0,0 +1,9 @@
+require "thread"
+require "agent/errors"
+
+module Agent
+  def self.go!(*args)
+    raise Errors::BlockMissing unless block_given?
+    Thread.new(*args){|*a| yield(*a) }
+  end
+end

data/lib/agent/kernel/channel.rb

@@ -0,0 +1,7 @@
+require "agent/channel"
+
+module Kernel
+  def channel!(*args)
+    Agent.channel!(*args)
+  end
+end

data/lib/agent/kernel/go.rb

@@ -0,0 +1,7 @@
+require "agent/go"
+
+module Kernel
+  def go!(*args, &blk)
+    Agent.go!(*args, &blk)
+  end
+end

data/lib/agent/kernel/select.rb

@@ -0,0 +1,7 @@
+require "agent/selector"
+
+module Kernel
+  def select!(&blk)
+    Agent.select!(&blk)
+  end
+end

data/lib/agent/notifier.rb

@@ -0,0 +1,34 @@
+module Agent
+  class Notifier
+    attr_reader :payload
+
+    def initialize
+      @mutex    = Mutex.new
+      @cvar     = ConditionVariable.new
+      @notified = false
+      @payload  = nil
+    end
+
+    def notified?
+      @notified
+    end
+
+    def wait
+      @mutex.synchronize do
+        until notified?
+          @cvar.wait(@mutex)
+        end
+      end
+    end
+
+    def notify(payload)
+      @mutex.synchronize do
+        return Error.new("already notified") if notified?
+        @payload  = payload
+        @notified = true
+        @cvar.signal
+        return nil
+      end
+    end
+  end
+end

data/lib/agent/once.rb

@@ -0,0 +1,32 @@
+module Agent
+  class Once
+    def initialize
+      @mutex     = Mutex.new
+      @performed = false
+    end
+
+    def perform
+      # optimium path
+      return nil, error if @performed
+
+      # slow path
+      @mutex.synchronize do
+        return nil, error if @performed
+        @performed = true
+      end
+
+      return yield, nil
+    end
+
+    def performed?
+      @performed
+    end
+
+  protected
+
+    def error
+      @error ||= Error.new("already performed")
+    end
+
+  end
+end

data/lib/agent/pop.rb

@@ -0,0 +1,70 @@
+require "agent/errors"
+
+module Agent
+  class Pop
+    attr_reader :uuid, :blocking_once, :notifier, :object
+
+    def initialize(options={})
+      @object        = nil
+      @uuid          = options[:uuid] || UUID.generate
+      @blocking_once = options[:blocking_once]
+      @notifier      = options[:notifier]
+      @mutex         = Mutex.new
+      @cvar          = ConditionVariable.new
+      @received      = false
+      @closed        = false
+    end
+
+    def received?
+      @received
+    end
+
+    def closed?
+      @closed
+    end
+
+    def wait
+      @mutex.synchronize do
+        until @received || @closed
+          @cvar.wait(@mutex)
+        end
+        return received?
+      end
+    end
+
+    def send
+      @mutex.synchronize do
+        raise Errors::ChannelClosed if @closed
+
+        if @blocking_once
+          value, error = @blocking_once.perform do
+            @object = Marshal.load(yield)
+            @received = true
+            @cvar.signal
+            @notifier.notify(self) if @notifier
+          end
+
+          return error
+        else
+          begin
+            @object = Marshal.load(yield)
+            @received = true
+            @cvar.signal
+            @notifier.notify(self) if @notifier
+          rescue Errors::Rollback
+          end
+        end
+      end
+    end
+
+    def close
+      @mutex.synchronize do
+        return if @received
+        @closed = true
+        @cvar.broadcast
+        @notifier.notify(self) if @notifier
+      end
+    end
+
+  end
+end