eventmachine 1.0.0.beta.2-x86-mingw32

data/lib/em/deferrable.rb

@@ -0,0 +1,206 @@
+#--
+#
+# Author:: Francis Cianfrocca (gmail: blackhedd)
+# Homepage::  http://rubyeventmachine.com
+# Date:: 16 Jul 2006
+# 
+# See EventMachine and EventMachine::Connection for documentation and
+# usage examples.
+#
+#----------------------------------------------------------------------------
+#
+# Copyright (C) 2006-07 by Francis Cianfrocca. All Rights Reserved.
+# Gmail: blackhedd
+# 
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of either: 1) the GNU General Public License
+# as published by the Free Software Foundation; either version 2 of the
+# License, or (at your option) any later version; or 2) Ruby's License.
+# 
+# See the file COPYING for complete licensing information.
+#
+#---------------------------------------------------------------------------
+#
+# 
+
+module EventMachine
+  module Deferrable
+
+    # Specify a block to be executed if and when the Deferrable object receives
+    # a status of :succeeded. See #set_deferred_status for more information.
+    #
+    # Calling this method on a Deferrable object whose status is not yet known
+    # will cause the callback block to be stored on an internal list.
+    # If you call this method on a Deferrable whose status is :succeeded, the
+    # block will be executed immediately, receiving the parameters given to the
+    # prior #set_deferred_status call.
+    #
+    #--
+    # If there is no status, add a callback to an internal list.
+    # If status is succeeded, execute the callback immediately.
+    # If status is failed, do nothing.
+    #
+    def callback &block
+      return unless block
+      @deferred_status ||= :unknown
+      if @deferred_status == :succeeded
+        block.call(*@deferred_args)
+      elsif @deferred_status != :failed
+        @callbacks ||= []
+        @callbacks.unshift block # << block
+      end
+    end
+
+    # Cancels an outstanding callback to &block if any. Undoes the action of #callback.
+    #
+    def cancel_callback block
+      @callbacks ||= []
+      @callbacks.delete block
+    end
+
+    # Specify a block to be executed if and when the Deferrable object receives
+    # a status of :failed. See #set_deferred_status for more information.
+    #--
+    # If there is no status, add an errback to an internal list.
+    # If status is failed, execute the errback immediately.
+    # If status is succeeded, do nothing.
+    #
+    def errback &block
+      return unless block
+      @deferred_status ||= :unknown
+      if @deferred_status == :failed
+        block.call(*@deferred_args)
+      elsif @deferred_status != :succeeded
+        @errbacks ||= []
+        @errbacks.unshift block # << block
+      end
+    end
+
+    # Cancels an outstanding errback to &block if any. Undoes the action of #errback.
+    #
+    def cancel_errback block
+      @errbacks ||= []
+      @errbacks.delete block
+    end
+
+    # Sets the "disposition" (status) of the Deferrable object. See also the large set of
+    # sugarings for this method.
+    # Note that if you call this method without arguments,
+    # no arguments will be passed to the callback/errback.
+    # If the user has coded these with arguments, then the
+    # user code will throw an argument exception.
+    # Implementors of deferrable classes <b>must</b>
+    # document the arguments they will supply to user callbacks.
+    #
+    # OBSERVE SOMETHING VERY SPECIAL here: you may call this method even
+    # on the INSIDE of a callback. This is very useful when a previously-registered
+    # callback wants to change the parameters that will be passed to subsequently-registered
+    # ones.
+    #
+    # You may give either :succeeded or :failed as the status argument.
+    #
+    # If you pass :succeeded, then all of the blocks passed to the object using the #callback
+    # method (if any) will be executed BEFORE the #set_deferred_status method returns. All of the blocks
+    # passed to the object using #errback will be discarded.
+    #
+    # If you pass :failed, then all of the blocks passed to the object using the #errback
+    # method (if any) will be executed BEFORE the #set_deferred_status method returns. All of the blocks
+    # passed to the object using # callback will be discarded.
+    #
+    # If you pass any arguments to #set_deferred_status in addition to the status argument,
+    # they will be passed as arguments to any callbacks or errbacks that are executed.
+    # It's your responsibility to ensure that the argument lists specified in your callbacks and
+    # errbacks match the arguments given in calls to #set_deferred_status, otherwise Ruby will raise
+    # an ArgumentError.
+    #
+    #--
+    # We're shifting callbacks off and discarding them as we execute them.
+    # This is valid because by definition callbacks are executed no more than
+    # once. It also has the magic effect of permitting recursive calls, which
+    # means that a callback can call #set_deferred_status and change the parameters
+    # that will be sent to subsequent callbacks down the chain.
+    #
+    # Changed @callbacks and @errbacks from push/shift to unshift/pop, per suggestion
+    # by Kirk Haines, to work around the memory leak bug that still exists in many Ruby
+    # versions.
+    #
+    # Changed 15Sep07: after processing callbacks or errbacks, CLEAR the other set of
+    # handlers. This gets us a little closer to the behavior of Twisted's "deferred,"
+    # which only allows status to be set once. Prior to making this change, it was possible
+    # to "succeed" a Deferrable (triggering its callbacks), and then immediately "fail" it,
+    # triggering its errbacks! That is clearly undesirable, but it's just as undesirable
+    # to raise an exception is status is set more than once on a Deferrable. The latter
+    # behavior would invalidate the idiom of resetting arguments by setting status from
+    # within a callback or errback, but more seriously it would cause spurious errors
+    # if a Deferrable was timed out and then an attempt was made to succeed it. See the
+    # comments under the new method #timeout.
+    #
+    def set_deferred_status status, *args
+      cancel_timeout
+      @errbacks ||= nil
+      @callbacks ||= nil
+      @deferred_status = status
+      @deferred_args = args
+      case @deferred_status
+      when :succeeded
+        if @callbacks
+          while cb = @callbacks.pop
+            cb.call(*@deferred_args)
+          end
+        end
+        @errbacks.clear if @errbacks
+      when :failed
+        if @errbacks
+          while eb = @errbacks.pop
+            eb.call(*@deferred_args)
+          end
+        end
+        @callbacks.clear if @callbacks
+      end
+    end
+
+
+    # Setting a timeout on a Deferrable causes it to go into the failed state after
+    # the Timeout expires (passing no arguments to the object's errbacks).
+    # Setting the status at any time prior to a call to the expiration of the timeout
+    # will cause the timer to be cancelled.
+    def timeout seconds, *args
+      cancel_timeout
+      me = self
+      @deferred_timeout = EventMachine::Timer.new(seconds) {me.fail(*args)}
+    end
+
+    # Cancels an outstanding timeout if any. Undoes the action of #timeout.
+    #
+    def cancel_timeout
+      @deferred_timeout ||= nil
+      if @deferred_timeout
+        @deferred_timeout.cancel
+        @deferred_timeout = nil
+      end
+    end
+
+
+    # Sugar for set_deferred_status(:succeeded, ...)
+    #
+    def succeed *args
+      set_deferred_status :succeeded, *args
+    end
+    alias set_deferred_success succeed
+
+    # Sugar for set_deferred_status(:failed, ...)
+    #
+    def fail *args
+      set_deferred_status :failed, *args
+    end
+    alias set_deferred_failure fail
+  end
+
+
+  # DefaultDeferrable is an otherwise empty class that includes Deferrable.
+  # This is very useful when you just need to return a Deferrable object
+  # as a way of communicating deferred status to some other part of a program.
+  class DefaultDeferrable
+    include Deferrable
+  end
+end

