eventmachine 1.0.0.beta.3 → 1.0.0.beta.4

data/lib/em/deferrable.rb

@@ -25,6 +25,7 @@
 
 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.
@@ -49,6 +50,7 @@ module EventMachine
         @callbacks ||= []
         @callbacks.unshift block # << block
       end
+      self
     end
 
     # Cancels an outstanding callback to &block if any. Undoes the action of #callback.
@@ -74,6 +76,7 @@ module EventMachine
         @errbacks ||= []
         @errbacks.unshift block # << block
       end
+      self
     end
 
     # Cancels an outstanding errback to &block if any. Undoes the action of #errback.
@@ -168,6 +171,7 @@ module EventMachine
       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.

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

@@ -1,15 +1,24 @@
 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.
+  # 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
-    # :stopdoc:
+    # @private
     Cmodified = 'modified'.freeze
+    # @private
     Cdeleted = 'deleted'.freeze
+    # @private
     Cmoved = 'moved'.freeze
-    # :startdoc:
 
-    def receive_data(data) #:nodoc:
+
+    # @private
+    def receive_data(data)
       case data
       when Cmodified
         file_modified
@@ -20,35 +29,45 @@ module EventMachine
       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.
+    # 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
 
-    # Should be redefined with the user's custom callback that will be fired when the file is modified.
+    # Will be called when the file is modified. Supposed to be redefined by subclasses.
+    #
+    # @abstract
     def file_modified
     end
 
-    # Should be redefined with the user's custom callback that will be fired when the file is deleted.
+    # 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 that on linux (with inotify), file_deleted will not be called until all open file descriptors to
-    # the file have been closed.
+    # @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
 
-    # Should be redefined with the user's custom callback that will be fired when the file is moved or renamed.
+    # 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 unbind.
+    #
+    # 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
-  end
-
-end
+    end # stop_watching
+  end # FileWatch
+end # EventMachine

data/lib/em/iterator.rb

@@ -4,46 +4,46 @@ module EventMachine
   # 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| }
+  #   (0..10).each{ |num| }
   #
   # becomes:
   #
-  #  EM::Iterator.new(0..10).each{ |num,iter| iter.next }
+  #   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| ... }
+  #   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!'
+  #   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!'
-  #  })
+  #   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
+  #   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)
+    #   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
@@ -70,17 +70,17 @@ module EventMachine
 
     # 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
+    #   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' }
-    #  )
+    #   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
@@ -136,13 +136,13 @@ module EventMachine
 
     # 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
-    #  })
+    #   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
@@ -174,14 +174,14 @@ module EventMachine
 
     # 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
-    #  })
+    #   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|

data/lib/em/pool.rb

