Module EventMachine
In: lib/eventmachine.rb
lib/em/timers.rb
lib/em/connection.rb
lib/em/processes.rb
lib/em/queue.rb
lib/em/completion.rb
lib/em/tick_loop.rb
lib/em/iterator.rb
lib/em/protocols/saslauth.rb
lib/em/protocols/object_protocol.rb
lib/em/protocols/header_and_content.rb
lib/em/protocols/line_and_text.rb
lib/em/protocols/tcptest.rb
lib/em/protocols/linetext2.rb
lib/em/protocols/socks4.rb
lib/em/protocols/memcache.rb
lib/em/protocols/httpclient.rb
lib/em/protocols/smtpserver.rb
lib/em/protocols/smtpclient.rb
lib/em/protocols/postgres3.rb
lib/em/protocols/line_protocol.rb
lib/em/protocols/httpclient2.rb
lib/em/protocols/stomp.rb
lib/em/file_watch.rb
lib/em/spawnable.rb
lib/em/pool.rb
lib/em/deferrable.rb
lib/em/channel.rb
lib/em/callback.rb
lib/em/threaded_resource.rb
lib/em/streamer.rb
lib/em/future.rb
lib/em/pure_ruby.rb
lib/em/protocols.rb
lib/em/resolver.rb
lib/em/process_watch.rb

@private

Methods

Classes and Modules

Module EventMachine::DNS
Module EventMachine::Deferrable
Module EventMachine::Protocols
Module EventMachine::UuidGenerator
Class EventMachine::Channel
Class EventMachine::Completion
Class EventMachine::Connection
Class EventMachine::DatagramObject
Class EventMachine::DefaultDeferrable
Class EventMachine::DeferrableChildProcess
Class EventMachine::Error
Class EventMachine::EvmaKeyboard
Class EventMachine::EvmaTCPClient
Class EventMachine::EvmaTCPServer
Class EventMachine::EvmaUDPSocket
Class EventMachine::EvmaUNIXClient
Class EventMachine::EvmaUNIXServer
Class EventMachine::FileNotFoundException
Class EventMachine::FileStreamer
Class EventMachine::FileWatch
Class EventMachine::Iterator
Class EventMachine::LoopbreakReader
Class EventMachine::PeriodicTimer
Class EventMachine::Pool
Class EventMachine::ProcessWatch
Class EventMachine::Queue
Class EventMachine::Reactor
Class EventMachine::Selectable
Class EventMachine::SpawnedProcess
Class EventMachine::StreamObject
Class EventMachine::SystemCmd
Class EventMachine::ThreadedResource
Class EventMachine::TickLoop
Class EventMachine::Timer
Class EventMachine::YieldBlockFromSpawnedProcess

Constants

ERRNOS = Errno::constants.grep(/^E/).inject(Hash.new(:unknown)) { |hash, name| errno = Errno.__send__(:const_get, name)   System errnos @private
TimerFired = 100   @private
ConnectionData = 101   @private
ConnectionUnbound = 102   @private
ConnectionAccepted = 103   @private
ConnectionCompleted = 104   @private
LoopbreakSignalled = 105   @private

Attributes

reactor_thread  [R]  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]

threadpool  [R]  @private
threadpool_size  [RW]  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>]

Changed 04Oct06: intervals from the caller are now in milliseconds, but our native-ruby processor still wants them in seconds. @private

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

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

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

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.

This method is like {EventMachine.connect}, but allows for a local address/port to bind the connection to.

@see EventMachine.connect

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

The extension version does NOT raise any kind of an error if an attempt is made to close a non-existent connection. Not sure whether we should. For now, we‘ll raise an error here in that case. @private

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

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.

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.

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.

## 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.

@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.
 }

 EventMachine.defer(operation, callback)

@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.

@see EventMachine.threadpool_size

Returns true if all deferred actions are done executing and their callbacks have been fired.

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

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

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

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

Forks a new process, properly stops the reactor and then calls {EventMachine.run} inside of it again, passing your block.

Gets the current maximum number of allowed timers

@return [Integer] Maximum number of timers that may be outstanding at any given time

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

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

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

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

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.

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

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

@return [Boolean] true if the calling thread is the same thread as the reactor.

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

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})

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

Runs the given callback on the reactor thread, or immediately if called from the reactor thread. Accepts the same arguments as {EventMachine::Callback}

This is currently only for UDP! We need to make it work with unix-domain sockets as well. @private

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.

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

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

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

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

This method is a no-op in the pure-Ruby implementation. We simply return Ruby‘s built-in per-process file-descriptor limit. @private

Sets reactor quantum in milliseconds. The underlying Reactor function wants a (possibly fractional) number of seconds. @private

Spawn an erlang-style process

This method is not implemented for pure-Ruby implementation @private

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

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

@private

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.

Stop a TCP server socket that was started with {EventMachine.start_server}. @see EventMachine.start_server

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.

Creates and immediately starts an EventMachine::TickLoop

{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)

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.

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.

[Validate]