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 |
|
---|