module EventMachine
EM::Completion¶ ↑
A completion 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.
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.
@private
@private
Top-level EventMachine
namespace. If you are looking for EventMachine
examples, see {file:docs/GettingStarted.md EventMachine
tutorial}.
## Key methods ## ### Starting and stopping the event loop ###
-
{EventMachine.run}
-
{EventMachine.stop_event_loop}
### Implementing clients ###
-
{EventMachine.connect}
### Implementing servers ###
-
{EventMachine.start_server}
### Working with timers ###
-
{EventMachine.add_timer}
-
{EventMachine.add_periodic_timer}
-
{EventMachine.cancel_timer}
### Working with blocking tasks ###
-
{EventMachine.defer}
-
{EventMachine.next_tick}
### Efficient proxying ###
-
{EventMachine.enable_proxy}
-
{EventMachine.disable_proxy}
Constants
- ConnectionAccepted
@private
- ConnectionCompleted
@private
- ConnectionData
@private
- ConnectionNotifyReadable
@private
- ConnectionNotifyWritable
@private
- ConnectionUnbound
@private
- DefaultCertificate
@private
- DefaultDHKey1024
@private
- DefaultDHKey2048
@private
- EM_PROTO_SSLv2
@private
- EM_PROTO_SSLv3
@private
- EM_PROTO_TLSv1
@private
- EM_PROTO_TLSv1_1
@private
- EM_PROTO_TLSv1_2
@private
- EM_PROTO_TLSv1_3
- ERRNOS
System errnos @private
- LoopbreakSignalled
@private
- OPENSSL_LIBRARY_VERSION
Version of OpenSSL that
EventMachine
loaded with- OPENSSL_NO_SSL2
- OPENSSL_NO_SSL3
- OPENSSL_VERSION
Version of OpenSSL that
EventMachine
was compiled with- SSLConnectionWaitReadable
- SSLConnectionWaitWritable
- SslHandshakeCompleted
@private
- SslVerify
@private
- TimerFired
@private
Attributes
Exposed to allow joining on the thread, when run in a multithreaded environment. Performing other actions on the thread has undefined semantics (read: a dangerous endevor).
@return [Thread]
@private
Size of the EventMachine.defer
threadpool (defaults to 20) @return [Number]
Public Class Methods
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>]
# File lib/em/callback.rb, line 47 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
@private
# File lib/eventmachine.rb, line 1563 def self._open_file_for_writing filename, handler=nil klass = klass_from_handler(Connection, handler) s = _write_file filename c = klass.new s @conns[s] = c block_given? and yield c c end
Changed 04Oct06: intervals from the caller are now in milliseconds, but our native-ruby processor still wants them in seconds. @private
# File lib/em/pure_ruby.rb, line 138 def add_oneshot_timer interval Reactor.instance.install_oneshot_timer(interval / 1000) end
Adds a periodic timer to the event loop. It takes the same parameters as the one-shot timer method, {EventMachine.add_timer}. This method schedules execution of the given block repeatedly, at intervals of time *at least* as great as the number of seconds given in the first parameter to the call.
@example Write a dollar-sign to stderr every five seconds, without blocking
EventMachine.run { EventMachine.add_periodic_timer( 5 ) { $stderr.write "$" } }
@param [Integer] delay Delay in seconds
@see EventMachine::PeriodicTimer
@see EventMachine.add_timer
# File lib/eventmachine.rb, line 351 def self.add_periodic_timer *args, &block interval = args.shift code = args.shift || block EventMachine::PeriodicTimer.new(interval, code) end
Adds a block to call as the reactor is shutting down.
These callbacks are called in the reverse order to which they are added.
@example Scheduling operations to be run when EventMachine
event loop is stopped
EventMachine.run do EventMachine.add_shutdown_hook { puts "b" } EventMachine.add_shutdown_hook { puts "a" } EventMachine.stop end # Outputs: # a # b
# File lib/eventmachine.rb, line 291 def self.add_shutdown_hook &block @tails << block end
Adds a one-shot timer to the event loop. Call it with one or two parameters. The first parameters is a delay-time expressed in seconds (not milliseconds). The second parameter, if present, must be an object that responds to :call. If 2nd parameter is not given, then you can also simply pass a block to the method call.
This method may be called from the block passed to {EventMachine.run} or from any callback method. It schedules execution of the proc or block passed to it, after the passage of an interval of time equal to *at least* the number of seconds specified in the first parameter to the call.
{EventMachine.add_timer} is a non-blocking method. Callbacks can and will be called during the interval of time that the timer is in effect. There is no built-in limit to the number of timers that can be outstanding at any given time.
@example Setting a one-shot timer with EventMachine
EventMachine.run { puts "Starting the run now: #{Time.now}" EventMachine.add_timer 5, proc { puts "Executing timer event: #{Time.now}" } EventMachine.add_timer(10) { puts "Executing timer event: #{Time.now}" } }
@param [Integer] delay Delay in seconds @see EventMachine::Timer
@see EventMachine.add_periodic_timer
# File lib/eventmachine.rb, line 323 def self.add_timer *args, &block interval = args.shift code = args.shift || block if code # check too many timers! s = add_oneshot_timer((interval.to_f * 1000).to_i) @timers[s] = code s end end
Attaches an IO
object or file descriptor to the eventloop as a regular connection. The file descriptor will be set as non-blocking, and EventMachine
will process receive_data and send_data
events on it as it would for any other connection.
To watch a fd instead, use {EventMachine.watch}, which will not alter the state of the socket and fire notify_readable and notify_writable events instead.
# File lib/eventmachine.rb, line 741 def EventMachine::attach io, handler=nil, *args, &blk attach_io io, false, handler, *args, &blk end
@private
# File lib/eventmachine.rb, line 746 def EventMachine::attach_io io, watch_mode, handler=nil, *args klass = klass_from_handler(Connection, handler, *args) if !watch_mode and klass.public_instance_methods.any?{|m| [:notify_readable, :notify_writable].include? m.to_sym } raise ArgumentError, "notify_readable/writable with EM.attach is not supported. Use EM.watch(io){ |c| c.notify_readable = true }" end if io.respond_to?(:fileno) # getDescriptorByFileno deprecated in JRuby 1.7.x, removed in JRuby 9000 if defined?(JRuby) && JRuby.runtime.respond_to?(:getDescriptorByFileno) fd = JRuby.runtime.getDescriptorByFileno(io.fileno).getChannel else fd = io.fileno end else fd = io end s = attach_fd fd, watch_mode c = klass.new s, *args c.instance_variable_set(:@io, io) c.instance_variable_set(:@watch_mode, watch_mode) c.instance_variable_set(:@fd, fd) @conns[s] = c block_given? and yield c c end
Attach to an existing socket’s file descriptor. The socket may have been started with {EventMachine.start_server}.
# File lib/eventmachine.rb, line 541 def self.attach_server sock, handler=nil, *args, &block klass = klass_from_handler(Connection, handler, *args) sd = sock.respond_to?(:fileno) ? sock.fileno : sock s = attach_sd(sd) @acceptors[s] = [klass,args,block,sock] s end
This method is like {EventMachine.connect}, but allows for a local address/port to bind the connection to.
@see EventMachine.connect
# File lib/eventmachine.rb, line 661 def self.bind_connect bind_addr, bind_port, server, port=nil, handler=nil, *args begin port = Integer(port) rescue ArgumentError, TypeError # there was no port, so server must be a unix domain socket # the port argument is actually the handler, and the handler is one of the args args.unshift handler if handler handler = port port = nil end if port klass = klass_from_handler(Connection, handler, *args) s = if port if bind_addr bind_connect_server bind_addr, bind_port.to_i, server, port else connect_server server, port end else connect_unix_server server end c = klass.new s, *args @conns[s] = c block_given? and yield c c end
@private
# File lib/em/pure_ruby.rb, line 167 def bind_connect_server bind_addr, bind_port, host, port EvmaTCPClient.connect(bind_addr, bind_port, host, port).uuid end
Cancel a timer (can be a callback or an {EventMachine::Timer} instance).
@param [#cancel, call] timer_or_sig A timer to cancel @see EventMachine::Timer#cancel
# File lib/eventmachine.rb, line 363 def self.cancel_timer timer_or_sig if timer_or_sig.respond_to? :cancel timer_or_sig.cancel else @timers[timer_or_sig] = false if @timers.has_key?(timer_or_sig) end end
Clean up Ruby space following a release_machine
# File lib/eventmachine.rb, line 261 def self.cleanup_machine if @threadpool && !@threadpool.empty? # Tell the threads to stop @threadpool.each { |t| t.exit } # Join the threads or bump the stragglers one more time @threadpool.each { |t| t.join 0.01 || t.exit } end @threadpool = nil @threadqueue = nil @resultqueue = nil @all_threads_spawned = false @next_tick_queue = [] end
@private
# File lib/em/pure_ruby.rb, line 178 def close_connection target, after_writing selectable = Reactor.instance.get_selectable( target ) selectable.schedule_close after_writing if selectable end
Initiates a TCP connection to a remote server and sets up event handling for the connection. {EventMachine.connect} requires event loop to be running (see {EventMachine.run}).
{EventMachine.connect} takes the IP address (or hostname) and port of the remote server you want to connect to. It also takes an optional handler (a module or a subclass of {EventMachine::Connection}) which you must define, that contains the callbacks that will be invoked by the event loop on behalf of the connection.
Learn more about connection lifecycle callbacks in the {file:docs/GettingStarted.md EventMachine
tutorial} and {file:docs/ConnectionLifecycleCallbacks.md Connection
lifecycle guide}.
@example
# Here's a program which connects to a web server, sends a naive # request, parses the HTTP header of the response, and then # (antisocially) ends the event loop, which automatically drops the connection # (and incidentally calls the connection's unbind method). module DumbHttpClient def post_init send_data "GET / HTTP/1.1\r\nHost: _\r\n\r\n" @data = "" @parsed = false end def receive_data data @data << data if !@parsed and @data =~ /[\n][\r]*[\n]/m @parsed = true puts "RECEIVED HTTP HEADER:" $`.each {|line| puts ">>> #{line}" } puts "Now we'll terminate the loop, which will also close the connection" EventMachine::stop_event_loop end end def unbind puts "A connection has terminated" end end EventMachine.run { EventMachine.connect "www.bayshorenetworks.com", 80, DumbHttpClient } puts "The event loop has ended"
@example Defining protocol handler as a class
class MyProtocolHandler < EventMachine::Connection def initialize *args super # whatever else you want to do here end # ... end
@param [String] server Host to connect to @param [Integer] port Port to connect to @param [Module, Class] handler A module or class that implements connection lifecycle callbacks
@see EventMachine.start_server
@see file:docs/GettingStarted.md EventMachine
tutorial
# File lib/eventmachine.rb, line 631 def self.connect server, port=nil, handler=nil, *args, &blk # EventMachine::connect initiates a TCP connection to a remote # server and sets up event-handling for the connection. # It internally creates an object that should not be handled # by the caller. HOWEVER, it's often convenient to get the # object to set up interfacing to other objects in the system. # We return the newly-created anonymous-class object to the caller. # It's expected that a considerable amount of code will depend # on this behavior, so don't change it. # # Ok, added support for a user-defined block, 13Apr06. # This leads us to an interesting choice because of the # presence of the post_init call, which happens in the # initialize method of the new object. We call the user's # block and pass the new object to it. This is a great # way to do protocol-specific initiation. It happens # AFTER post_init has been called on the object, which I # certainly hope is the right choice. # Don't change this lightly, because accepted connections # are different from connected ones and we don't want # to have them behave differently with respect to post_init # if at all possible. bind_connect nil, nil, server, port, handler, *args, &blk end
@private
# File lib/em/pure_ruby.rb, line 162 def connect_server host, port bind_connect_server nil, nil, host, port end
Make a connection to a Unix-domain socket. This method is simply an alias for {.connect}, which can connect to both TCP and Unix-domain sockets. Make sure that your process has sufficient permissions to open the socket it is given.
@param [String] socketname Unix domain socket (local fully-qualified path) you want to connect to.
@note UNIX sockets, as the name suggests, are not available on Microsoft Windows.
# File lib/eventmachine.rb, line 813 def self.connect_unix_domain socketname, *args, &blk connect socketname, *args, &blk end
@private
# File lib/em/pure_ruby.rb, line 202 def connect_unix_server chain EvmaUNIXClient.connect(chain).uuid end
Returns the total number of connections (file descriptors) currently held by the reactor. Note that a tick must pass after the ‘initiation’ of a connection for this number to increment. It’s usually accurate, but don’t rely on the exact precision of this number unless you really know EM
internals.
@example
EventMachine.run { EventMachine.connect("rubyeventmachine.com", 80) # count will be 0 in this case, because connection is not # established yet count = EventMachine.connection_count }
@example
EventMachine.run { EventMachine.connect("rubyeventmachine.com", 80) EventMachine.next_tick { # In this example, count will be 1 since the connection has been established in # the next loop of the reactor. count = EventMachine.connection_count } }
@return [Integer] Number of connections currently held by the reactor.
# File lib/eventmachine.rb, line 955 def self.connection_count self.get_connection_count end
EventMachine.defer
is used for integrating blocking operations into EventMachine’s control flow. The action of {.defer} is to take the block specified in the first parameter (the “operation”) and schedule it for asynchronous execution on an internal thread pool maintained by EventMachine
. When the operation completes, it will pass the result computed by the block (if any) back to the EventMachine
reactor. Then, EventMachine
calls the block specified in the second parameter to {.defer} (the “callback”), as part of its normal event handling loop. The result computed by the operation block is passed as a parameter to the callback. You may omit the callback parameter if you don’t need to execute any code after the operation completes. If the operation raises an unhandled exception, the exception will be passed to the third parameter to {.defer} (the “errback”), as part of its normal event handling loop. If no errback is provided, the exception will be allowed to blow through to the main thread immediately.
## Caveats ##
Note carefully that the code in your deferred operation will be executed on a separate thread from the main EventMachine
processing and all other Ruby threads that may exist in your program. Also, multiple deferred operations may be running at once! Therefore, you are responsible for ensuring that your operation code is threadsafe.
Don’t write a deferred operation that will block forever. If so, the current implementation will not detect the problem, and the thread will never be returned to the pool. EventMachine
limits the number of threads in its pool, so if you do this enough times, your subsequent deferred operations won’t get a chance to run.
The threads within the EventMachine’s thread pool have abort_on_exception set to true. As a result, if an unhandled exception is raised by the deferred operation and an errback is not provided, it will blow through to the main thread immediately. If the main thread is within an indiscriminate rescue block at that time, the exception could be handled improperly by the main thread.
@example
operation = proc { # perform a long-running operation here, such as a database query. "result" # as usual, the last expression evaluated in the block will be the return value. } callback = proc {|result| # do something with result here, such as send it back to a network client. } errback = proc {|error| # do something with error here, such as re-raising or logging. } EventMachine.defer(operation, callback, errback)
@param [#call] op An operation you want to offload to EventMachine
thread pool @param [#call] callback A callback that will be run on the event loop thread after ‘operation` finishes. @param [#call] errback An errback that will be run on the event loop thread after `operation` raises an exception.
@see EventMachine.threadpool_size
# File lib/eventmachine.rb, line 1043 def self.defer op = nil, callback = nil, errback = nil, &blk # OBSERVE that #next_tick hacks into this mechanism, so don't make any changes here # without syncing there. # # Running with $VERBOSE set to true gives a warning unless all ivars are defined when # they appear in rvalues. But we DON'T ever want to initialize @threadqueue unless we # need it, because the Ruby threads are so heavyweight. We end up with this bizarre # way of initializing @threadqueue because EventMachine is a Module, not a Class, and # has no constructor. unless @threadpool @threadpool = [] @threadqueue = ::Queue.new @resultqueue = ::Queue.new spawn_threadpool end @threadqueue << [op||blk,callback,errback] end
Returns true
if all deferred actions are done executing and their callbacks have been fired.
# File lib/eventmachine.rb, line 1095 def self.defers_finished? return false if @threadpool and !@all_threads_spawned return false if @threadqueue and not @threadqueue.empty? return false if @resultqueue and not @resultqueue.empty? return false if @threadpool and @threadqueue.num_waiting != @threadpool.size return true end
Takes just one argument, a {Connection} that has proxying enabled via {EventMachine.enable_proxy}. Calling this method will remove that functionality and your connection will begin receiving data via {Connection#receive_data} again.
@param [EventMachine::Connection] from Source of data that is being proxied @see EventMachine.enable_proxy
# File lib/eventmachine.rb, line 1440 def self.disable_proxy(from) EM::stop_proxy(from.signature) end
This method allows for direct writing of incoming data back out to another descriptor, at the C++ level in the reactor. This is very efficient and especially useful for proxies where high performance is required. Propogating data from a server response all the way up to Ruby, and then back down to the reactor to be sent back to the client, is often unnecessary and incurs a significant performance decrease.
The two arguments are instance of {EventMachine::Connection} subclasses, ‘from’ and ‘to’. ‘from’ is the connection whose inbound data you want relayed back out. ‘to’ is the connection to write it to.
Once you call this method, the ‘from’ connection will no longer get receive_data callbacks from the reactor, except in the case that ‘to’ connection has already closed when attempting to write to it. You can see in the example, that proxy_target_unbound will be called when this occurs. After that, further incoming data will be passed into receive_data as normal.
Note also that this feature supports different types of descriptors: TCP, UDP, and pipes. You can relay data from one kind to another, for example, feed a pipe from a UDP stream.
@example
module ProxyConnection def initialize(client, request) @client, @request = client, request end def post_init EM::enable_proxy(self, @client) end def connection_completed send_data @request end def proxy_target_unbound close_connection end def unbind @client.close_connection_after_writing end end module ProxyServer def receive_data(data) (@buf ||= "") << data if @buf =~ /\r\n\r\n/ # all http headers received EventMachine.connect("10.0.0.15", 80, ProxyConnection, self, data) end end end EventMachine.run { EventMachine.start_server("127.0.0.1", 8080, ProxyServer) }
@param [EventMachine::Connection] from Source of data to be proxies/streamed. @param [EventMachine::Connection] to Destination of data to be proxies/streamed. @param [Integer] bufsize Buffer size to use @param [Integer] length Maximum number of bytes to proxy.
@see EventMachine.disable_proxy
# File lib/eventmachine.rb, line 1430 def self.enable_proxy(from, to, bufsize=0, length=0) EM::start_proxy(from.signature, to.signature, bufsize, length) end
This method is a harmless no-op in the pure-Ruby implementation. This is intended to ensure that user code behaves properly across different EM
implementations. @private
# File lib/em/pure_ruby.rb, line 247 def epoll end
Catch-all for errors raised during event loop callbacks.
@example
EventMachine.error_handler{ |e| puts "Error raised during event loop: #{e.message}" }
@param [#call] cb Global catch-all errback
# File lib/eventmachine.rb, line 1363 def self.error_handler cb = nil, &blk if cb or blk @error_handler = cb || blk elsif instance_variable_defined? :@error_handler remove_instance_variable :@error_handler end end
@private
# File lib/eventmachine.rb, line 1463 def self.event_callback conn_binding, opcode, data # # Changed 27Dec07: Eliminated the hookable error handling. # No one was using it, and it degraded performance significantly. # It's in original_event_callback, which is dead code. # # Changed 25Jul08: Added a partial solution to the problem of exceptions # raised in user-written event-handlers. If such exceptions are not caught, # we must cause the reactor to stop, and then re-raise the exception. # Otherwise, the reactor doesn't stop and it's left on the call stack. # This is partial because we only added it to #unbind, where it's critical # (to keep unbind handlers from being re-entered when a stopping reactor # runs down open connections). It should go on the other calls to user # code, but the performance impact may be too large. # if opcode == ConnectionUnbound if c = @conns.delete( conn_binding ) begin if c.original_method(:unbind).arity != 0 c.unbind(data == 0 ? nil : EventMachine::ERRNOS[data]) else c.unbind end # If this is an attached (but not watched) connection, close the underlying io object. if c.instance_variable_defined?(:@io) and !c.instance_variable_get(:@watch_mode) io = c.instance_variable_get(:@io) begin io.close rescue Errno::EBADF, IOError end end # As noted above, unbind absolutely must not raise an exception or the reactor will crash. # If there is no EM.error_handler, or if the error_handler retrows, then stop the reactor, # stash the exception in $wrapped_exception, and the exception will be raised after the # reactor is cleaned up (see the last line of self.run). rescue Exception => error if instance_variable_defined? :@error_handler begin @error_handler.call error # No need to stop unless error_handler rethrows rescue Exception => error @wrapped_exception = error stop end else @wrapped_exception = error stop end end elsif c = @acceptors.delete( conn_binding ) # no-op else if $! # Bubble user generated errors. @wrapped_exception = $! stop else raise ConnectionNotBound, "received ConnectionUnbound for an unknown signature: #{conn_binding}" end end elsif opcode == ConnectionAccepted accep,args,blk = @acceptors[conn_binding] raise NoHandlerForAcceptedConnection unless accep c = accep.new data, *args @conns[data] = c blk and blk.call(c) c # (needed?) ## # The remaining code is a fallback for the pure ruby and java reactors. # In the C++ reactor, these events are handled in the C event_callback() in rubymain.cpp elsif opcode == ConnectionCompleted c = @conns[conn_binding] or raise ConnectionNotBound, "received ConnectionCompleted for unknown signature: #{conn_binding}" c.connection_completed elsif opcode == SslHandshakeCompleted c = @conns[conn_binding] or raise ConnectionNotBound, "received SslHandshakeCompleted for unknown signature: #{conn_binding}" c.ssl_handshake_completed elsif opcode == SslVerify c = @conns[conn_binding] or raise ConnectionNotBound, "received SslVerify for unknown signature: #{conn_binding}" c.close_connection if c.ssl_verify_peer(data) == false elsif opcode == TimerFired t = @timers.delete( data ) return if t == false # timer cancelled t or raise UnknownTimerFired, "timer data: #{data}" t.call elsif opcode == ConnectionData c = @conns[conn_binding] or raise ConnectionNotBound, "received data #{data} for unknown signature: #{conn_binding}" c.receive_data data elsif opcode == LoopbreakSignalled run_deferred_callbacks elsif opcode == ConnectionNotifyReadable c = @conns[conn_binding] or raise ConnectionNotBound c.notify_readable elsif opcode == ConnectionNotifyWritable c = @conns[conn_binding] or raise ConnectionNotBound c.notify_writable end end
Forks a new process, properly stops the reactor and then calls {EventMachine.run} inside of it again, passing your block.
# File lib/eventmachine.rb, line 243 def self.fork_reactor &block # This implementation is subject to change, especially if we clean up the relationship # of EM#run to @reactor_running. # Original patch by Aman Gupta. # Kernel.fork do if reactor_running? stop_event_loop release_machine cleanup_machine @reactor_running = false @reactor_thread = nil end run block end end
# File lib/em/pure_ruby.rb, line 359 def get_cipher_bits signature selectable = Reactor.instance.get_selectable(signature) or raise "unknown get_cipher_bits target" selectable.io.respond_to?(:cipher) ? selectable.io.cipher[2] : nil end
# File lib/em/pure_ruby.rb, line 349 def get_cipher_name signature selectable = Reactor.instance.get_selectable(signature) or raise "unknown get_cipher_name target" selectable.io.respond_to?(:cipher) ? selectable.io.cipher[0] : nil end
# File lib/em/pure_ruby.rb, line 354 def get_cipher_protocol signature selectable = Reactor.instance.get_selectable(signature) or raise "unknown get_cipher_protocol target" selectable.io.respond_to?(:cipher) ? selectable.io.cipher[1] : nil end
Gets the current maximum number of allowed timers
@return [Integer] Maximum number of timers that may be outstanding at any given time
# File lib/eventmachine.rb, line 924 def self.get_max_timers get_max_timer_count end
@private
# File lib/em/pure_ruby.rb, line 412 def get_outbound_data_size sig r = Reactor.instance.get_selectable( sig ) or raise "unknown get_outbound_data_size target" r.get_outbound_data_size end
# File lib/em/pure_ruby.rb, line 340 def get_peer_cert signature selectable = Reactor.instance.get_selectable(signature) or raise "unknown get_peer_cert target" if selectable.io.respond_to?(:peer_cert) && selectable.io.peer_cert selectable.io.peer_cert.to_pem else nil end end
@private
# File lib/em/pure_ruby.rb, line 212 def get_peername sig selectable = Reactor.instance.get_selectable( sig ) or raise "unknown get_peername target" selectable.get_peername end
# File lib/em/pure_ruby.rb, line 364 def get_sni_hostname signature @tls_parms ||= {} if @tls_parms[signature] @tls_parms[signature][:server_name] else nil end end
@private
# File lib/em/pure_ruby.rb, line 387 def get_sock_opt signature, level, optname selectable = Reactor.instance.get_selectable( signature ) or raise "unknown get_sock_opt target" selectable.getsockopt level, optname end
@private
# File lib/em/pure_ruby.rb, line 218 def get_sockname sig selectable = Reactor.instance.get_selectable( sig ) or raise "unknown get_sockname target" selectable.get_sockname end
Retrieve the heartbeat interval. This is how often EventMachine
will check for dead connections that have had an inactivity timeout set via {Connection#set_comm_inactivity_timeout}. Default is 2 seconds.
@return [Integer] Heartbeat interval, in seconds
# File lib/eventmachine.rb, line 1449 def self.heartbeat_interval EM::get_heartbeat_interval end
Set the heartbeat interval. This is how often EventMachine
will check for dead connections that have had an inactivity timeout set via {Connection#set_comm_inactivity_timeout}. Takes a Numeric number of seconds. Default is 2.
@param [Integer] time Heartbeat interval, in seconds
# File lib/eventmachine.rb, line 1458 def self.heartbeat_interval=(time) EM::set_heartbeat_interval time.to_f end
@private
# File lib/em/pure_ruby.rb, line 131 def initialize_event_machine Reactor.instance.initialize_for_run end
@private
# File lib/eventmachine.rb, line 1574 def self.klass_from_handler(klass = Connection, handler = nil, *args) klass = if handler and handler.is_a?(Class) raise ArgumentError, "must provide module or subclass of #{klass.name}" unless klass >= handler handler elsif handler if defined?(handler::EM_CONNECTION_CLASS) handler::EM_CONNECTION_CLASS else handler::const_set(:EM_CONNECTION_CLASS, Class.new(klass) {include handler}) end else klass end arity = klass.instance_method(:initialize).arity expected = arity >= 0 ? arity : -(arity + 1) if (arity >= 0 and args.size != expected) or (arity < 0 and args.size < expected) raise ArgumentError, "wrong number of arguments for #{klass}#initialize (#{args.size} for #{expected})" end klass end
This is mostly useful for automated tests. Return a distinctive symbol so the caller knows whether he’s dealing with an extension or with a pure-Ruby library. @private
# File lib/em/pure_ruby.rb, line 126 def library_type :pure_ruby end
Schedules a proc for execution immediately after the next “turn” through the reactor core. An advanced technique, this can be useful for improving memory management and/or application responsiveness, especially when scheduling large amounts of data for writing to a network connection.
This method takes either a single argument (which must be a callable object) or a block.
@param [#call] pr A callable object to run
# File lib/eventmachine.rb, line 1121 def self.next_tick pr=nil, &block # This works by adding to the @resultqueue that's used for #defer. # The general idea is that next_tick is used when we want to give the reactor a chance # to let other operations run, either to balance the load out more evenly, or to let # outbound network buffers drain, or both. So we probably do NOT want to block, and # we probably do NOT want to be spinning any threads. A program that uses next_tick # but not #defer shouldn't suffer the penalty of having Ruby threads running. They're # extremely expensive even if they're just sleeping. raise ArgumentError, "no proc or block given" unless ((pr && pr.respond_to?(:call)) or block) @next_tick_mutex.synchronize do @next_tick_queue << ( pr || block ) end signal_loopbreak if reactor_running? end
Used for UDP-based protocols. Its usage is similar to that of {EventMachine.start_server}.
This method will create a new UDP (datagram) socket and bind it to the address and port that you specify. The normal callbacks (see {EventMachine.start_server}) will be called as events of interest occur on the newly-created socket, but there are some differences in how they behave.
{Connection#receive_data} will be called when a datagram packet is received on the socket, but unlike TCP sockets, the message boundaries of the received data will be respected. In other words, if the remote peer sent you a datagram of a particular size, you may rely on {Connection#receive_data} to give you the exact data in the packet, with the original data length. Also observe that Connection#receive_data
may be called with a zero-length data payload, since empty datagrams are permitted in UDP.
{Connection#send_data} is available with UDP packets as with TCP, but there is an important difference. Because UDP communications are connectionless, there is no implicit recipient for the packets you send. Ordinarily you must specify the recipient for each packet you send. However, EventMachine
provides for the typical pattern of receiving a UDP datagram from a remote peer, performing some operation, and then sending one or more packets in response to the same remote peer. To support this model easily, just use {Connection#send_data} in the code that you supply for {Connection#receive_data}.
EventMachine
will provide an implicit return address for any messages sent to {Connection#send_data} within the context of a {Connection#receive_data} callback, and your response will automatically go to the correct remote peer.
Observe that the port number that you supply to {EventMachine.open_datagram_socket} may be zero. In this case, EventMachine
will create a UDP socket that is bound to an [ephemeral port](en.wikipedia.org/wiki/Ephemeral_port). This is not appropriate for servers that must publish a well-known port to which remote peers may send datagrams. But it can be useful for clients that send datagrams to other servers. If you do this, you will receive any responses from the remote servers through the normal {Connection#receive_data} callback. Observe that you will probably have issues with firewalls blocking the ephemeral port numbers, so this technique is most appropriate for LANs.
If you wish to send datagrams to arbitrary remote peers (not necessarily ones that have sent data to which you are responding), then see {Connection#send_datagram}.
DO NOT call send_data
from a datagram socket outside of a {Connection#receive_data} method. Use {Connection#send_datagram}. If you do use {Connection#send_data} outside of a {Connection#receive_data} method, you’ll get a confusing error because there is no “peer,” as send_data requires (inside of {EventMachine::Connection#receive_data}, {EventMachine::Connection#send_data} “fakes” the peer as described above).
@param [String] address IP address @param [String] port Port @param [Class, Module] handler A class or a module that implements connection lifecycle callbacks.
# File lib/eventmachine.rb, line 872 def self.open_datagram_socket address, port, handler=nil, *args # Replaced the implementation on 01Oct06. Thanks to Tobias Gustafsson for pointing # out that this originally did not take a class but only a module. klass = klass_from_handler(Connection, handler, *args) s = open_udp_socket address, port.to_i c = klass.new s, *args @conns[s] = c block_given? and yield c c end
(Experimental)
@private
# File lib/eventmachine.rb, line 1235 def self.open_keyboard handler=nil, *args klass = klass_from_handler(Connection, handler, *args) s = read_keyboard c = klass.new s, *args @conns[s] = c block_given? and yield c c end
@private
# File lib/em/pure_ruby.rb, line 224 def open_udp_socket host, port EvmaUDPSocket.create(host, port).uuid end
Runs an external process.
@example
module RubyCounter def post_init # count up to 5 send_data "5\n" end def receive_data data puts "ruby sent me: #{data}" end def unbind puts "ruby died with exit status: #{get_status.exitstatus}" end end EventMachine.run { EventMachine.popen("ruby -e' $stdout.sync = true; gets.to_i.times{ |i| puts i+1; sleep 1 } '", RubyCounter) }
@note This method is not supported on Microsoft Windows @see EventMachine::DeferrableChildProcess
@see EventMachine.system
# File lib/eventmachine.rb, line 1198 def self.popen cmd, handler=nil, *args # At this moment, it's only available on Unix. # Perhaps misnamed since the underlying function uses socketpair and is full-duplex. klass = klass_from_handler(Connection, handler, *args) w = case cmd when Array cmd when String Shellwords::shellwords( cmd ) end w.unshift( w.first ) if w.first s = invoke_popen( w ) c = klass.new s, *args @conns[s] = c yield(c) if block_given? c end
Tells you whether the EventMachine
reactor loop is currently running.
Useful when writing libraries that want to run event-driven code, but may be running in programs that are already event-driven. In such cases, if {EventMachine.reactor_running?} returns false, your code can invoke {EventMachine.run} and run your application code inside the block passed to that method. If this method returns true, just execute your event-aware code.
@return [Boolean] true if the EventMachine
reactor loop is currently running
# File lib/eventmachine.rb, line 1227 def self.reactor_running? @reactor_running && Process.pid == @reactor_pid end
@return [Boolean] true if the calling thread is the same thread as the reactor.
# File lib/eventmachine.rb, line 227 def self.reactor_thread? Thread.current == @reactor_thread end
@private
# File lib/em/pure_ruby.rb, line 418 def read_keyboard EvmaKeyboard.open.uuid end
Connect to a given host/port and re-use the provided {EventMachine::Connection} instance. Consider also {EventMachine::Connection#reconnect}.
@see EventMachine::Connection#reconnect
# File lib/eventmachine.rb, line 781 def self.reconnect server, port, handler # Observe, the test for already-connected FAILS if we call a reconnect inside post_init, # because we haven't set up the connection in @conns by that point. # RESIST THE TEMPTATION to "fix" this problem by redefining the behavior of post_init. # # Changed 22Nov06: if called on an already-connected handler, just return the # handler and do nothing more. Originally this condition raised an exception. # We may want to change it yet again and call the block, if any. raise "invalid handler" unless handler.respond_to?(:connection_completed) #raise "still connected" if @conns.has_key?(handler.signature) return handler if @conns.has_key?(handler.signature) s = if port connect_server server, port else connect_unix_server server end handler.signature = s @conns[s] = handler block_given? and yield handler handler end
@private
# File lib/em/pure_ruby.rb, line 148 def release_machine end
@private
# File lib/em/pure_ruby.rb, line 435 def report_connection_error_status signature get_sock_opt(signature, Socket::SOL_SOCKET, Socket::SO_ERROR).int end
Initializes and runs an event loop. This method only returns if code inside the block passed to this method calls {EventMachine.stop_event_loop}. The block is executed after initializing its internal event loop but before running the loop, therefore this block is the right place to call any code that needs event loop to run, for example, {EventMachine.start_server}, {EventMachine.connect} or similar methods of libraries that use EventMachine
under the hood (like ‘EventMachine::HttpRequest.new` or `AMQP.start`).
Programs that are run for long periods of time (e.g. servers) usually start event loop by calling {EventMachine.run}, and let it run “forever”. It’s also possible to use {EventMachine.run} to make a single client-connection to a remote server, process the data flow from that single connection, and then call {EventMachine.stop_event_loop} to stop, in other words, to run event loop for a short period of time (necessary to complete some operation) and then shut it down.
Once event loop is running, it is perfectly possible to start multiple servers and clients simultaneously: content-aware proxies like [Proxymachine](github.com/mojombo/proxymachine) do just that.
## Using EventMachine
with Ruby on Rails and other Web application frameworks ##
Standalone applications often run event loop on the main thread, thus blocking for their entire lifespan. In case of Web applications, if you are running an EventMachine-based app server such as [Thin](code.macournoyer.com/thin/) or [Goliath](github.com/postrank-labs/goliath/), they start event loop for you. Servers like Unicorn, Apache Passenger or Mongrel occupy main Ruby thread to serve HTTP(S) requests. This means that calling {EventMachine.run} on the same thread is not an option (it will result in Web server never binding to the socket). In that case, start event loop in a separate thread as demonstrated below.
@example Starting EventMachine
event loop in the current thread to run the “Hello, world”-like Echo server example
#!/usr/bin/env ruby require 'rubygems' # or use Bundler.setup require 'eventmachine' class EchoServer < EM::Connection def receive_data(data) send_data(data) end end EventMachine.run do EventMachine.start_server("0.0.0.0", 10000, EchoServer) end
@example Starting EventMachine
event loop in a separate thread
# doesn't block current thread, can be used with Ruby on Rails, Sinatra, Merb, Rack # and any other application server that occupies main Ruby thread. Thread.new { EventMachine.run }
@note This method blocks calling thread. If you need to start EventMachine
event loop from a Web app
running on a non event-driven server (Unicorn, Apache Passenger, Mongrel), do it in a separate thread like demonstrated in one of the examples.
@see file:docs/GettingStarted.md Getting started with EventMachine
@see EventMachine.stop_event_loop
# File lib/eventmachine.rb, line 149 def self.run blk=nil, tail=nil, &block # Obsoleted the use_threads mechanism. # 25Nov06: Added the begin/ensure block. We need to be sure that release_machine # gets called even if an exception gets thrown within any of the user code # that the event loop runs. The best way to see this is to run a unit # test with two functions, each of which calls {EventMachine.run} and each of # which throws something inside of #run. Without the ensure, the second test # will start without release_machine being called and will immediately throw # if @reactor_running and @reactor_pid != Process.pid # Reactor was started in a different parent, meaning we have forked. # Clean up reactor state so a new reactor boots up in this child. stop_event_loop release_machine cleanup_machine @reactor_running = false end tail and @tails.unshift(tail) if reactor_running? (b = blk || block) and b.call # next_tick(b) else @conns = {} @acceptors = {} @timers = {} @wrapped_exception = nil @next_tick_queue ||= [] @tails ||= [] begin initialize_event_machine @reactor_pid = Process.pid @reactor_thread = Thread.current @reactor_running = true (b = blk || block) and add_timer(0, b) if @next_tick_queue && !@next_tick_queue.empty? add_timer(0) { signal_loopbreak } end # Rubinius needs to come back into "Ruby space" for GC to work, # so we'll crank the machine here. if defined?(RUBY_ENGINE) && RUBY_ENGINE == "rbx" while run_machine_once; end else run_machine end ensure until @tails.empty? @tails.pop.call end release_machine cleanup_machine @reactor_running = false @reactor_thread = nil end raise @wrapped_exception if @wrapped_exception end end
Sugars a common use case. Will pass the given block to run, but will terminate the reactor loop and exit the function as soon as the code in the block completes. (Normally, {EventMachine.run} keeps running indefinitely, even after the block supplied to it finishes running, until user code calls {EventMachine.stop})
# File lib/eventmachine.rb, line 218 def self.run_block &block pr = proc { block.call EventMachine::stop } run(&pr) end
The is the responder for the loopback-signalled event. It can be fired either by code running on a separate thread ({EventMachine.defer}) or on the main thread ({EventMachine.next_tick}). It will often happen that a next_tick
handler will reschedule itself. We consume a copy of the tick queue so that tick events scheduled by tick events have to wait for the next pass through the reactor core.
@private
# File lib/eventmachine.rb, line 967 def self.run_deferred_callbacks until (@resultqueue ||= []).empty? result,cback = @resultqueue.pop cback.call result if cback end # Capture the size at the start of this tick... size = @next_tick_mutex.synchronize { @next_tick_queue.size } size.times do |i| callback = @next_tick_mutex.synchronize { @next_tick_queue.shift } begin callback.call rescue exception_raised = true raise ensure # This is a little nasty. The problem is, if an exception occurs during # the callback, then we need to send a signal to the reactor to actually # do some work during the next_tick. The only mechanism we have from the # ruby side is next_tick itself, although ideally, we'd just drop a byte # on the loopback descriptor. next_tick {} if exception_raised end end end
@private
# File lib/em/pure_ruby.rb, line 143 def run_machine Reactor.instance.run end
Runs the given callback on the reactor thread, or immediately if called from the reactor thread. Accepts the same arguments as {EventMachine::Callback}
# File lib/eventmachine.rb, line 233 def self.schedule(*a, &b) cb = Callback(*a, &b) if reactor_running? && reactor_thread? cb.call else next_tick { cb.call } end end
@private
# File lib/em/pure_ruby.rb, line 172 def send_data target, data, datalength selectable = Reactor.instance.get_selectable( target ) or raise "unknown send_data target" selectable.send_data data end
This is currently only for UDP! We need to make it work with unix-domain sockets as well. @private
# File lib/em/pure_ruby.rb, line 231 def send_datagram target, data, datalength, host, port selectable = Reactor.instance.get_selectable( target ) or raise "unknown send_data target" selectable.send_datagram data, Socket::pack_sockaddr_in(port, host) end
@private
# File lib/em/pure_ruby.rb, line 399 def send_file_data sig, filename sz = File.size(filename) raise "file too large" if sz > 32*1024 data = begin File.read filename rescue "" end send_data sig, data, data.length end
@private
# File lib/em/pure_ruby.rb, line 423 def set_comm_inactivity_timeout sig, tm r = Reactor.instance.get_selectable( sig ) or raise "unknown set_comm_inactivity_timeout target" r.set_inactivity_timeout tm end
Sets the maximum number of file or socket descriptors that your process may open. If you call this method with no arguments, it will simply return the current size of the descriptor table without attempting to change it.
The new limit on open descriptors only applies to sockets and other descriptors that belong to EventMachine
. It has **no effect** on the number of descriptors you can create in ordinary Ruby code.
Not available on all platforms. Increasing the number of descriptors beyond its default limit usually requires superuser privileges. (See {.set_effective_user} for a way to drop superuser privileges while your program is running.)
@param [Integer] n_descriptors The maximum number of file or socket descriptors that your process may open @return [Integer] The new descriptor table size.
# File lib/eventmachine.rb, line 1168 def self.set_descriptor_table_size n_descriptors=nil EventMachine::set_rlimit_nofile n_descriptors end
A wrapper over the setuid system call. Particularly useful when opening a network server on a privileged port because you can use this call to drop privileges after opening the port. Also very useful after a call to {.set_descriptor_table_size}, which generally requires that you start your process with root privileges.
This method is intended for use in enforcing security requirements, consequently it will throw a fatal error and end your program if it fails.
@param [String] username The effective name of the user whose privilege-level your process should attain.
@note This method has no effective implementation on Windows or in the pure-Ruby
implementation of EventMachine
# File lib/eventmachine.rb, line 1149 def self.set_effective_user username EventMachine::setuid_string username end
This method is a harmless no-op in pure Ruby, which doesn’t have a built-in limit on the number of available timers. @private
# File lib/em/pure_ruby.rb, line 383 def set_max_timer_count n end
Sets the maximum number of timers and periodic timers that may be outstanding at any given time. You only need to call {.set_max_timers} if you need more than the default number of timers, which on most platforms is 1000.
@note This method has to be used before event loop is started.
@param [Integer] ct Maximum number of timers that may be outstanding at any given time
@see EventMachine.add_timer
@see EventMachine.add_periodic_timer
@see EventMachine::Timer
# File lib/eventmachine.rb, line 917 def self.set_max_timers ct set_max_timer_count ct end
@private
# File lib/em/pure_ruby.rb, line 429 def set_pending_connect_timeout sig, tm # Needs to be implemented. Currently a no-op stub to allow # certain software to operate with the EM pure-ruby. end
For advanced users. This function sets the default timer granularity, which by default is slightly smaller than 100 milliseconds. Call this function to set a higher or lower granularity. The function affects the behavior of {EventMachine.add_timer} and {EventMachine.add_periodic_timer}. Most applications will not need to call this function.
Avoid setting the quantum to very low values because that may reduce performance under some extreme conditions. We recommend that you not use values lower than 10.
This method only can be used if event loop is running.
@param [Integer] mills New timer granularity, in milliseconds
@see EventMachine.add_timer
@see EventMachine.add_periodic_timer
@see EventMachine::Timer
@see EventMachine.run
# File lib/eventmachine.rb, line 902 def self.set_quantum mills set_timer_quantum mills.to_i end
This method is a no-op in the pure-Ruby implementation. We simply return Ruby’s built-in per-process file-descriptor limit. @private
# File lib/em/pure_ruby.rb, line 376 def set_rlimit_nofile n 1024 end
@private
# File lib/em/pure_ruby.rb, line 393 def set_sock_opt signature, level, optname, optval selectable = Reactor.instance.get_selectable( signature ) or raise "unknown set_sock_opt target" selectable.setsockopt level, optname, optval end
Sets reactor quantum in milliseconds. The underlying Reactor
function wants a (possibly fractional) number of seconds. @private
# File lib/em/pure_ruby.rb, line 240 def set_timer_quantum interval Reactor.instance.set_timer_quantum(( 1.0 * interval) / 1000.0) end
This method takes a series of positional arguments for specifying such things as private keys and certificate chains. It’s expected that the parameter list will grow as we add more supported features. ALL of these parameters are optional, and can be specified as empty or nil strings. @private
# File lib/em/pure_ruby.rb, line 264 def set_tls_parms signature, priv_key, cert_chain, verify_peer, fail_if_no_peer_cert, sni_hostname, cipher_list, ecdh_curve, dhparam, protocols_bitmask bitmask = protocols_bitmask ssl_options = OpenSSL::SSL::OP_ALL ssl_options |= OpenSSL::SSL::OP_NO_SSLv2 if defined?(OpenSSL::SSL::OP_NO_SSLv2) && EM_PROTO_SSLv2 & bitmask == 0 ssl_options |= OpenSSL::SSL::OP_NO_SSLv3 if defined?(OpenSSL::SSL::OP_NO_SSLv3) && EM_PROTO_SSLv3 & bitmask == 0 ssl_options |= OpenSSL::SSL::OP_NO_TLSv1 if defined?(OpenSSL::SSL::OP_NO_TLSv1) && EM_PROTO_TLSv1 & bitmask == 0 ssl_options |= OpenSSL::SSL::OP_NO_TLSv1_1 if defined?(OpenSSL::SSL::OP_NO_TLSv1_1) && EM_PROTO_TLSv1_1 & bitmask == 0 ssl_options |= OpenSSL::SSL::OP_NO_TLSv1_2 if defined?(OpenSSL::SSL::OP_NO_TLSv1_2) && EM_PROTO_TLSv1_2 & bitmask == 0 @tls_parms ||= {} @tls_parms[signature] = { :verify_peer => verify_peer, :fail_if_no_peer_cert => fail_if_no_peer_cert, :ssl_options => ssl_options } @tls_parms[signature][:priv_key] = File.read(priv_key) if tls_parm_set?(priv_key) @tls_parms[signature][:cert_chain] = File.read(cert_chain) if tls_parm_set?(cert_chain) @tls_parms[signature][:sni_hostname] = sni_hostname if tls_parm_set?(sni_hostname) @tls_parms[signature][:cipher_list] = cipher_list.gsub(/,\s*/, ':') if tls_parm_set?(cipher_list) @tls_parms[signature][:dhparam] = File.read(dhparam) if tls_parm_set?(dhparam) @tls_parms[signature][:ecdh_curve] = ecdh_curve if tls_parm_set?(ecdh_curve) end
@private
# File lib/em/pure_ruby.rb, line 207 def signal_loopbreak Reactor.instance.signal_loopbreak end
Spawn an erlang-style process
# File lib/em/spawnable.rb, line 69 def self.spawn &block s = SpawnedProcess.new s.set_receiver block s end
@private
# File lib/eventmachine.rb, line 1065 def self.spawn_threadpool until @threadpool.size == @threadpool_size.to_i thread = Thread.new do Thread.current.abort_on_exception = true while true begin op, cback, eback = *@threadqueue.pop rescue ThreadError $stderr.puts $!.message break # Ruby 2.0 may fail at Queue.pop end begin result = op.call @resultqueue << [result, cback] rescue Exception => error raise error unless eback @resultqueue << [error, eback] end signal_loopbreak end end @threadpool << thread end @all_threads_spawned = true end
@private
# File lib/em/pure_ruby.rb, line 251 def ssl? true end
Initiates a TCP server (socket acceptor) on the specified IP address and port.
The IP address must be valid on the machine where the program runs, and the process must be privileged enough to listen on the specified port (on Unix-like systems, superuser privileges are usually required to listen on any port lower than 1024). Only one listener may be running on any given address/port combination. start_server
will fail if the given address and port are already listening on the machine, either because of a prior call to {.start_server} or some unrelated process running on the machine. If {.start_server} succeeds, the new network listener becomes active immediately and starts accepting connections from remote peers, and these connections generate callback events that are processed by the code specified in the handler parameter to {.start_server}.
The optional handler which is passed to this method is the key to EventMachine’s ability to handle particular network protocols. The handler parameter passed to start_server
must be a Ruby Module that you must define. When the network server that is started by start_server
accepts a new connection, it instantiates a new object of an anonymous class that is inherited from {EventMachine::Connection}, *into which your handler module have been included*. Arguments passed into start_server
after the class name are passed into the constructor during the instantiation.
Your handler module may override any of the methods in {EventMachine::Connection}, such as {EventMachine::Connection#receive_data}, in order to implement the specific behavior of the network protocol.
Callbacks invoked in response to network events always take place within the execution context of the object derived from {EventMachine::Connection} extended by your handler module. There is one object per connection, and all of the callbacks invoked for a particular connection take the form of instance methods called against the corresponding {EventMachine::Connection} object. Therefore, you are free to define whatever instance variables you wish, in order to contain the per-connection state required by the network protocol you are implementing.
{EventMachine.start_server} is usually called inside the block passed to {EventMachine.run}, but it can be called from any EventMachine
callback. {EventMachine.start_server} will fail unless the EventMachine
event loop is currently running (which is why it’s often called in the block suppled to {EventMachine.run}).
You may call start_server
any number of times to start up network listeners on different address/port combinations. The servers will all run simultaneously. More interestingly, each individual call to start_server
can specify a different handler module and thus implement a different network protocol from all the others.
@example
require 'rubygems' require 'eventmachine' # Here is an example of a server that counts lines of input from the remote # peer and sends back the total number of lines received, after each line. # Try the example with more than one client connection opened via telnet, # and you will see that the line count increments independently on each # of the client connections. Also very important to note, is that the # handler for the receive_data function, which our handler redefines, may # not assume that the data it receives observes any kind of message boundaries. # Also, to use this example, be sure to change the server and port parameters # to the start_server call to values appropriate for your environment. module LineCounter MaxLinesPerConnection = 10 def post_init puts "Received a new connection" @data_received = "" @line_count = 0 end def receive_data data @data_received << data while @data_received.slice!( /^[^\n]*[\n]/m ) @line_count += 1 send_data "received #{@line_count} lines so far\r\n" @line_count == MaxLinesPerConnection and close_connection_after_writing end end end EventMachine.run { host, port = "192.168.0.100", 8090 EventMachine.start_server host, port, LineCounter puts "Now accepting connections on address #{host}, port #{port}..." EventMachine.add_periodic_timer(10) { $stderr.write "*" } }
@param [String] server Host to bind to. @param [Integer] port Port to bind to. @param [Module, Class] handler A module or class that implements connection callbacks
@note Don’t forget that in order to bind to ports < 1024 on Linux, *BSD and Mac OS X your process must have superuser privileges.
@see file:docs/GettingStarted.md EventMachine
tutorial @see EventMachine.stop_server
# File lib/eventmachine.rb, line 517 def self.start_server server, port=nil, handler=nil, *args, &block begin port = Integer(port) rescue ArgumentError, TypeError # there was no port, so server must be a unix domain socket # the port argument is actually the handler, and the handler is one of the args args.unshift handler if handler handler = port port = nil end if port klass = klass_from_handler(Connection, handler, *args) s = if port start_tcp_server server, port else start_unix_server server end @acceptors[s] = [klass,args,block] s end
@private
# File lib/em/pure_ruby.rb, line 184 def start_tcp_server host, port (s = EvmaTCPServer.start_server host, port) or raise "no acceptor" s.uuid end
# File lib/em/pure_ruby.rb, line 286 def start_tls signature selectable = Reactor.instance.get_selectable(signature) or raise "unknown io selectable for start_tls" tls_parms = @tls_parms[signature] ctx = OpenSSL::SSL::SSLContext.new ctx.options = tls_parms[:ssl_options] ctx.cert = DefaultCertificate.cert ctx.key = DefaultCertificate.key ctx.cert_store = OpenSSL::X509::Store.new ctx.cert_store.set_default_paths ctx.cert = OpenSSL::X509::Certificate.new(tls_parms[:cert_chain]) if tls_parms[:cert_chain] ctx.key = OpenSSL::PKey::RSA.new(tls_parms[:priv_key]) if tls_parms[:priv_key] verify_mode = OpenSSL::SSL::VERIFY_NONE if tls_parms[:verify_peer] verify_mode |= OpenSSL::SSL::VERIFY_PEER end if tls_parms[:fail_if_no_peer_cert] verify_mode |= OpenSSL::SSL::VERIFY_FAIL_IF_NO_PEER_CERT end ctx.verify_mode = verify_mode ctx.servername_cb = Proc.new do |_, server_name| tls_parms[:server_name] = server_name nil end ctx.ciphers = tls_parms[:cipher_list] if tls_parms[:cipher_list] if selectable.is_server ctx.tmp_dh_callback = Proc.new do |_, _, key_length| if tls_parms[:dhparam] OpenSSL::PKey::DH.new(tls_parms[:dhparam]) else case key_length when 1024 then DefaultDHKey1024 when 2048 then DefaultDHKey2048 else nil end end end if tls_parms[:ecdh_curve] && ctx.respond_to?(:tmp_ecdh_callback) ctx.tmp_ecdh_callback = Proc.new do OpenSSL::PKey::EC.new(tls_parms[:ecdh_curve]) end end end ssl_io = OpenSSL::SSL::SSLSocket.new(selectable, ctx) ssl_io.sync_close = true if tls_parms[:sni_hostname] ssl_io.hostname = tls_parms[:sni_hostname] if ssl_io.respond_to?(:hostname=) end begin selectable.is_server ? ssl_io.accept_nonblock : ssl_io.connect_nonblock rescue; end selectable.io = ssl_io end
Start a Unix-domain server.
Note that this is an alias for {EventMachine.start_server}, which can be used to start both TCP and Unix-domain servers.
@see EventMachine.start_server
# File lib/eventmachine.rb, line 561 def self.start_unix_domain_server filename, *args, &block start_server filename, *args, &block end
@private
# File lib/em/pure_ruby.rb, line 196 def start_unix_server chain (s = EvmaUNIXServer.start_server chain) or raise "no acceptor" s.uuid end
@private
# File lib/em/pure_ruby.rb, line 157 def stop Reactor.instance.stop end
Causes the processing loop to stop executing, which will cause all open connections and accepting servers to be run down and closed. Connection
termination callbacks added using {EventMachine.add_shutdown_hook} will be called as part of running this method.
When all of this processing is complete, the call to {EventMachine.run} which started the processing loop will return and program flow will resume from the statement following {EventMachine.run} call.
@example Stopping a running EventMachine
event loop
require 'rubygems' require 'eventmachine' module Redmond def post_init puts "We're sending a dumb HTTP request to the remote peer." send_data "GET / HTTP/1.1\r\nHost: www.microsoft.com\r\n\r\n" end def receive_data data puts "We received #{data.length} bytes from the remote peer." puts "We're going to stop the event loop now." EventMachine::stop_event_loop end def unbind puts "A connection has terminated." end end puts "We're starting the event loop now." EventMachine.run { EventMachine.connect "www.microsoft.com", 80, Redmond } puts "The event loop has stopped." # This program will produce approximately the following output: # # We're starting the event loop now. # We're sending a dumb HTTP request to the remote peer. # We received 1440 bytes from the remote peer. # We're going to stop the event loop now. # A connection has terminated. # The event loop has stopped.
# File lib/eventmachine.rb, line 417 def self.stop_event_loop EventMachine::stop end
Stop a TCP server socket that was started with {EventMachine.start_server}. @see EventMachine.start_server
# File lib/eventmachine.rb, line 551 def self.stop_server signature EventMachine::stop_tcp_server signature end
@private
# File lib/em/pure_ruby.rb, line 190 def stop_tcp_server sig s = Reactor.instance.get_selectable(sig) s.schedule_close end
# File lib/em/pure_ruby.rb, line 152 def stopping? return Reactor.instance.stop_scheduled 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.
# File lib/em/processes.rb, line 112 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] if args.any? EM.get_subprocess_pid(EM.popen(cmd, SystemCmd, cb) do |c| init[c] if init end.signature) end
Creates and immediately starts an EventMachine::TickLoop
# File lib/em/tick_loop.rb, line 3 def self.tick_loop(*a, &b) TickLoop.new(*a, &b).start end
# File lib/em/pure_ruby.rb, line 255 def tls_parm_set?(parm) !(parm.nil? || parm.empty?) end
{EventMachine.watch} registers a given file descriptor or IO
object with the eventloop. The file descriptor will not be modified (it will remain blocking or non-blocking).
The eventloop can be used to process readable and writable events on the file descriptor, using {EventMachine::Connection#notify_readable=} and {EventMachine::Connection#notify_writable=}
{EventMachine::Connection#notify_readable?} and {EventMachine::Connection#notify_writable?} can be used to check what events are enabled on the connection.
To detach the file descriptor, use {EventMachine::Connection#detach}
@example
module SimpleHttpClient def notify_readable header = @io.readline if header == "\r\n" # detach returns the file descriptor number (fd == @io.fileno) fd = detach end rescue EOFError detach end def unbind EM.next_tick do # socket is detached from the eventloop, but still open data = @io.read end end end EventMachine.run { sock = TCPSocket.new('site.com', 80) sock.write("GET / HTTP/1.0\r\n\r\n") conn = EventMachine.watch(sock, SimpleHttpClient) conn.notify_readable = true }
@author Riham Aldakkak (eSpace Technologies)
# File lib/eventmachine.rb, line 731 def EventMachine::watch io, handler=nil, *args, &blk attach_io io, true, handler, *args, &blk end
EventMachine’s file monitoring API. Currently supported are the following events on individual files, using inotify on Linux systems, and kqueue for *BSD and Mac OS X:
-
File modified (written to)
-
File moved/renamed
-
File deleted
EventMachine::watch_file
takes a filename and a handler Module containing your custom callback methods. This will setup the low level monitoring on the specified file, and create a new EventMachine::FileWatch
object with your Module mixed in. FileWatch
is a subclass of {EventMachine::Connection}, so callbacks on this object work in the familiar way. The callbacks that will be fired by EventMachine
are:
-
file_modified
-
file_moved
-
file_deleted
You can access the filename being monitored from within this object using {FileWatch#path}.
When a file is deleted, {FileWatch#stop_watching} will be called after your file_deleted callback, to clean up the underlying monitoring and remove EventMachine’s reference to the now-useless {FileWatch} instance. This will in turn call unbind, if you wish to use it.
The corresponding system-level Errno will be raised when attempting to monitor non-existent files, files with wrong permissions, or if an error occurs dealing with inotify/kqueue.
@example
# Before running this example, make sure we have a file to monitor: # $ echo "bar" > /tmp/foo module Handler def file_modified puts "#{path} modified" end def file_moved puts "#{path} moved" end def file_deleted puts "#{path} deleted" end def unbind puts "#{path} monitoring ceased" end end # for efficient file watching, use kqueue on Mac OS X EventMachine.kqueue = true if EventMachine.kqueue? EventMachine.run { EventMachine.watch_file("/tmp/foo", Handler) } # $ echo "baz" >> /tmp/foo => "/tmp/foo modified" # $ mv /tmp/foo /tmp/oof => "/tmp/foo moved" # $ rm /tmp/oof => "/tmp/foo deleted"
@note The ability to pick up on the new filename after a rename is not yet supported.
Calling #path will always return the filename you originally used.
@param [String] filename Local path to the file to watch. @param [Class, Module] handler A class or module that implements event handlers associated with the file.
# File lib/eventmachine.rb, line 1309 def self.watch_file(filename, handler=nil, *args) klass = klass_from_handler(FileWatch, handler, *args) s = EM::watch_filename(filename) c = klass.new s, *args # we have to set the path like this because of how Connection.new works c.instance_variable_set("@path", filename) @conns[s] = c block_given? and yield c c end
EventMachine’s process monitoring API. On Mac OS X and *BSD this method is implemented using kqueue.
@example
module ProcessWatcher def process_exited put 'the forked child died!' end end pid = fork{ sleep } EventMachine.run { EventMachine.watch_process(pid, ProcessWatcher) EventMachine.add_timer(1){ Process.kill('TERM', pid) } }
@param [Integer] pid PID of the process to watch. @param [Class, Module] handler A class or module that implements event handlers associated with the file.
# File lib/eventmachine.rb, line 1340 def self.watch_process(pid, handler=nil, *args) pid = pid.to_i klass = klass_from_handler(ProcessWatch, handler, *args) s = EM::watch_pid(pid) c = klass.new s, *args # we have to set the path like this because of how Connection.new works c.instance_variable_set("@pid", pid) @conns[s] = c block_given? and yield c c end
@private
# File lib/em/spawnable.rb, line 76 def self.yield &block return YieldBlockFromSpawnedProcess.new( block, false ) end
@private
# File lib/em/spawnable.rb, line 81 def self.yield_and_notify &block return YieldBlockFromSpawnedProcess.new( block, true ) end