data/lib/em/file_watch.rb

@@ -0,0 +1,54 @@
+module EventMachine
+
+  # This is subclassed from EventMachine::Connection for use with the file monitoring API. Read the
+  # documentation on the instance methods of this class, and for a full explanation see EventMachine.watch_file.
+  class FileWatch < Connection
+    # :stopdoc:
+    Cmodified = 'modified'.freeze
+    Cdeleted = 'deleted'.freeze
+    Cmoved = 'moved'.freeze
+    # :startdoc:
+
+    def receive_data(data) #:nodoc:
+      case data
+      when Cmodified
+        file_modified
+      when Cdeleted
+        file_deleted
+      when Cmoved
+        file_moved
+      end
+    end
+
+    # Returns the path that EventMachine::watch_file was originally called with. The current implementation
+    # does not pick up on the new filename after a rename occurs.
+    def path
+      @path
+    end
+
+    # Should be redefined with the user's custom callback that will be fired when the file is modified.
+    def file_modified
+    end
+
+    # Should be redefined with the user's custom callback that will be fired when the file is deleted.
+    # When the file is deleted, stop_watching will be called after this to make sure everything is
+    # cleaned up correctly.
+    #
+    # Note that on linux (with inotify), file_deleted will not be called until all open file descriptors to
+    # the file have been closed.
+    def file_deleted
+    end
+
+    # Should be redefined with the user's custom callback that will be fired when the file is moved or renamed.
+    def file_moved
+    end
+
+    # Discontinue monitoring of the file.
+    # This involves cleaning up the underlying monitoring details with kqueue/inotify, and in turn firing unbind.
+    # This will be called automatically when a file is deleted. User code may call it as well.
+    def stop_watching
+      EventMachine::unwatch_filename(@signature)
+    end
+  end
+
+end

