MattHulse-eventmachine 0.0.1

data/lib/em/deferrable.rb

@@ -0,0 +1,187 @@
+#--
+#
+# 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
+      if @deferred_status == :succeeded
+        block.call(*@deferred_args)
+      elsif @deferred_status != :failed
+        @callbacks ||= []
+        @callbacks.unshift block # << block
+      end
+    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
+      if @deferred_status == :failed
+        block.call(*@deferred_args)
+      elsif @deferred_status != :succeeded
+        @errbacks ||= []
+        @errbacks.unshift block # << block
+      end
+    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
+      @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
+      cancel_timeout
+      me = self
+      @deferred_timeout = EventMachine::Timer.new(seconds) {me.fail}
+    end
+
+    # Cancels an outstanding timeout if any. Undoes the action of #timeout.
+    #
+    def cancel_timeout
+      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/messages.rb

@@ -0,0 +1,66 @@
+#--
+#
+# 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.
+#
+#---------------------------------------------------------------------------
+#
+# 
+
+=begin
+
+Message Routing in EventMachine.
+
+The goal here is to enable "routing points," objects that can send and receive
+"messages," which are delimited streams of bytes. The boundaries of a message
+are preserved as it passes through the reactor system.
+
+There will be several module methods defined in EventMachine to create route-point
+objects (which will probably have a base class of EventMachine::MessageRouter
+until someone suggests a better name).
+
+As with I/O objects, routing objects will receive events by having the router
+core call methods on them. And of course user code can and will define handlers
+to deal with events of interest.
+
+The message router base class only really needs a receive_message method. There will
+be an EM module-method to send messages, in addition to the module methods to create
+the various kinds of message receivers.
+
+The simplest kind of message receiver object can receive messages by being named 
+explicitly in a parameter to EM#send_message. More sophisticated receivers can define
+pub-sub selectors and message-queue names. And they can also define channels for
+route-points in other processes or even on other machines.
+
+A message is NOT a marshallable entity. Rather, it's a chunk of flat content more like
+an Erlang message. Initially, all content submitted for transmission as a message will
+have the to_s method called on it. Eventually, we'll be able to transmit certain structured
+data types (XML and YAML documents, Structs within limits) and have them reconstructed
+on the other end.
+
+A fundamental goal of the message-routing capability is to interoperate seamlessly with
+external systems, including non-Ruby systems like ActiveMQ. We will define various protocol
+handlers for things like Stomp and possibly AMQP, but these will be wrapped up and hidden
+from the users of the basic routing capability.
+
+As with Erlang, a critical goal is for programs that are built to use message-passing to work
+WITHOUT CHANGE when the code is re-based on a multi-process system.
+
+=end
+

data/lib/em/process_watch.rb

@@ -0,0 +1,44 @@
+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:
+    Cfork = 'fork'.freeze
+    Cexit = 'exit'.freeze
+    # :startdoc:
+
+    def receive_data(data) # :nodoc:
+      case data
+      when Cfork
+        process_forked
+      when Cexit
+        process_exited
+      end
+    end
+
+    # Returns the pid that EventMachine::watch_process was originally called with.
+    def pid
+      @pid
+    end
+
+    # Should be redefined with the user's custom callback that will be fired when the prcess is forked.
+    #
+    # There is currently not an easy way to get the pid of the forked child.
+    def process_forked
+    end
+
+    # Should be redefined with the user's custom callback that will be fired when the process exits.
+    #
+    # stop_watching is called automatically after this callback
+    def process_exited
+    end
+
+    # Discontinue monitoring of the process.
+    # This will be called automatically when a process dies. User code may call it as well.
+    def stop_watching
+      EventMachine::unwatch_pid(@signature)
+    end
+  end
+
+end

data/lib/em/processes.rb

@@ -0,0 +1,119 @@
+#--
+#
+# Author:: Francis Cianfrocca (gmail: blackhedd)
+# Homepage::  http://rubyeventmachine.com
+# Date:: 13 Dec 07
+# 
+# See EventMachine and EventMachine::Connection for documentation and
+# usage examples.
+#
+#----------------------------------------------------------------------------
+#
+# Copyright (C) 2006-08 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
+
+  # EM::DeferrableChildProcess is a sugaring of a common use-case
+  # involving EM::popen.
+  # Call the #open method on EM::DeferrableChildProcess, passing
+  # a command-string. #open immediately returns an EM::Deferrable
+  # object. It also schedules the forking of a child process, which
+  # will execute the command passed to #open.
+  # When the forked child terminates, the Deferrable will be signalled
+  # and execute its callbacks, passing the data that the child process
+  # wrote to stdout.
+  #
+  class DeferrableChildProcess < EventMachine::Connection
+    include EventMachine::Deferrable
+
+    def initialize # :nodoc:
+      super
+      @data = []
+    end
+
+    # Sugars a common use-case involving forked child processes.
+    # #open takes a String argument containing an shell command
+    # string (including arguments if desired). #open immediately
+    # returns an EventMachine::Deferrable object, without blocking.
+    #
+    # It also invokes EventMachine#popen to run the passed-in
+    # command in a forked child process.
+    #
+    # When the forked child terminates, the Deferrable that
+    # #open calls its callbacks, passing the data returned
+    # from the child process.
+    #
+    def self.open cmd
+      EventMachine.popen( cmd, DeferrableChildProcess )
+    end
+
+    def receive_data data # :nodoc:
+      @data << data
+    end
+
+    def unbind # :nodoc:
+      succeed( @data.join )
+    end
+  end
+
+  class SystemCmd < EventMachine::Connection # :nodoc:
+    def initialize cb
+      @cb = cb
+      @output = []
+    end
+    def receive_data data
+      @output << data
+    end
+    def unbind
+      @cb.call @output.join(''), get_status if @cb
+    end
+  end
+
+  # EM::system is a simple wrapper for EM::popen. It is similar to Kernel::system, but requires a
+  # single string argument for the command and performs no shell expansion.
+  #
+  # The block or proc passed to EM::system is called with two arguments: the output generated by the command,
+  # and a Process::Status that contains information about the command's execution.
+  #
+  #  EM.run{
+  #    EM.system('ls'){ |output,status| puts output if status.exitstatus == 0 }
+  #  }
+  #
+  # You can also supply an additional proc to send some data to the process:
+  #
+  #  EM.run{
+  #    EM.system('sh', proc{ |process|
+  #      process.send_data("echo hello\n")
+  #      process.send_data("exit\n")
+  #    }, proc{ |out,status|
+  #      puts(out)
+  #    })
+  #  }
+  #
+  # Like EventMachine.popen, EventMachine.system currently does not work on windows.
+  # It returns the pid of the spawned process.
+  def EventMachine::system cmd, *args, &cb
+    cb ||= args.pop if args.last.is_a? Proc
+    init = args.pop if args.last.is_a? Proc
+
+    # merge remaining arguments into the command
+    cmd = ([cmd] + args.map{|a|a.to_s.dump}).join(' ')
+
+    EM.get_subprocess_pid(EM.popen(cmd, SystemCmd, cb) do |c|
+      init[c] if init
+    end.signature)
+  end
+end