@@ -0,0 +1,146 @@
+module EventMachine
+  # = EventMachine::Pool
+  #
+  # A simple async resource pool based on a resource and work queue. Resources
+  # are enqueued and work waits for resources to become available.
+  #
+  # Example:
+  #
+  #    EM.run do
+  #      pool  = EM::Pool.new
+  #      spawn = lambda { pool.add EM::HttpRequest.new('http://example.org') }
+  #      10.times { spawn[] }
+  #      done, scheduled = 0, 0
+  #    
+  #      check = lambda do
+  #        done += 1
+  #        if done >= scheduled
+  #          EM.stop
+  #        end
+  #      end
+  #    
+  #      pool.on_error { |conn| spawn[] }
+  #    
+  #      100.times do
+  #        pool.perform do |conn|
+  #          req = conn.get :path => '/', :keepalive => true
+  #    
+  #          req.callback do
+  #            p [:success, conn.object_id, i, req.response.size]
+  #            check[]
+  #          end
+  #    
+  #          req.errback { check[] }
+  #    
+  #          req
+  #        end
+  #      end
+  #    end
+  #
+  # Resources are expected to be controlled by an object responding to a
+  # deferrable/completion style API with callback and errback blocks.
+  #
+  class Pool
+
+    def initialize
+      @resources = EM::Queue.new
+      @removed = []
+      @contents = []
+      @on_error = nil
+    end
+
+    def add resource
+      @contents << resource
+      requeue resource
+    end
+
+    def remove resource
+      @contents.delete resource
+      @removed << resource
+    end
+
+    # Returns a list for introspection purposes only. You should *NEVER* call
+    # modification or work oriented methods on objects in this list. A good
+    # example use case is periodic statistics collection against a set of
+    # connection resources.
+    #
+    # For example: 
+    #     pool.contents.inject(0) { |sum, connection| connection.num_bytes }
+    def contents
+      @contents.dup
+    end
+
+    # Define a default catch-all for when the deferrables returned by work
+    # blocks enter a failed state. By default all that happens is that the
+    # resource is returned to the pool. If on_error is defined, this block is
+    # responsible for re-adding the resource to the pool if it is still usable.
+    # In other words, it is generally assumed that on_error blocks explicitly
+    # handle the rest of the lifetime of the resource.
+    def on_error *a, &b
+      @on_error = EM::Callback(*a, &b)
+    end
+
+    # Perform a given #call-able object or block. The callable object will be
+    # called with a resource from the pool as soon as one is available, and is
+    # expected to return a deferrable.
+    # 
+    # The deferrable will have callback and errback added such that when the
+    # deferrable enters a finished state, the object is returned to the pool.
+    #
+    # If on_error is defined, then objects are not automatically returned to the
+    # pool.
+    def perform(*a, &b)
+      work = EM::Callback(*a, &b)
+
+      @resources.pop do |resource|
+        if removed? resource
+          @removed.delete resource
+          reschedule work
+        else
+          process work, resource
+        end
+      end
+    end
+    alias reschedule perform
+
+    # A peek at the number of enqueued jobs waiting for resources
+    def num_waiting
+      @resources.num_waiting
+    end
+
+    # Removed will show resources in a partial pruned state. Resources in the
+    # removed list may not appear in the contents list if they are currently in
+    # use.
+    def removed? resource
+      @removed.include? resource
+    end
+
+    protected
+    def requeue resource
+      @resources.push resource
+    end
+
+    def failure resource
+      if @on_error
+        @on_error.call resource
+      else
+        requeue resource
+      end
+    end
+
+    def completion deferrable, resource
+      deferrable.callback { requeue resource }
+      deferrable.errback  { failure resource }
+    end
+
+    def process work, resource
+      deferrable = work.call resource
+      if deferrable.kind_of?(EM::Deferrable)
+        completion deferrable, resource
+      else
+        raise ArgumentError, "deferrable expected from work"
+      end
+    end
+
+  end
+end

data/lib/em/process_watch.rb

@@ -3,12 +3,13 @@ module EventMachine
   # This is subclassed from EventMachine::Connection for use with the process monitoring API. Read the
   # documentation on the instance methods of this class, and for a full explanation see EventMachine.watch_process.
   class ProcessWatch < Connection
-    # :stopdoc:
+    # @private
     Cfork = 'fork'.freeze
+    # @private
     Cexit = 'exit'.freeze
-    # :startdoc:
 
-    def receive_data(data) # :nodoc:
+    # @private
+    def receive_data(data)
       case data
       when Cfork
         process_forked
@@ -41,4 +42,4 @@ module EventMachine
     end
   end
 
-end
+end

data/lib/em/processes.rb

@@ -39,7 +39,8 @@ module EventMachine
   class DeferrableChildProcess < EventMachine::Connection
     include EventMachine::Deferrable
 
-    def initialize # :nodoc:
+    # @private
+    def initialize
       super
       @data = []
     end
@@ -60,16 +61,19 @@ module EventMachine
       EventMachine.popen( cmd, DeferrableChildProcess )
     end
 
-    def receive_data data # :nodoc:
+    # @private
+    def receive_data data
       @data << data
     end
 
-    def unbind # :nodoc:
+    # @private
+    def unbind
       succeed( @data.join )
     end
   end
 
-  class SystemCmd < EventMachine::Connection # :nodoc:
+  # @private
+  class SystemCmd < EventMachine::Connection
     def initialize cb
       @cb = cb
       @output = []