sonixlabs-eventmachine-java 1.0.0.rc.4-java

data/lib/em/buftok.rb

@@ -0,0 +1,110 @@
+# BufferedTokenizer takes a delimiter upon instantiation, or acts line-based
+# by default.  It allows input to be spoon-fed from some outside source which
+# receives arbitrary length datagrams which may-or-may-not contain the token
+# by which entities are delimited.
+#
+# By default, new BufferedTokenizers will operate on lines delimited by "\n" by default
+# or allow you to specify any delimiter token you so choose, which will then
+# be used by String#split to tokenize the input data
+#
+# @example Using BufferedTokernizer to parse lines out of incoming data
+#
+#   module LineBufferedConnection
+#     def receive_data(data)
+#       (@buffer ||= BufferedTokenizer.new).extract(data).each do |line|
+#         receive_line(line)
+#       end
+#     end
+#   end
+#
+# @author Tony Arcieri
+# @author Martin Emde
+class BufferedTokenizer
+  # @param [String] delimiter
+  # @param [Integer] size_limit
+  def initialize(delimiter = "\n", size_limit = nil)
+    @delimiter  = delimiter
+    @size_limit = size_limit
+
+    # The input buffer is stored as an array.  This is by far the most efficient
+    # approach given language constraints (in C a linked list would be a more
+    # appropriate data structure).  Segments of input data are stored in a list
+    # which is only joined when a token is reached, substantially reducing the
+    # number of objects required for the operation.
+    @input = []
+
+    # Size of the input buffer
+    @input_size = 0
+  end
+
+  # Extract takes an arbitrary string of input data and returns an array of
+  # tokenized entities, provided there were any available to extract.
+  #
+  # @example
+  #
+  #   tokenizer.extract(data).
+  #     map { |entity| Decode(entity) }.each { ... }
+  #
+  # @param [String] data
+  def extract(data)
+    # Extract token-delimited entities from the input string with the split command.
+    # There's a bit of craftiness here with the -1 parameter.  Normally split would
+    # behave no differently regardless of if the token lies at the very end of the
+    # input buffer or not (i.e. a literal edge case)  Specifying -1 forces split to
+    # return "" in this case, meaning that the last entry in the list represents a
+    # new segment of data where the token has not been encountered
+    entities = data.split @delimiter, -1
+
+    # Check to see if the buffer has exceeded capacity, if we're imposing a limit
+    if @size_limit
+      raise 'input buffer full' if @input_size + entities.first.size > @size_limit
+      @input_size += entities.first.size
+    end
+
+    # Move the first entry in the resulting array into the input buffer.  It represents
+    # the last segment of a token-delimited entity unless it's the only entry in the list.
+    @input << entities.shift
+
+    # If the resulting array from the split is empty, the token was not encountered
+    # (not even at the end of the buffer).  Since we've encountered no token-delimited
+    # entities this go-around, return an empty array.
+    return [] if entities.empty?
+
+    # At this point, we've hit a token, or potentially multiple tokens.  Now we can bring
+    # together all the data we've buffered from earlier calls without hitting a token,
+    # and add it to our list of discovered entities.
+    entities.unshift @input.join
+
+    # Now that we've hit a token, joined the input buffer and added it to the entities
+    # list, we can go ahead and clear the input buffer.  All of the segments that were
+    # stored before the join can now be garbage collected.
+    @input.clear
+
+    # The last entity in the list is not token delimited, however, thanks to the -1
+    # passed to split.  It represents the beginning of a new list of as-yet-untokenized
+    # data, so we add it to the start of the list.
+    @input << entities.pop
+
+    # Set the new input buffer size, provided we're keeping track
+    @input_size = @input.first.size if @size_limit
+
+    # Now we're left with the list of extracted token-delimited entities we wanted
+    # in the first place.  Hooray!
+    entities
+  end
+
+  # Flush the contents of the input buffer, i.e. return the input buffer even though
+  # a token has not yet been encountered.
+  #
+  # @return [String]
+  def flush
+    buffer = @input.join
+    @input.clear
+    buffer
+  end
+
+  # @return [Boolean]
+  def empty?
+    @input.empty?
+  end
+end

data/lib/em/callback.rb

