eventmachine 1.2.0.dev.2-x64-mingw32

data/lib/em/deferrable.rb

@@ -0,0 +1,210 @@
+#--
+#
+# 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
+    autoload :Pool, 'em/deferrable/pool'
+
+    # 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
+      self
+    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
+      self
+    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)}
+      self
+    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/deferrable/pool.rb

@@ -0,0 +1,2 @@
+warn "EM::Deferrable::Pool is deprecated, please use EM::Pool"
+EM::Deferrable::Pool = EM::Pool

data/lib/em/file_watch.rb

@@ -0,0 +1,73 @@
+module EventMachine
+  # Utility class that is useful for file monitoring. Supported events are
+  #
+  # * File is modified
+  # * File is deleted
+  # * File is moved
+  #
+  # @note On Mac OS X, file watching only works when kqueue is enabled
+  #
+  # @see EventMachine.watch_file
+  class FileWatch < Connection
+    # @private
+    Cmodified = 'modified'.freeze
+    # @private
+    Cdeleted = 'deleted'.freeze
+    # @private
+    Cmoved = 'moved'.freeze
+
+
+    # @private
+    def receive_data(data)
+      case data
+      when Cmodified
+        file_modified
+      when Cdeleted
+        file_deleted
+      when Cmoved
+        file_moved
+      end
+    end
+
+    # Returns the path that is being monitored.
+    #
+    # @note Current implementation does not pick up on the new filename after a rename occurs.
+    #
+    # @return [String]
+    # @see EventMachine.watch_file
+    def path
+      @path
+    end
+
+    # Will be called when the file is modified. Supposed to be redefined by subclasses.
+    #
+    # @abstract
+    def file_modified
+    end
+
+    # Will be called when the file is deleted. Supposed to be redefined by subclasses.
+    # When the file is deleted, stop_watching will be called after this to make sure everything is
+    # cleaned up correctly.
+    #
+    # @note On Linux (with {http://en.wikipedia.org/wiki/Inotify inotify}), this method will not be called until *all* open file descriptors to
+    #       the file have been closed.
+    #
+    # @abstract
+    def file_deleted
+    end
+
+    # Will be called when the file is moved or renamed. Supposed to be redefined by subclasses.
+    #
+    # @abstract
+    def file_moved
+    end
+
+    # Discontinue monitoring of the file.
+    #
+    # This involves cleaning up the underlying monitoring details with kqueue/inotify, and in turn firing {EventMachine::Connection#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 # stop_watching
+  end # FileWatch
+end # EventMachine

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,252 @@
+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
+    Stop = "EM::Stop"
+    # 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
+    #
+    # The list may either be an array-like object, or a proc that returns a new object
+    # to be processed each time it is called.  If a proc is used, it must return
+    # EventMachine::Iterator::Stop to signal the end of the iterations.
+    #
+    def initialize(list, concurrency = 1)
+      raise ArgumentError, 'concurrency must be bigger than zero' unless (concurrency > 0)
+      if list.respond_to?(:call)
+        @list = nil
+        @list_proc = list
+      elsif list.respond_to?(:to_a)
+        @list = list.to_a.dup
+        @list_proc = nil
+      else
+        raise ArgumentError, 'argument must be a proc or an array'
+      end
+      @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
+          item = next_item()
+          if item.equal?(Stop)
+            @ended = true
+            @workers -= 1
+            all_done.call
+          else
+            @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
+
+    # Return the next item from @list or @list_proc.
+    # Once items have run out, will return EM::Iterator::Stop.  Procs must supply this themselves
+    def next_item
+      if @list_proc
+        @list_proc.call
+      else
+        @list.empty? ? Stop : @list.shift
+      end
+    end
+  end
+end
+
+# 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