data/lib/em/future.rb

@@ -0,0 +1,61 @@
+#--
+#
+# Author:: Francis Cianfrocca (gmail: blackhedd)
+# Homepage::  http://rubyeventmachine.com
+# Date:: 16 Jul 2006
+# 
+# See EventMachine and EventMachine::Connection for documentation and
+# usage examples.
+#
+#----------------------------------------------------------------------------
+#
+# Copyright (C) 2006-07 by Francis Cianfrocca. All Rights Reserved.
+# Gmail: blackhedd
+# 
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of either: 1) the GNU General Public License
+# as published by the Free Software Foundation; either version 2 of the
+# License, or (at your option) any later version; or 2) Ruby's License.
+# 
+# See the file COPYING for complete licensing information.
+#
+#---------------------------------------------------------------------------
+#
+# 
+
+#--
+# This defines EventMachine::Deferrable#future, which requires
+# that the rest of EventMachine::Deferrable has already been seen.
+# (It's in deferrable.rb.)
+
+module EventMachine
+    module Deferrable
+
+      # A future is a sugaring of a typical deferrable usage.
+      #--
+      # Evaluate arg (which may be an expression or a block).
+      # What's the class of arg?
+      # If arg is an ordinary expression, then return it.
+      # If arg is deferrable (responds to :set_deferred_status),
+      # then look at the arguments. If either callback or errback
+      # are defined, then use them. If neither are defined, then
+      # use the supplied block (if any) as the callback.
+      # Then return arg.
+      def self.future arg, cb=nil, eb=nil, &blk
+        arg = arg.call if arg.respond_to?(:call)
+
+        if arg.respond_to?(:set_deferred_status)
+          if cb || eb
+            arg.callback(&cb) if cb
+            arg.errback(&eb) if eb
+          else
+            arg.callback(&blk) if blk
+          end
+        end
+
+        arg
+      end
+
+    end
+end
+

data/lib/em/iterator.rb

