eventmachine 1.0.0.beta.2-x86-mingw32
Sign up to get free protection for your applications and to get access to all the features.
- data/.gitignore +16 -0
- data/Gemfile +1 -0
- data/README +81 -0
- data/Rakefile +11 -0
- data/docs/COPYING +60 -0
- data/docs/ChangeLog +211 -0
- data/docs/DEFERRABLES +246 -0
- data/docs/EPOLL +141 -0
- data/docs/GNU +281 -0
- data/docs/INSTALL +13 -0
- data/docs/KEYBOARD +42 -0
- data/docs/LEGAL +25 -0
- data/docs/LIGHTWEIGHT_CONCURRENCY +130 -0
- data/docs/PURE_RUBY +75 -0
- data/docs/RELEASE_NOTES +94 -0
- data/docs/SMTP +4 -0
- data/docs/SPAWNED_PROCESSES +148 -0
- data/docs/TODO +8 -0
- data/eventmachine.gemspec +33 -0
- data/examples/ex_channel.rb +43 -0
- data/examples/ex_queue.rb +2 -0
- data/examples/ex_tick_loop_array.rb +15 -0
- data/examples/ex_tick_loop_counter.rb +32 -0
- data/examples/helper.rb +2 -0
- data/ext/binder.cpp +124 -0
- data/ext/binder.h +46 -0
- data/ext/cmain.cpp +838 -0
- data/ext/ed.cpp +1884 -0
- data/ext/ed.h +418 -0
- data/ext/em.cpp +2348 -0
- data/ext/em.h +228 -0
- data/ext/eventmachine.h +123 -0
- data/ext/extconf.rb +157 -0
- data/ext/fastfilereader/extconf.rb +85 -0
- data/ext/fastfilereader/mapper.cpp +214 -0
- data/ext/fastfilereader/mapper.h +59 -0
- data/ext/fastfilereader/rubymain.cpp +127 -0
- data/ext/kb.cpp +79 -0
- data/ext/page.cpp +107 -0
- data/ext/page.h +51 -0
- data/ext/pipe.cpp +347 -0
- data/ext/project.h +155 -0
- data/ext/rubymain.cpp +1200 -0
- data/ext/ssl.cpp +460 -0
- data/ext/ssl.h +94 -0
- data/java/.classpath +8 -0
- data/java/.project +17 -0
- data/java/src/com/rubyeventmachine/EmReactor.java +571 -0
- data/java/src/com/rubyeventmachine/EmReactorException.java +40 -0
- data/java/src/com/rubyeventmachine/EventableChannel.java +69 -0
- data/java/src/com/rubyeventmachine/EventableDatagramChannel.java +189 -0
- data/java/src/com/rubyeventmachine/EventableSocketChannel.java +364 -0
- data/lib/em/buftok.rb +138 -0
- data/lib/em/callback.rb +26 -0
- data/lib/em/channel.rb +57 -0
- data/lib/em/connection.rb +569 -0
- data/lib/em/deferrable.rb +206 -0
- data/lib/em/file_watch.rb +54 -0
- data/lib/em/future.rb +61 -0
- data/lib/em/iterator.rb +270 -0
- data/lib/em/messages.rb +66 -0
- data/lib/em/process_watch.rb +44 -0
- data/lib/em/processes.rb +119 -0
- data/lib/em/protocols.rb +36 -0
- data/lib/em/protocols/header_and_content.rb +138 -0
- data/lib/em/protocols/httpclient.rb +268 -0
- data/lib/em/protocols/httpclient2.rb +590 -0
- data/lib/em/protocols/line_and_text.rb +125 -0
- data/lib/em/protocols/line_protocol.rb +28 -0
- data/lib/em/protocols/linetext2.rb +161 -0
- data/lib/em/protocols/memcache.rb +323 -0
- data/lib/em/protocols/object_protocol.rb +45 -0
- data/lib/em/protocols/postgres3.rb +247 -0
- data/lib/em/protocols/saslauth.rb +175 -0
- data/lib/em/protocols/smtpclient.rb +357 -0
- data/lib/em/protocols/smtpserver.rb +640 -0
- data/lib/em/protocols/socks4.rb +66 -0
- data/lib/em/protocols/stomp.rb +200 -0
- data/lib/em/protocols/tcptest.rb +53 -0
- data/lib/em/pure_ruby.rb +1013 -0
- data/lib/em/queue.rb +62 -0
- data/lib/em/spawnable.rb +85 -0
- data/lib/em/streamer.rb +130 -0
- data/lib/em/tick_loop.rb +85 -0
- data/lib/em/timers.rb +57 -0
- data/lib/em/version.rb +3 -0
- data/lib/eventmachine.rb +1548 -0
- data/lib/jeventmachine.rb +258 -0
- data/lib/rubyeventmachine.rb +2 -0
- data/setup.rb +1585 -0
- data/tasks/cpp.rake_example +77 -0
- data/tasks/doc.rake +30 -0
- data/tasks/package.rake +85 -0
- data/tasks/test.rake +6 -0
- data/tests/client.crt +31 -0
- data/tests/client.key +51 -0
- data/tests/test_attach.rb +136 -0
- data/tests/test_basic.rb +249 -0
- data/tests/test_channel.rb +64 -0
- data/tests/test_connection_count.rb +35 -0
- data/tests/test_defer.rb +49 -0
- data/tests/test_deferrable.rb +35 -0
- data/tests/test_epoll.rb +160 -0
- data/tests/test_error_handler.rb +35 -0
- data/tests/test_errors.rb +82 -0
- data/tests/test_exc.rb +55 -0
- data/tests/test_file_watch.rb +49 -0
- data/tests/test_futures.rb +198 -0
- data/tests/test_get_sock_opt.rb +30 -0
- data/tests/test_handler_check.rb +37 -0
- data/tests/test_hc.rb +190 -0
- data/tests/test_httpclient.rb +227 -0
- data/tests/test_httpclient2.rb +154 -0
- data/tests/test_inactivity_timeout.rb +50 -0
- data/tests/test_kb.rb +60 -0
- data/tests/test_ltp.rb +190 -0
- data/tests/test_ltp2.rb +317 -0
- data/tests/test_next_tick.rb +133 -0
- data/tests/test_object_protocol.rb +37 -0
- data/tests/test_pause.rb +70 -0
- data/tests/test_pending_connect_timeout.rb +48 -0
- data/tests/test_process_watch.rb +50 -0
- data/tests/test_processes.rb +128 -0
- data/tests/test_proxy_connection.rb +144 -0
- data/tests/test_pure.rb +134 -0
- data/tests/test_queue.rb +44 -0
- data/tests/test_running.rb +42 -0
- data/tests/test_sasl.rb +72 -0
- data/tests/test_send_file.rb +251 -0
- data/tests/test_servers.rb +76 -0
- data/tests/test_smtpclient.rb +83 -0
- data/tests/test_smtpserver.rb +85 -0
- data/tests/test_spawn.rb +322 -0
- data/tests/test_ssl_args.rb +79 -0
- data/tests/test_ssl_methods.rb +50 -0
- data/tests/test_ssl_verify.rb +82 -0
- data/tests/test_tick_loop.rb +59 -0
- data/tests/test_timers.rb +160 -0
- data/tests/test_ud.rb +36 -0
- data/tests/testem.rb +31 -0
- metadata +240 -0
data/docs/LEGAL
ADDED
@@ -0,0 +1,25 @@
|
|
1
|
+
LEGAL NOTICE INFORMATION
|
2
|
+
------------------------
|
3
|
+
|
4
|
+
EventMachine is Copyright (C) 2006-07 by Francis Cianfrocca.
|
5
|
+
|
6
|
+
EventMachine is copyrighted software owned by Francis Cianfrocca
|
7
|
+
(blackhedd ... gmail.com). You may redistribute and/or modify this
|
8
|
+
software as long as you comply with either the terms of the GPL
|
9
|
+
(see the file GPL), or Ruby's license (see the file COPYING).
|
10
|
+
|
11
|
+
Your use of all the files in this distribution is controlled by these
|
12
|
+
license terms, except for those files specifically mentioned below:
|
13
|
+
|
14
|
+
|
15
|
+
|
16
|
+
setup.rb
|
17
|
+
This file is Copyright (C) 2000-2005 by Minero Aoki
|
18
|
+
You can distribute/modify this file under the terms of
|
19
|
+
the GNU LGPL, Lesser General Public License version 2.1.
|
20
|
+
|
21
|
+
|
22
|
+
lib/em/buftok.rb
|
23
|
+
This file is Copyright (C) 2007 by Tony Arcieri. This file is
|
24
|
+
covered by the terms of Ruby's License (see the file COPYING).
|
25
|
+
|
@@ -0,0 +1,130 @@
|
|
1
|
+
EventMachine (EM) adds two different formalisms for lightweight concurrency to
|
2
|
+
the Ruby programmer's toolbox: spawned processes and deferrables. This note
|
3
|
+
will show you how to use them.
|
4
|
+
|
5
|
+
|
6
|
+
=== What is Lightweight Concurrency?
|
7
|
+
|
8
|
+
We use the term "Lightweight Concurrency" (LC) to refer to concurrency
|
9
|
+
mechanisms that are lighter than Ruby threads. By "lighter," we mean: less
|
10
|
+
resource-intensive in one or more dimensions, usually including memory and
|
11
|
+
CPU usage. In general, you turn to LC in the hope of improving the
|
12
|
+
performance and scalability of your programs.
|
13
|
+
|
14
|
+
In addition to the two EventMachine mechanisms we will discuss here, Ruby
|
15
|
+
has at least one other LC construct: Fibers, which are currently under
|
16
|
+
development in Ruby 1.9.
|
17
|
+
|
18
|
+
The technical feature that makes all of these LC mechanisms different from
|
19
|
+
standard Ruby threads is that they are not scheduled automatically.
|
20
|
+
|
21
|
+
When you create and run Ruby threads, you can assume (within certain
|
22
|
+
constraints) that your threads will all be scheduled fairly by Ruby's runtime.
|
23
|
+
Ruby itself is responsible for giving each of your threads its own share of
|
24
|
+
the total runtime.
|
25
|
+
|
26
|
+
But with LC, your program is responsible for causing different execution
|
27
|
+
paths to run. In effect, your program has to act as a "thread scheduler."
|
28
|
+
Scheduled entities in LC run to completion and are never preempted. The
|
29
|
+
runtime system has far less work to do since it has no need to interrupt
|
30
|
+
threads or to schedule them fairly. This is what makes LC lighter and faster.
|
31
|
+
|
32
|
+
You'll learn exactly how LC scheduling works in practice as we work through
|
33
|
+
specific examples.
|
34
|
+
|
35
|
+
|
36
|
+
=== EventMachine Lightweight Concurrency
|
37
|
+
|
38
|
+
Recall that EM provides a reactor loop that must be running in order for
|
39
|
+
your programs to perform event-driven logic. An EM program typically has a
|
40
|
+
structure like this:
|
41
|
+
|
42
|
+
require 'eventmachine'
|
43
|
+
|
44
|
+
# your initializations
|
45
|
+
|
46
|
+
EM.run {
|
47
|
+
# perform event-driven I/O here, including network clients,
|
48
|
+
# servers, timers, and thread-pool operations.
|
49
|
+
}
|
50
|
+
|
51
|
+
# your cleanup
|
52
|
+
# end of the program
|
53
|
+
|
54
|
+
|
55
|
+
EventMachine#run executes the reactor loop, which causes your code to be
|
56
|
+
called as events of interest to your program occur. The block you pass to
|
57
|
+
EventMachine#run is executed right after the reactor loop starts, and is
|
58
|
+
the right place to start socket acceptors, etc.
|
59
|
+
|
60
|
+
Because the reactor loop runs constantly in an EM program (until it is
|
61
|
+
stopped by a call to EventMachine#stop), it has the ability to schedule
|
62
|
+
blocks of code for asynchronous execution. Unlike a pre-emptive thread
|
63
|
+
scheduler, it's NOT able to interrupt code blocks while they execute. But
|
64
|
+
the scheduling capability it does have is enough to enable lightweight
|
65
|
+
concurrency.
|
66
|
+
|
67
|
+
|
68
|
+
For information on Spawned Processes, see the separate document
|
69
|
+
SPAWNED_PROCESSES.
|
70
|
+
|
71
|
+
For information on Deferrables, see the separate document DEFERRABLES.
|
72
|
+
|
73
|
+
|
74
|
+
=== [SIDEBAR]: I Heard That EventMachine Doesn't Work With Ruby Threads.
|
75
|
+
|
76
|
+
This is incorrect. EM is fully interoperable with all versions of Ruby
|
77
|
+
threads, and has been since its earliest releases.
|
78
|
+
|
79
|
+
It's very true that EM encourages an "evented" (non-threaded) programming
|
80
|
+
style. The specific benefits of event-driven programming are far better
|
81
|
+
performance and scalability for well-written programs, and far easier
|
82
|
+
debugging.
|
83
|
+
|
84
|
+
The benefit of using threads for similar applications is a possibly more
|
85
|
+
intuitive programming model, as well as the fact that threads are already
|
86
|
+
familiar to most programmers. Also, bugs in threaded programs often fail
|
87
|
+
to show up until programs go into production. These factors create the
|
88
|
+
illusion that threaded programs are easier to write.
|
89
|
+
|
90
|
+
However, some operations that occur frequently in professional-caliber
|
91
|
+
applications simply can't be done without threads. (The classic example
|
92
|
+
is making calls to database client-libraries that block on network I/O
|
93
|
+
until they complete.)
|
94
|
+
|
95
|
+
EventMachine not only allows the use of Ruby threads in these cases, but
|
96
|
+
it even provides a built-in thread-pool object to make them easier to
|
97
|
+
work with.
|
98
|
+
|
99
|
+
You may have heard a persistent criticism that evented I/O is fundamentally
|
100
|
+
incompatible with Ruby threads. It is true that some well-publicized attempts
|
101
|
+
to incorporate event-handling libraries into Ruby were not successful. But
|
102
|
+
EventMachine was designed from the ground up with Ruby compatibility in mind,
|
103
|
+
so EM never suffered from the problems that defeated the earlier attempts.
|
104
|
+
|
105
|
+
|
106
|
+
=== [SIDEBAR]: I Heard That EventMachine Doesn't Work Very Well On Windows.
|
107
|
+
|
108
|
+
This too is incorrect. EventMachine is an extension written in C++ and Java,
|
109
|
+
and therefore it requires compilation. Many Windows computers (and some Unix
|
110
|
+
computers, especially in production environments) don't have a build stack.
|
111
|
+
Attempting to install EventMachine on a machine without a compiler usually
|
112
|
+
produces a confusing error.
|
113
|
+
|
114
|
+
In addition, Ruby has a much-debated issue with Windows compiler versions.
|
115
|
+
Ruby on Windows works best with Visual Studio 6, a compiler version that is
|
116
|
+
long out-of-print, no longer supported by Microsoft, and difficult to obtain.
|
117
|
+
(This problem is not specific to EventMachine.)
|
118
|
+
|
119
|
+
Shortly after EventMachine was first released, the compiler issues led to
|
120
|
+
criticism that EM was incompatible with Windows. Since that time, every
|
121
|
+
EventMachine release has been supplied in a precompiled binary form for
|
122
|
+
Windows users, that does not require you to compile the code yourself. EM
|
123
|
+
binary Gems for Windows are compiled using Visual Studio 6.
|
124
|
+
|
125
|
+
EventMachine does supply some advanced features (such as Linux EPOLL support,
|
126
|
+
reduced-privilege operation, UNIX-domain sockets, etc.) that have no
|
127
|
+
meaningful implementation on Windows. Apart from these special cases, all EM
|
128
|
+
functionality (including lightweight concurrency) works perfectly well on
|
129
|
+
Windows.
|
130
|
+
|
data/docs/PURE_RUBY
ADDED
@@ -0,0 +1,75 @@
|
|
1
|
+
EventMachine is supplied in three alternative versions.
|
2
|
+
|
3
|
+
1) A version that includes a Ruby extension written in C++. This version requires compilation;
|
4
|
+
2) A version for JRuby that contains a precompiled JAR file written in Java;
|
5
|
+
3) A pure Ruby version that has no external dependencies and can run in any Ruby environment.
|
6
|
+
|
7
|
+
The Java version of EventMachine is packaged in a distinct manner and must be installed using a
|
8
|
+
special procedure. This version is described fully in a different document, and not considered
|
9
|
+
further here.
|
10
|
+
|
11
|
+
The C++ and pure-Ruby versions, however, are shipped in the same distribution. You use the same
|
12
|
+
files (either tarball or Ruby gem) to install both of these versions.
|
13
|
+
|
14
|
+
If you intend to use the C++ version, you must successfully compile EventMachine after you install it.
|
15
|
+
(The gem installation attempts to perform this step automatically.)
|
16
|
+
|
17
|
+
If you choose not to compile the EventMachine C++ extension, or if your compilation fails for any
|
18
|
+
reason, you still have a fully-functional installation of the pure-Ruby version of EM.
|
19
|
+
|
20
|
+
However, for technical reasons, a default EM installation (whether or not the compilation succeeds)
|
21
|
+
will always assume that the compiled ("extension") implementation should be used.
|
22
|
+
|
23
|
+
If you want your EM program to use the pure Ruby version, you must specifically request it. There
|
24
|
+
are two ways to do this: by setting either a Ruby global variable, or an environment string.
|
25
|
+
|
26
|
+
The following code will invoke the pure-Ruby implementation of EM:
|
27
|
+
|
28
|
+
$eventmachine_library = :pure_ruby
|
29
|
+
require 'eventmachine'
|
30
|
+
|
31
|
+
EM.library_type #=> "pure_ruby"
|
32
|
+
|
33
|
+
Notice that this requires a code change and is not the preferred way to select pure Ruby, unless
|
34
|
+
for some reason you are absolutely sure you will never want the compiled implementation.
|
35
|
+
|
36
|
+
Setting the following environment string has the same effect:
|
37
|
+
|
38
|
+
export EVENTMACHINE_LIBRARY="pure_ruby"
|
39
|
+
|
40
|
+
This technique gives you the flexibility to select either version at runtime with no code changes.
|
41
|
+
|
42
|
+
Support
|
43
|
+
|
44
|
+
The EventMachine development team has committed to support precisely the same APIs for all the
|
45
|
+
various implementations of EM.
|
46
|
+
|
47
|
+
This means that you can expect any EM program to behave identically, whether you use pure Ruby,
|
48
|
+
the compiled C++ extension, or JRuby. Deviations from this behavior are to be considered bugs
|
49
|
+
and should be reported as such.
|
50
|
+
|
51
|
+
There is a small number of exceptions to this rule, which arise from underlying platform
|
52
|
+
distinctions. Notably, EM#epoll is a silent no-op in the pure Ruby implementation.
|
53
|
+
|
54
|
+
|
55
|
+
When Should You Use the Pure-Ruby Implementation of EM?
|
56
|
+
|
57
|
+
|
58
|
+
Use the pure Ruby implementation of EM when you must support a platform for which no C++ compiler
|
59
|
+
is available, or on which the standard EM C++ code can't be compiled.
|
60
|
+
|
61
|
+
Keep in mind that you don't need a C++ compiler in order to deploy EM applications that rely on
|
62
|
+
the compiled version, so long as appropriate C++ runtime libraries are available on the target platform.
|
63
|
+
|
64
|
+
In extreme cases, you may find that you can develop software with the compiled EM version, but are
|
65
|
+
not allowed to install required runtime libraries on the deployment system(s). This would be another
|
66
|
+
case in which the pure Ruby implementation can be useful.
|
67
|
+
|
68
|
+
In general you should avoid the pure Ruby version of EM when performance and scalability are important.
|
69
|
+
EM in pure Ruby will necessarily run slower than the compiled version. Depending on your application
|
70
|
+
this may or may not be a key issue.
|
71
|
+
|
72
|
+
Also, since EPOLL is not supported in pure Ruby, your applications will be affected by Ruby's built-in
|
73
|
+
limit of 1024 file and socket descriptors that may be open in a single process. For maximum scalability
|
74
|
+
and performance, always use EPOLL if possible.
|
75
|
+
|
data/docs/RELEASE_NOTES
ADDED
@@ -0,0 +1,94 @@
|
|
1
|
+
RUBY/EventMachine RELEASE NOTES
|
2
|
+
|
3
|
+
--------------------------------------------------
|
4
|
+
Version: 0.9.0, released xxXXX07
|
5
|
+
Added Erlang-like distributed-computing features
|
6
|
+
|
7
|
+
--------------------------------------------------
|
8
|
+
Version: 0.8.0, released 23Jun07
|
9
|
+
Added an epoll implementation for Linux 2.6 kernels.
|
10
|
+
Added evented #popen.
|
11
|
+
|
12
|
+
--------------------------------------------------
|
13
|
+
Version: 0.7.3, released 22May07
|
14
|
+
Added a large variety of small features. See the ChangeLog.
|
15
|
+
|
16
|
+
--------------------------------------------------
|
17
|
+
Version: 0.7.1, released xxNov06
|
18
|
+
Added protocol handlers for line-oriented protocols.
|
19
|
+
Various bug fixes.
|
20
|
+
|
21
|
+
--------------------------------------------------
|
22
|
+
Version: 0.7.0, released 20Nov06
|
23
|
+
Added a fix in em.cpp/ConnectToServer to fix a fatal exception that
|
24
|
+
occurred in FreeBSD when connecting successfully to a remote server.
|
25
|
+
|
26
|
+
--------------------------------------------------
|
27
|
+
Version: 0.6.0, released xxJul06
|
28
|
+
Added deferred operations, suggested by Don Stocks, amillionhitpoints@yahoo.com.
|
29
|
+
|
30
|
+
--------------------------------------------------
|
31
|
+
Version: 0.5.4, released xxJun06
|
32
|
+
Added get_peername support for streams and datagrams.
|
33
|
+
|
34
|
+
--------------------------------------------------
|
35
|
+
Version: 0.5.3, released 17May06
|
36
|
+
Fixed bugs in extconf.rb, thanks to Daniel Harple, dharple@generalconsumption.org.
|
37
|
+
Added proper setup.rb and rake tasks, thanks to Austin Ziegler.
|
38
|
+
Fixed a handful of reported problems with builds on various platforms.
|
39
|
+
|
40
|
+
--------------------------------------------------
|
41
|
+
Version: 0.5.2, released 05May06
|
42
|
+
Made several nonvisible improvements to the Windows
|
43
|
+
implementation.
|
44
|
+
Added an exception-handling patch contributed by Jeff Rose, jeff@rosejn.net.
|
45
|
+
Added a dir-config patch contributed anonymously.
|
46
|
+
Supported builds on Solaris.
|
47
|
+
|
48
|
+
--------------------------------------------------
|
49
|
+
Version: 0.5.1, released 05May06
|
50
|
+
Made it possible to pass a Class rather than a Module
|
51
|
+
to a protocol handler.
|
52
|
+
Added Windows port.
|
53
|
+
|
54
|
+
--------------------------------------------------
|
55
|
+
Version: 0.5.0, released 30Apr06
|
56
|
+
Added a preliminary SSL/TLS extension. This will probably
|
57
|
+
change over the next few releases.
|
58
|
+
|
59
|
+
--------------------------------------------------
|
60
|
+
Version: 0.4.5, released 29Apr06
|
61
|
+
Changed ext files so the ruby.h is installed after unistd.h
|
62
|
+
otherwise it doesn't compile on gcc 4.1
|
63
|
+
|
64
|
+
--------------------------------------------------
|
65
|
+
Version: 0.4.2, released 19Apr06
|
66
|
+
Changed the Ruby-glue so the extension will play nicer
|
67
|
+
in the sandbox with Ruby threads.
|
68
|
+
Added an EventMachine::run_without_threads API to
|
69
|
+
switch off the thread-awareness for better performance
|
70
|
+
in programs that do not spin any Ruby threads.
|
71
|
+
|
72
|
+
--------------------------------------------------
|
73
|
+
Version: 0.4.1, released 15Apr06
|
74
|
+
Reworked the shared-object interface to make it easier to
|
75
|
+
use EventMachine from languages other than Ruby.
|
76
|
+
|
77
|
+
--------------------------------------------------
|
78
|
+
Version: 0.3.2, released 12Apr06
|
79
|
+
Added support for a user-supplied block in EventMachine#connect.
|
80
|
+
|
81
|
+
--------------------------------------------------
|
82
|
+
Version: 0.3.1, released 11Apr06
|
83
|
+
Fixed bug that prevented EventMachine from being run multiple
|
84
|
+
times in a single process.
|
85
|
+
|
86
|
+
--------------------------------------------------
|
87
|
+
Version: 0.3.0, released 10Apr06
|
88
|
+
Added method EventHandler::Connection::post_init
|
89
|
+
|
90
|
+
--------------------------------------------------
|
91
|
+
Version: 0.2.0, released 10Apr06
|
92
|
+
Added method EventHandler::stop
|
93
|
+
|
94
|
+
|
data/docs/SMTP
ADDED
@@ -0,0 +1,148 @@
|
|
1
|
+
EventMachine (EM) adds two different formalisms for lightweight concurrency
|
2
|
+
to the Ruby programmer's toolbox: spawned processes and deferrables. This
|
3
|
+
note will show you how to use spawned processes. For more information, see
|
4
|
+
the separate document LIGHTWEIGHT_CONCURRENCY.
|
5
|
+
|
6
|
+
|
7
|
+
=== What are Spawned Processes?
|
8
|
+
|
9
|
+
Spawned Processes in EventMachine are inspired directly by the "processes"
|
10
|
+
found in the Erlang programming language. EM deliberately borrows much (but
|
11
|
+
not all) of Erlang's terminology. However, EM's spawned processes differ from
|
12
|
+
Erlang's in ways that reflect not only Ruby style, but also the fact that
|
13
|
+
Ruby is not a functional language like Erlang.
|
14
|
+
|
15
|
+
Let's proceed with a complete, working code sample that we will analyze line
|
16
|
+
by line. Here's an EM implementation of the "ping-pong" program that also
|
17
|
+
appears in the Erlang tutorial:
|
18
|
+
|
19
|
+
|
20
|
+
require 'eventmachine'
|
21
|
+
|
22
|
+
EM.run {
|
23
|
+
pong = EM.spawn {|x, ping|
|
24
|
+
puts "Pong received #{x}"
|
25
|
+
ping.notify( x-1 )
|
26
|
+
}
|
27
|
+
|
28
|
+
ping = EM.spawn {|x|
|
29
|
+
if x > 0
|
30
|
+
puts "Pinging #{x}"
|
31
|
+
pong.notify x, self
|
32
|
+
else
|
33
|
+
EM.stop
|
34
|
+
end
|
35
|
+
}
|
36
|
+
|
37
|
+
ping.notify 3
|
38
|
+
}
|
39
|
+
|
40
|
+
If you run this program, you'll see the following output:
|
41
|
+
|
42
|
+
Pinging 3
|
43
|
+
Pong received 3
|
44
|
+
Pinging 2
|
45
|
+
Pong received 2
|
46
|
+
Pinging 1
|
47
|
+
Pong received 1
|
48
|
+
|
49
|
+
Let's take it step by step.
|
50
|
+
|
51
|
+
EventMachine#spawn works very much like the built-in function spawn in
|
52
|
+
Erlang. It returns a reference to a Ruby object of class
|
53
|
+
EventMachine::SpawnedProcess, which is actually a schedulable entity. In
|
54
|
+
Erlang, the value returned from spawn is called a "process identifier" or
|
55
|
+
"pid." But we'll refer to the Ruby object returned from EM#spawn simply as a
|
56
|
+
"spawned process."
|
57
|
+
|
58
|
+
You pass a Ruby block with zero or more parameters to EventMachine#spawn.
|
59
|
+
Like all Ruby blocks, this one is a closure, so it can refer to variables
|
60
|
+
defined in the local context when you call EM#spawn.
|
61
|
+
|
62
|
+
However, the code block passed to EM#spawn does NOT execute immediately by
|
63
|
+
default. Rather, it will execute only when the Spawned Object is "notified."
|
64
|
+
In Erlang, this process is called "message passing," and is done with the
|
65
|
+
operator !, but in Ruby it's done simply by calling the #notify method of a
|
66
|
+
spawned-process object. The parameters you pass to #notify must match those
|
67
|
+
defined in the block that was originally passed to EM#spawn.
|
68
|
+
|
69
|
+
When you call the #notify method of a spawned-process object, EM's reactor
|
70
|
+
core will execute the code block originally passed to EM#spawn, at some point
|
71
|
+
in the future. (#notify itself merely adds a notification to the object's
|
72
|
+
message queue and ALWAYS returns immediately.)
|
73
|
+
|
74
|
+
When a SpawnedProcess object executes a notification, it does so in the
|
75
|
+
context of the SpawnedProcess object itself. The notified code block can see
|
76
|
+
local context from the point at which EM#spawn was called. However, the value
|
77
|
+
of "self" inside the notified code block is a reference to the SpawnedProcesss
|
78
|
+
object itself.
|
79
|
+
|
80
|
+
An EM spawned process is nothing more than a Ruby object with a message
|
81
|
+
queue attached to it. You can have any number of spawned processes in your
|
82
|
+
program without compromising scalability. You can notify a spawned process
|
83
|
+
any number of times, and each notification will cause a "message" to be
|
84
|
+
placed in the queue of the spawned process. Spawned processes with non-empty
|
85
|
+
message queues are scheduled for execution automatically by the EM reactor.
|
86
|
+
Spawned processes with no visible references are garbage-collected like any
|
87
|
+
other Ruby object.
|
88
|
+
|
89
|
+
Back to our code sample:
|
90
|
+
|
91
|
+
pong = EM.spawn {|x, ping|
|
92
|
+
puts "Pong received #{x}"
|
93
|
+
ping.notify( x-1 )
|
94
|
+
}
|
95
|
+
|
96
|
+
This simply creates a spawned process and assigns it to the local variable
|
97
|
+
pong. You can see that the spawned code block takes a numeric parameter and a
|
98
|
+
reference to another spawned process. When pong is notified, it expects to
|
99
|
+
receive arguments corresponding to these two parameters. It simply prints out
|
100
|
+
the number it receives as the first argument. Then it notifies the spawned
|
101
|
+
process referenced by the second argument, passing it the first argument
|
102
|
+
minus 1.
|
103
|
+
|
104
|
+
And then the block ends, which is crucial because otherwise nothing else
|
105
|
+
can run. (Remember that in LC, scheduled entities run to completion and are
|
106
|
+
never preempted.)
|
107
|
+
|
108
|
+
On to the next bit of the code sample:
|
109
|
+
|
110
|
+
ping = EM.spawn {|x|
|
111
|
+
if x > 0
|
112
|
+
puts "Pinging #{x}"
|
113
|
+
pong.notify x, self
|
114
|
+
else
|
115
|
+
EM.stop
|
116
|
+
end
|
117
|
+
}
|
118
|
+
|
119
|
+
Here, we're spawning a process that takes a single (numeric) parameter. If
|
120
|
+
the parameter is greater than zero, the block writes it to the console. It
|
121
|
+
then notifies the spawned process referenced by the pong local variable,
|
122
|
+
passing as arguments its number argument, and a reference to itself. The
|
123
|
+
latter reference, as you saw above, is used by pong to send a return
|
124
|
+
notification.
|
125
|
+
|
126
|
+
If the ping process receives a zero value, it will stop the reactor loop and
|
127
|
+
end the program.
|
128
|
+
|
129
|
+
Now we've created a pair of spawned processes, but nothing else has happened.
|
130
|
+
If we stop now, the program will spin in the EM reactor loop, doing nothing
|
131
|
+
at all. Our spawned processes will never be scheduled for execution.
|
132
|
+
|
133
|
+
But look at the next line in the code sample:
|
134
|
+
|
135
|
+
ping.notify 3
|
136
|
+
|
137
|
+
This line gets the ping-pong ball rolling. We call ping's #notify method,
|
138
|
+
passing the argument 3. This causes a message to be sent to the ping spawned
|
139
|
+
process. The message contains the single argument, and it causes the EM
|
140
|
+
reactor to schedule the ping process. And this in turn results in the
|
141
|
+
execution of the Ruby code block passed to EM#spawn when ping was created.
|
142
|
+
Everything else proceeds as a result of the messages that are subsequently
|
143
|
+
passed to each other by the spawned processes.
|
144
|
+
|
145
|
+
[TODO, present the outbound network i/o use case, and clarify that spawned
|
146
|
+
processes are interleaved with normal i/o operations and don't interfere
|
147
|
+
with them at all. Also, blame Erlang for the confusing term "process"]
|
148
|
+
|