root/trunk/docs/README

Revision 788, 3.3 kB (checked in by raggi, 8 months ago)

Merge of branches/raggi
Most notable work and patches by Aman Gupta, Roger Pack, and James Tucker.
Patches / Tickets also submitted by: Jeremy Evans, aanand, darix, mmmurf,
danielaquino, macournoyer.

  • Moved docs into docs/ dir
  • Major refactor of rakefile, added generic rakefile helpers in tasks
  • Added example CPP build rakefile in tasks/cpp.rake
  • Moved rake tests out to tasks/tests.rake
  • Added svn ignores where appropriate
  • Fixed jruby build on older java platforms
  • Gem now builds from Rakefile rather than directly via extconf
  • Gem unified for jruby, C++ and pure ruby.
  • Correction for pure C++ build, removing ruby dependency
  • Fix for CYGWIN builds on ipv6
  • Major refactor for extconf.rb
  • Working mingw builds
  • extconf optionally uses pkg_config over manual configuration
  • extconf builds for 1.9 on any system that has 1.9
  • extconf no longer links pthread explicitly
  • looks for kqueue on all *nix systems
  • better error output on std::runtime_error, now says where it came from
  • Fixed some tests on jruby
  • Added test for general send_data flaw, required for a bugfix in jruby build
  • Added timeout to epoll tests
  • Added fixes for java reactor ruby api
  • Small addition of some docs in httpclient.rb and httpcli2.rb
  • Some refactor and fixes in smtpserver.rb
  • Added parenthesis where possible to avoid excess ruby warnings
  • Refactor of $eventmachine_library logic for accuracy and maintenance, jruby
  • EM::start_server now supports unix sockets
  • EM::connect now supports unix sockets
  • EM::defer @threadqueue now handled more gracefully
  • Added better messages on exceptions raised
  • Fix edge case in timer fires
  • Explicitly require buftok.rb
  • Add protocols to autoload, rather than require them all immediately
  • Fix a bug in pr_eventmachine for outbound_q
  • Refactors to take some of the use of defer out of tests.
  • Fixes in EM.defer under start/stop conditions. Reduced scope of threads.
  • Property svn:keywords set to Id
Line 
1 $Id$
2
3 = RUBY/EventMachine
4
5 Homepage::  http://rubyeventmachine.com
6 Copyright:: (C) 2006-07 by Francis Cianfrocca. All Rights Reserved.
7 Email:: gmail address: garbagecat10
8
9 EventMachine is copyrighted free software made available under the terms
10 of either the GPL or Ruby's License. See the file COPYING for full licensing
11 information.
12 See EventMachine and EventMachine::Connection for documentation and
13 usage examples.
14
15 EventMachine implements a fast, single-threaded engine for arbitrary network
16 communications. It's extremely easy to use in Ruby. EventMachine wraps all
17 interactions with IP sockets, allowing programs to concentrate on the
18 implementation of network protocols. It can be used to create both network
19 servers and clients. To create a server or client, a Ruby program only needs
20 to specify the IP address and port, and provide a Module that implements the
21 communications protocol. Implementations of several standard network protocols
22 are provided with the package, primarily to serve as examples. The real goal
23 of EventMachine is to enable programs to easily interface with other programs
24 using TCP/IP, especially if custom protocols are required.
25
26 A Ruby program uses EventMachine by registering the addresses and ports of
27 network servers and clients, and then entering an event-handling loop.
28 EventMachine contains glue code in Ruby which will execute callbacks to
29 user-supplied code for all significant events occurring in the clients
30 and servers. These events include connection acceptance, startup, data-receipt,
31 shutdown, and timer events. Arbitrary processing can be performed by user code
32 during event callbacks, including sending data to one or more remote network
33 peers, startup and shutdown of network connections, and installation of new
34 event handlers.
35
36 The EventMachine implements a very familiar model for network programming.
37 It emphasizes: 1) the maximum possible isolation of user code from network
38 objects like sockets; 2) maximum performance and scalability; and 3) extreme
39 ease-of-use for user code. It attempts to provide a higher-level interface
40 than similar projects which expose a variety of low-level event-handling
41 and networking objects to Ruby programs.
42
43 The design and implementation of EventMachine grows out of nearly ten years
44 of experience writing high-performance, high-scaling network server applications.
45 We have taken particular account of the challenges and lessons described as
46 the "C10K problem" by Dan Kegel and others.
47
48 EventMachine consists of an extension library written in C++ (which can be
49 accessed from languages other than Ruby), and a Ruby module which can be dropped
50 into user programs. On most platforms, EventMachine uses the
51 <tt>select(2)</tt> system call,
52 so it will run on a large range of Unix-like systems and on Microsoft
53 Windows with good performance and scalability. On Linux 2.6 kernels, EventMachine
54 automatically configures itself to use <tt>epoll(4)</tt> instead of
55 <tt>select(2),</tt> so scalability on that platform can be significantly
56 improved.
57
58 Here's a fully-functional echo server written with EventMachine:
59
60       require 'rubygems'
61       require 'eventmachine'
62
63       module EchoServer
64         def receive_data data
65           send_data ">>>you sent: #{data}"
66           close_connection if data =~ /quit/i
67         end
68       end
69
70       EventMachine::run {
71         EventMachine::start_server "192.168.0.100", 8081, EchoServer
72       }
73
74
Note: See TracBrowser for help on using the browser.