@@ -0,0 +1,270 @@
+module EventMachine
+  # A simple iterator for concurrent asynchronous work.
+  #
+  # Unlike ruby's built-in iterators, the end of the current iteration cycle is signaled manually,
+  # instead of happening automatically after the yielded block finishes executing. For example:
+  #
+  #  (0..10).each{ |num| }
+  #
+  # becomes:
+  #
+  #  EM::Iterator.new(0..10).each{ |num,iter| iter.next }
+  #
+  # This is especially useful when doing asynchronous work via reactor libraries and
+  # functions. For example, given a sync and async http api:
+  #
+  #  response = sync_http_get(url); ...
+  #  async_http_get(url){ |response| ... }
+  #
+  # a synchronous iterator such as:
+  #
+  #  responses = urls.map{ |url| sync_http_get(url) }
+  #  ...
+  #  puts 'all done!'
+  #
+  # could be written as:
+  #
+  #  EM::Iterator.new(urls).map(proc{ |url,iter|
+  #    async_http_get(url){ |res|
+  #      iter.return(res)
+  #    }
+  #  }, proc{ |responses|
+  #    ...
+  #    puts 'all done!'
+  #  })
+  #
+  # Now, you can take advantage of the asynchronous api to issue requests in parallel. For example,
+  # to fetch 10 urls at a time, simply pass in a concurrency of 10:
+  #
+  #  EM::Iterator.new(urls, 10).each do |url,iter|
+  #    async_http_get(url){ iter.next }
+  #  end
+  #
+  class Iterator
+    # Create a new parallel async iterator with specified concurrency.
+    #
+    #  i = EM::Iterator.new(1..100, 10)
+    #
+    # will create an iterator over the range that processes 10 items at a time. Iteration
+    # is started via #each, #map or #inject
+    #
+    def initialize(list, concurrency = 1)
+      raise ArgumentError, 'argument must be an array' unless list.respond_to?(:to_a)
+      @list = list.to_a.dup
+      @concurrency = concurrency
+
+      @started = false
+      @ended = false
+    end
+
+    # Change the concurrency of this iterator. Workers will automatically be spawned or destroyed
+    # to accomodate the new concurrency level.
+    #
+    def concurrency=(val)
+      old = @concurrency
+      @concurrency = val
+
+      spawn_workers if val > old and @started and !@ended
+    end
+    attr_reader :concurrency
+
+    # Iterate over a set of items using the specified block or proc.
+    #
+    #  EM::Iterator.new(1..100).each do |num, iter|
+    #    puts num
+    #    iter.next
+    #  end
+    #
+    # An optional second proc is invoked after the iteration is complete.
+    #
+    #  EM::Iterator.new(1..100).each(
+    #    proc{ |num,iter| iter.next },
+    #    proc{ puts 'all done' }
+    #  )
+    #
+    def each(foreach=nil, after=nil, &blk)
+      raise ArgumentError, 'proc or block required for iteration' unless foreach ||= blk
+      raise RuntimeError, 'cannot iterate over an iterator more than once' if @started or @ended
+
+      @started = true
+      @pending = 0
+      @workers = 0
+
+      all_done = proc{
+        after.call if after and @ended and @pending == 0
+      }
+
+      @process_next = proc{
+        # p [:process_next, :pending=, @pending, :workers=, @workers, :ended=, @ended, :concurrency=, @concurrency, :list=, @list]
+        unless @ended or @workers > @concurrency
+          if @list.empty?
+            @ended = true
+            @workers -= 1
+            all_done.call
+          else
+            item = @list.shift
+            @pending += 1
+
+            is_done = false
+            on_done = proc{
+              raise RuntimeError, 'already completed this iteration' if is_done
+              is_done = true
+
+              @pending -= 1
+
+              if @ended
+                all_done.call
+              else
+                EM.next_tick(@process_next)
+              end
+            }
+            class << on_done
+              alias :next :call
+            end
+
+            foreach.call(item, on_done)
+          end
+        else
+          @workers -= 1
+        end
+      }
+
+      spawn_workers
+
+      self
+    end
+
+    # Collect the results of an asynchronous iteration into an array.
+    #
+    #  EM::Iterator.new(%w[ pwd uptime uname date ], 2).map(proc{ |cmd,iter|
+    #    EM.system(cmd){ |output,status|
+    #      iter.return(output)
+    #    }
+    #  }, proc{ |results|
+    #    p results
+    #  })
+    #
+    def map(foreach, after)
+      index = 0
+
+      inject([], proc{ |results,item,iter|
+        i = index
+        index += 1
+
+        is_done = false
+        on_done = proc{ |res|
+          raise RuntimeError, 'already returned a value for this iteration' if is_done
+          is_done = true
+
+          results[i] = res
+          iter.return(results)
+        }
+        class << on_done
+          alias :return :call
+          def next
+            raise NoMethodError, 'must call #return on a map iterator'
+          end
+        end
+
+        foreach.call(item, on_done)
+      }, proc{ |results|
+        after.call(results)
+      })
+    end
+
+    # Inject the results of an asynchronous iteration onto a given object.
+    #
+    #  EM::Iterator.new(%w[ pwd uptime uname date ], 2).inject({}, proc{ |hash,cmd,iter|
+    #    EM.system(cmd){ |output,status|
+    #      hash[cmd] = status.exitstatus == 0 ? output.strip : nil
+    #      iter.return(hash)
+    #    }
+    #  }, proc{ |results|
+    #    p results
+    #  })
+    #
+    def inject(obj, foreach, after)
+      each(proc{ |item,iter|
+        is_done = false
+        on_done = proc{ |res|
+          raise RuntimeError, 'already returned a value for this iteration' if is_done
+          is_done = true
+
+          obj = res
+          iter.next
+        }
+        class << on_done
+          alias :return :call
+          def next
+            raise NoMethodError, 'must call #return on an inject iterator'
+          end
+        end
+
+        foreach.call(obj, item, on_done)
+      }, proc{
+        after.call(obj)
+      })
+    end
+
+    private
+
+    # Spawn workers to consume items from the iterator's enumerator based on the current concurrency level.
+    #
+    def spawn_workers
+      EM.next_tick(start_worker = proc{
+        if @workers < @concurrency and !@ended
+          # p [:spawning_worker, :workers=, @workers, :concurrency=, @concurrency, :ended=, @ended]
+          @workers += 1
+          @process_next.call
+          EM.next_tick(start_worker)
+        end
+      })
+      nil
+    end
+  end
+end
+
+if __FILE__ == $0
+  $:.unshift File.join(File.dirname(__FILE__), '..')
+  require 'eventmachine'
+
+  # TODO: real tests
+  # TODO: pass in one object instead of two? .each{ |iter| puts iter.current; iter.next }
+  # TODO: support iter.pause/resume/stop/break/continue?
+  # TODO: create some exceptions instead of using RuntimeError
+  # TODO: support proc instead of enumerable? EM::Iterator.new(proc{ return queue.pop })
+
+  EM.run{
+    EM::Iterator.new(1..50).each{ |num,iter| p num; iter.next }
+    EM::Iterator.new([1,2,3], 10).each{ |num,iter| p num; iter.next }
+
+    i = EM::Iterator.new(1..100, 5)
+    i.each(proc{|num,iter|
+      p num.to_s
+      iter.next
+    }, proc{
+      p :done
+    })
+    EM.add_timer(0.03){
+      i.concurrency = 1
+    }
+    EM.add_timer(0.04){
+      i.concurrency = 3
+    }
+
+    EM::Iterator.new(100..150).map(proc{ |num,iter|
+      EM.add_timer(0.01){ iter.return(num) }
+    }, proc{ |results|
+      p results
+    })
+
+    EM::Iterator.new(%w[ pwd uptime uname date ], 2).inject({}, proc{ |hash,cmd,iter|
+      EM.system(cmd){ |output,status|
+        hash[cmd] = status.exitstatus == 0 ? output.strip : nil
+        iter.return(hash)
+      }
+    }, proc{ |results|
+      p results
+    })
+  }
+end