Method: EventMachine.start_server

Defined in:

lib/eventmachine.rb

.start_server(server, port = nil, handler = nil, *args, &block) ⇒ Object

EventMachine::start_server 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 start_server 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 the methods from your handler have been mixed. Your handler module may redefine any of the methods in EventMachine::Connection 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.

start_server is often called inside the block passed to EventMachine::run, but it can be called from any EventMachine callback. 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.

Usage example

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.

require 'rubygems'
require 'eventmachine'

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 "*" }
}

# File 'lib/eventmachine.rb', line 540

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 = if (handler and handler.is_a?(Class))
    raise ArgumentError, 'must provide module or subclass of EventMachine::Connection' unless Connection > handler
    handler
  else
    Class.new( Connection ) {handler and include handler}
  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

  s = if port
        start_tcp_server server, port
      else
        start_unix_server server
      end
  @acceptors[s] = [klass,args,block]
  s
end