lib/em/completion.rb
module EventMachine
##
# An EM::Completion instance is a callback container for various states of
# completion. In its 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.
#
# ```ruby
# 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.
#
# ```ruby
# 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.
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