root/trunk/docs/PURE_RUBY

Revision 788, 3.6 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 EventMachine is supplied in three alternative versions.
4
5 1) A version that includes a Ruby extension written in C++. This version requires compilation;
6 2) A version for JRuby that contains a precompiled JAR file written in Java;
7 3) A pure Ruby version that has no external dependencies and can run in any Ruby environment.
8
9 The Java version of EventMachine is packaged in a distinct manner and must be installed using a
10 special procedure. This version is described fully in a different document, and not considered
11 further here.
12
13 The C++ and pure-Ruby versions, however, are shipped in the same distribution. You use the same
14 files (either tarball or Ruby gem) to install both of these versions.
15
16 If you intend to use the C++ version, you must successfully compile EventMachine after you install it.
17 (The gem installation attempts to perform this step automatically.)
18
19 If you choose not to compile the EventMachine C++ extension, or if your compilation fails for any
20 reason, you still have a fully-functional installation of the pure-Ruby version of EM.
21
22 However, for technical reasons, a default EM installation (whether or not the compilation succeeds)
23 will always assume that the compiled ("extension") implementation should be used.
24
25 If you want your EM program to use the pure Ruby version, you must specifically request it. There
26 are two ways to do this: by setting either a Ruby global variable, or an environment string.
27
28 The following code will invoke the pure-Ruby implementation of EM:
29
30  $eventmachine_library = :pure_ruby
31  require 'eventmachine'
32
33  EM.library_type #=> "pure_ruby"
34
35 Notice that this requires a code change and is not the preferred way to select pure Ruby, unless
36 for some reason you are absolutely sure you will never want the compiled implementation.
37
38 Setting the following environment string has the same effect:
39
40  export EVENTMACHINE_LIBRARY="pure_ruby"
41
42 This technique gives you the flexibility to select either version at runtime with no code changes.
43
44 Support
45
46 The EventMachine development team has committed to support precisely the same APIs for all the
47 various implementations of EM.
48
49 This means that you can expect any EM program to behave identically, whether you use pure Ruby,
50 the compiled C++ extension, or JRuby. Deviations from this behavior are to be considered bugs
51 and should be reported as such.
52
53 There is a small number of exceptions to this rule, which arise from underlying platform
54 distinctions. Notably, EM#epoll is a silent no-op in the pure Ruby implementation.
55
56
57 When Should You Use the Pure-Ruby Implementation of EM?
58
59
60 Use the pure Ruby implementation of EM when you must support a platform for which no C++ compiler
61 is available, or on which the standard EM C++ code can't be compiled.
62
63 Keep in mind that you don't need a C++ compiler in order to deploy EM applications that rely on
64 the compiled version, so long as appropriate C++ runtime libraries are available on the target platform.
65
66 In extreme cases, you may find that you can develop software with the compiled EM version, but are
67 not allowed to install required runtime libraries on the deployment system(s). This would be another
68 case in which the pure Ruby implementation can be useful.
69
70 In general you should avoid the pure Ruby version of EM when performance and scalability are important.
71 EM in pure Ruby will necessarily run slower than the compiled version. Depending on your application
72 this may or may not be a key issue.
73
74 Also, since EPOLL is not supported in pure Ruby, your applications will be affected by Ruby's built-in
75 limit of 1024 file and socket descriptors that may be open in a single process. For maximum scalability
76 and performance, always use EPOLL if possible.
77
Note: See TracBrowser for help on using the browser.