Method: EventMachine.start_server

Defined in:

lib/eventmachine.rb

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

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.

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 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 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 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 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 usually called inside the block passed to 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 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.

Examples:

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

Parameters:

• server (String) —

  Host to bind to.

• port (Integer) (defaults to: nil) —

  Port to bind to.

• handler (Module, Class) (defaults to: nil) —

  A module or class that implements connection callbacks

See Also:

• EventMachine tutorial
• 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