@@ -0,0 +1,58 @@
+module EventMachine
+  # Utility method for coercing arguments to an object that responds to :call.
+  # Accepts an object and a method name to send to, or a block, or an object
+  # that responds to :call.
+  #
+  # @example EventMachine.Callback used with a block. Returns that block.
+  #
+  #  cb = EventMachine.Callback do |msg|
+  #    puts(msg)
+  #  end
+  #  # returned object is a callable
+  #  cb.call('hello world')
+  #
+  #
+  # @example EventMachine.Callback used with an object (to be more specific, class object) and a method name, returns an object that responds to #call
+  #
+  #  cb = EventMachine.Callback(Object, :puts)
+  #  # returned object is a callable that delegates to Kernel#puts (in this case Object.puts)
+  #  cb.call('hello world')
+  #
+  #
+  # @example EventMachine.Callback used with an object that responds to #call. Returns the argument.
+  #
+  #  cb = EventMachine.Callback(proc{ |msg| puts(msg) })
+  #  # returned object is a callable
+  #  cb.call('hello world')
+  #
+  #
+  # @overload Callback(object, method)
+  #   Wraps `method` invocation on `object` into an object that responds to #call that proxies all the arguments to that method
+  #   @param [Object] Object to invoke method on
+  #   @param [Symbol] Method name
+  #   @return [<#call>] An object that responds to #call that takes any number of arguments and invokes method on object with those arguments
+  #
+  # @overload Callback(object)
+  #   Returns callable object as is, without any coercion
+  #   @param [<#call>] An object that responds to #call
+  #   @return [<#call>] Its argument
+  #
+  # @overload Callback(&block)
+  #   Returns block passed to it without any coercion
+  #   @return [<#call>] Block passed to this method
+  #
+  # @raise [ArgumentError] When argument doesn't respond to #call, method name is missing or when invoked without arguments and block isn't given
+  #
+  # @return [<#call>]
+  def self.Callback(object = nil, method = nil, &blk)
+    if object && method
+      lambda { |*args| object.__send__ method, *args }
+    else
+      if object.respond_to? :call
+        object
+      else
+        blk || raise(ArgumentError)
+      end # if
+    end # if
+  end # self.Callback
+end # EventMachine

data/lib/em/channel.rb

@@ -0,0 +1,64 @@
+module EventMachine
+  # Provides a simple thread-safe way to transfer data between (typically) long running
+  # tasks in {EventMachine.defer} and event loop thread.
+  #
+  # @example
+  #
+  #  channel = EventMachine::Channel.new
+  #  sid     = channel.subscribe { |msg| p [:got, msg] }
+  #
+  #  channel.push('hello world')
+  #  channel.unsubscribe(sid)
+  #
+  #
+  class Channel
+    def initialize
+      @subs = {}
+      @uid  = 0
+    end
+
+    # Takes any arguments suitable for EM::Callback() and returns a subscriber
+    # id for use when unsubscribing.
+    #
+    # @return [Integer] Subscribe identifier
+    # @see #unsubscribe
+    def subscribe(*a, &b)
+      name = gen_id
+      EM.schedule { @subs[name] = EM::Callback(*a, &b) }
+
+      name
+    end
+
+    # Removes subscriber from the list.
+    #
+    # @param [Integer] Subscriber identifier
+    # @see #subscribe
+    def unsubscribe(name)
+      EM.schedule { @subs.delete name }
+    end
+
+    # Add items to the channel, which are pushed out to all subscribers.
+    def push(*items)
+      items = items.dup
+      EM.schedule { items.each { |i| @subs.values.each { |s| s.call i } } }
+    end
+    alias << push
+
+    # Fetches one message from the channel.
+    def pop(*a, &b)
+      EM.schedule {
+        name = subscribe do |*args|
+          unsubscribe(name)
+          EM::Callback(*a, &b).call(*args)
+        end
+      }
+    end
+
+    private
+
+    # @private
+    def gen_id
+      @uid += 1
+    end
+  end
+end

data/lib/em/completion.rb

