careo-eventmachine

$Id$

= RUBY/EventMachine

Homepage:: http://rubyeventmachine.com Copyright:: (C) 2006-07 by Francis Cianfrocca. All Rights Reserved. Email:: gmail address: garbagecat10

EventMachine is copyrighted free software made available under the terms of either the GPL or Ruby's License. See the file COPYING for full licensing information. See EventMachine and EventMachine::Connection for documentation and usage examples.

EventMachine implements a fast, single-threaded engine for arbitrary network communications. It's extremely easy to use in Ruby. EventMachine wraps all interactions with IP sockets, allowing programs to concentrate on the implementation of network protocols. It can be used to create both network servers and clients. To create a server or client, a Ruby program only needs to specify the IP address and port, and provide a Module that implements the communications protocol. Implementations of several standard network protocols are provided with the package, primarily to serve as examples. The real goal of EventMachine is to enable programs to easily interface with other programs using TCP/IP, especially if custom protocols are required.

A Ruby program uses EventMachine by registering the addresses and ports of network servers and clients, and then entering an event-handling loop. EventMachine contains glue code in Ruby which will execute callbacks to user-supplied code for all significant events occurring in the clients and servers. These events include connection acceptance, startup, data-receipt, shutdown, and timer events. Arbitrary processing can be performed by user code during event callbacks, including sending data to one or more remote network peers, startup and shutdown of network connections, and installation of new event handlers.

The EventMachine implements a very familiar model for network programming. It emphasizes: 1) the maximum possible isolation of user code from network objects like sockets; 2) maximum performance and scalability; and 3) extreme ease-of-use for user code. It attempts to provide a higher-level interface than similar projects which expose a variety of low-level event-handling and networking objects to Ruby programs.

The design and implementation of EventMachine grows out of nearly ten years of experience writing high-performance, high-scaling network server applications. We have taken particular account of the challenges and lessons described as the "C10K problem" by Dan Kegel and others.

EventMachine consists of an extension library written in C++ (which can be accessed from languages other than Ruby), and a Ruby module which can be dropped into user programs. On most platforms, EventMachine uses the select(2) system call, so it will run on a large range of Unix-like systems and on Microsoft Windows with good performance and scalability. On Linux 2.6 kernels, EventMachine automatically configures itself to use epoll(4) instead of select(2), so scalability on that platform can be significantly improved.

Here's a fully-functional echo server written with EventMachine:

  require 'rubygems'
  require 'eventmachine'

  module EchoServer
    def receive_data data
      send_data ">>>you sent: #{data}"
      close_connection if data =~ /quit/i
    end
  end

  EventMachine::run {
    EventMachine::start_server "192.168.0.100", 8081, EchoServer
  }