@@ -0,0 +1,304 @@
+# = EM::Completion
+#
+# A completion is a callback container for various states of completion. In
+# it's most basic form it has a start state and a finish state.
+#
+# This implementation includes some hold-back from the EM::Deferrable
+# interface in order to be compatible - but it has a much cleaner
+# implementation.
+#
+# In general it is preferred that this implementation be used as a state
+# callback container than EM::DefaultDeferrable or other classes including
+# EM::Deferrable. This is because it is generally more sane to keep this level
+# of state in a dedicated state-back container. This generally leads to more
+# malleable interfaces and software designs, as well as eradicating nasty bugs
+# that result from abstraction leakage.
+#
+# == Basic Usage
+#
+# As already mentioned, the basic usage of a Completion is simply for its two
+# final states, :succeeded and :failed.
+#
+# An asynchronous operation will complete at some future point in time, and
+# users often want to react to this event. API authors will want to expose
+# some common interface to react to these events.
+#
+# In the following example, the user wants to know when a short lived
+# connection has completed its exchange with the remote server. The simple
+# protocol just waits for an ack to its message.
+#
+#    class Protocol < EM::Connection
+#      include EM::P::LineText2
+#
+#      def initialize(message, completion)
+#        @message, @completion = message, completion
+#        @completion.completion { close_connection }
+#        @completion.timeout(1, :timeout)
+#      end
+#
+#      def post_init
+#        send_data(@message)
+#      end
+#
+#      def receive_line(line)
+#        case line
+#        when /ACK/i
+#          @completion.succeed line
+#        when /ERR/i
+#          @completion.fail :error, line
+#        else
+#          @completion.fail :unknown, line
+#        end
+#      end
+#  
+#      def unbind
+#        @completion.fail :disconnected unless @completion.completed?
+#      end
+#    end
+#
+#    class API
+#      attr_reader :host, :port
+#
+#      def initialize(host = 'example.org', port = 8000)
+#        @host, @port = host, port
+#      end
+#
+#      def request(message)
+#        completion = EM::Deferrable::Completion.new
+#        EM.connect(host, port, Protocol, message, completion)
+#        completion
+#      end
+#    end
+#
+#    api = API.new
+#    completion = api.request('stuff')
+#    completion.callback do |line|
+#      puts "API responded with: #{line}"
+#    end
+#    completion.errback do |type, line|
+#      case type
+#      when :error
+#        puts "API error: #{line}"
+#      when :unknown
+#        puts "API returned unknown response: #{line}"
+#      when :disconnected
+#        puts "API server disconnected prematurely"
+#      when :timeout
+#        puts "API server did not respond in a timely fashion"
+#      end
+#    end
+#
+# == Advanced Usage
+#
+# This completion implementation also supports more state callbacks and
+# arbitrary states (unlike the original Deferrable API). This allows for basic
+# stateful process encapsulation. One might use this to setup state callbacks
+# for various states in an exchange like in the basic usage example, except
+# where the applicaiton could be made to react to "connected" and
+# "disconnected" states additionally.
+#
+#    class Protocol < EM::Connection
+#      def initialize(completion)
+#        @response = []
+#        @completion = completion
+#        @completion.stateback(:disconnected) do
+#          @completion.succeed @response.join
+#        end
+#      end
+#
+#      def connection_completed
+#        @host, @port = Socket.unpack_sockaddr_in get_peername
+#        @completion.change_state(:connected, @host, @port)
+#        send_data("GET http://example.org/ HTTP/1.0\r\n\r\n")
+#      end
+#
+#      def receive_data(data)
+#        @response << data
+#      end
+#
+#      def unbind
+#        @completion.change_state(:disconnected, @host, @port)
+#      end
+#    end
+#
+#    completion = EM::Deferrable::Completion.new
+#    completion.stateback(:connected) do |host, port|
+#      puts "Connected to #{host}:#{port}"
+#    end
+#    completion.stateback(:disconnected) do |host, port|
+#      puts "Disconnected from #{host}:#{port}"
+#    end
+#    completion.callback do |response|
+#      puts response
+#    end
+#
+#    EM.connect('example.org', 80, Protocol, completion)
+#
+# == Timeout
+#
+# The Completion also has a timeout. The timeout is global and is not aware of
+# states apart from completion states. The timeout is only engaged if #timeout
+# is called, and it will call fail if it is reached.
+#
+# == Completion states
+#
+# By default there are two completion states, :succeeded and :failed. These
+# states can be modified by subclassing and overrding the #completion_states
+# method. Completion states are special, in that callbacks for all completion
+# states are explcitly cleared when a completion state is entered. This
+# prevents errors that could arise from accidental unterminated timeouts, and
+# other such user errors.
+#
+# == Other notes
+#
+# Several APIs have been carried over from EM::Deferrable for compatibility
+# reasons during a transitionary period. Specifically cancel_errback and
+# cancel_callback are implemented, but their usage is to be strongly
+# discouraged. Due to the already complex nature of reaction systems, dynamic
+# callback deletion only makes the problem much worse. It is always better to
+# add correct conditionals to the callback code, or use more states, than to
+# address such implementaiton issues with conditional callbacks.
+
+module EventMachine
+
+  class Completion
+    # This is totally not used (re-implemented), it's here in case people check
+    # for kind_of?
+    include EventMachine::Deferrable
+
+    attr_reader :state, :value
+
+    def initialize
+      @state = :unknown
+      @callbacks = Hash.new { |h,k| h[k] = [] }
+      @value = []
+      @timeout_timer = nil
+    end
+
+    # Enter the :succeeded state, setting the result value if given.
+    def succeed(*args)
+      change_state(:succeeded, *args)
+    end
+    # The old EM method:
+    alias set_deferred_success succeed
+
+    # Enter the :failed state, setting the result value if given.
+    def fail(*args)
+      change_state(:failed, *args)
+    end
+    # The old EM method:
+    alias set_deferred_failure fail
+
+    # Statebacks are called when you enter (or are in) the named state.
+    def stateback(state, *a, &b)
+      # The following is quite unfortunate special casing for :completed
+      # statebacks, but it's a necessary evil for latent completion
+      # definitions.
+
+      if :completed == state || !completed? || @state == state
+        @callbacks[state] << EM::Callback(*a, &b)
+      end
+      execute_callbacks
+      self
+    end
+
+    # Callbacks are called when you enter (or are in) a :succeeded state.
+    def callback(*a, &b)
+      stateback(:succeeded, *a, &b)
+    end
+
+    # Errbacks are called when you enter (or are in) a :failed state.
+    def errback(*a, &b)
+      stateback(:failed, *a, &b)
+    end
+
+    # Completions are called when you enter (or are in) either a :failed or a
+    # :succeeded state. They are stored as a special (reserved) state called
+    # :completed.
+    def completion(*a, &b)
+      stateback(:completed, *a, &b)
+    end
+
+    # Enter a new state, setting the result value if given. If the state is one
+    # of :succeeded or :failed, then :completed callbacks will also be called.
+    def change_state(state, *args)
+      @value = args
+      @state = state
+
+      EM.schedule { execute_callbacks }
+    end
+
+    # The old EM method:
+    alias set_deferred_status change_state
+
+    # Indicates that we've reached some kind of completion state, by default
+    # this is :succeeded or :failed. Due to these semantics, the :completed
+    # state is reserved for internal use.
+    def completed?
+      completion_states.any? { |s| state == s }
+    end
+
+    # Completion states simply returns a list of completion states, by default
+    # this is :succeeded and :failed.
+    def completion_states
+      [:succeeded, :failed]
+    end
+
+    # Schedule a time which if passes before we enter a completion state, this
+    # deferrable will be failed with the given arguments.
+    def timeout(time, *args)
+      cancel_timeout
+      @timeout_timer = EM::Timer.new(time) do
+        fail(*args) unless completed?
+      end
+    end
+
+    # Disable the timeout
+    def cancel_timeout
+      if @timeout_timer
+        @timeout_timer.cancel
+        @timeout_timer = nil
+      end
+    end
+
+    # Remove an errback. N.B. Some errbacks cannot be deleted. Usage is NOT
+    # recommended, this is an anti-pattern.
+    def cancel_errback(*a, &b)
+      @callbacks[:failed].delete(EM::Callback(*a, &b))
+    end
+
+    # Remove a callback. N.B. Some callbacks cannot be deleted. Usage is NOT
+    # recommended, this is an anti-pattern.
+    def cancel_callback(*a, &b)
+      @callbacks[:succeeded].delete(EM::Callback(*a, &b))
+    end
+
+    private
+    # Execute all callbacks for the current state. If in a completed state, then
+    # call any statebacks associated with the completed state.
+    def execute_callbacks
+      execute_state_callbacks(state)
+      if completed?
+        execute_state_callbacks(:completed)
+        clear_dead_callbacks
+        cancel_timeout
+      end
+    end
+
+    # Iterate all callbacks for a given state, and remove then call them.
+    def execute_state_callbacks(state)
+      while callback = @callbacks[state].shift
+        callback.call(*value)
+      end
+    end
+
+    # If we enter a completion state, clear other completion states after all
+    # callback chains are completed. This means that operation specific
+    # callbacks can't be dual-called, which is most common user error.
+    def clear_dead_callbacks
+      completion_states.each do |state|
+        @callbacks[state].clear
+      end
+    end
+  end
+end