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.
Files changed (141) hide show
  1. data/.gitignore +16 -0
  2. data/Gemfile +1 -0
  3. data/README +81 -0
  4. data/Rakefile +11 -0
  5. data/docs/COPYING +60 -0
  6. data/docs/ChangeLog +211 -0
  7. data/docs/DEFERRABLES +246 -0
  8. data/docs/EPOLL +141 -0
  9. data/docs/GNU +281 -0
  10. data/docs/INSTALL +13 -0
  11. data/docs/KEYBOARD +42 -0
  12. data/docs/LEGAL +25 -0
  13. data/docs/LIGHTWEIGHT_CONCURRENCY +130 -0
  14. data/docs/PURE_RUBY +75 -0
  15. data/docs/RELEASE_NOTES +94 -0
  16. data/docs/SMTP +4 -0
  17. data/docs/SPAWNED_PROCESSES +148 -0
  18. data/docs/TODO +8 -0
  19. data/eventmachine.gemspec +33 -0
  20. data/examples/ex_channel.rb +43 -0
  21. data/examples/ex_queue.rb +2 -0
  22. data/examples/ex_tick_loop_array.rb +15 -0
  23. data/examples/ex_tick_loop_counter.rb +32 -0
  24. data/examples/helper.rb +2 -0
  25. data/ext/binder.cpp +124 -0
  26. data/ext/binder.h +46 -0
  27. data/ext/cmain.cpp +838 -0
  28. data/ext/ed.cpp +1884 -0
  29. data/ext/ed.h +418 -0
  30. data/ext/em.cpp +2348 -0
  31. data/ext/em.h +228 -0
  32. data/ext/eventmachine.h +123 -0
  33. data/ext/extconf.rb +157 -0
  34. data/ext/fastfilereader/extconf.rb +85 -0
  35. data/ext/fastfilereader/mapper.cpp +214 -0
  36. data/ext/fastfilereader/mapper.h +59 -0
  37. data/ext/fastfilereader/rubymain.cpp +127 -0
  38. data/ext/kb.cpp +79 -0
  39. data/ext/page.cpp +107 -0
  40. data/ext/page.h +51 -0
  41. data/ext/pipe.cpp +347 -0
  42. data/ext/project.h +155 -0
  43. data/ext/rubymain.cpp +1200 -0
  44. data/ext/ssl.cpp +460 -0
  45. data/ext/ssl.h +94 -0
  46. data/java/.classpath +8 -0
  47. data/java/.project +17 -0
  48. data/java/src/com/rubyeventmachine/EmReactor.java +571 -0
  49. data/java/src/com/rubyeventmachine/EmReactorException.java +40 -0
  50. data/java/src/com/rubyeventmachine/EventableChannel.java +69 -0
  51. data/java/src/com/rubyeventmachine/EventableDatagramChannel.java +189 -0
  52. data/java/src/com/rubyeventmachine/EventableSocketChannel.java +364 -0
  53. data/lib/em/buftok.rb +138 -0
  54. data/lib/em/callback.rb +26 -0
  55. data/lib/em/channel.rb +57 -0
  56. data/lib/em/connection.rb +569 -0
  57. data/lib/em/deferrable.rb +206 -0
  58. data/lib/em/file_watch.rb +54 -0
  59. data/lib/em/future.rb +61 -0
  60. data/lib/em/iterator.rb +270 -0
  61. data/lib/em/messages.rb +66 -0
  62. data/lib/em/process_watch.rb +44 -0
  63. data/lib/em/processes.rb +119 -0
  64. data/lib/em/protocols.rb +36 -0
  65. data/lib/em/protocols/header_and_content.rb +138 -0
  66. data/lib/em/protocols/httpclient.rb +268 -0
  67. data/lib/em/protocols/httpclient2.rb +590 -0
  68. data/lib/em/protocols/line_and_text.rb +125 -0
  69. data/lib/em/protocols/line_protocol.rb +28 -0
  70. data/lib/em/protocols/linetext2.rb +161 -0
  71. data/lib/em/protocols/memcache.rb +323 -0
  72. data/lib/em/protocols/object_protocol.rb +45 -0
  73. data/lib/em/protocols/postgres3.rb +247 -0
  74. data/lib/em/protocols/saslauth.rb +175 -0
  75. data/lib/em/protocols/smtpclient.rb +357 -0
  76. data/lib/em/protocols/smtpserver.rb +640 -0
  77. data/lib/em/protocols/socks4.rb +66 -0
  78. data/lib/em/protocols/stomp.rb +200 -0
  79. data/lib/em/protocols/tcptest.rb +53 -0
  80. data/lib/em/pure_ruby.rb +1013 -0
  81. data/lib/em/queue.rb +62 -0
  82. data/lib/em/spawnable.rb +85 -0
  83. data/lib/em/streamer.rb +130 -0
  84. data/lib/em/tick_loop.rb +85 -0
  85. data/lib/em/timers.rb +57 -0
  86. data/lib/em/version.rb +3 -0
  87. data/lib/eventmachine.rb +1548 -0
  88. data/lib/jeventmachine.rb +258 -0
  89. data/lib/rubyeventmachine.rb +2 -0
  90. data/setup.rb +1585 -0
  91. data/tasks/cpp.rake_example +77 -0
  92. data/tasks/doc.rake +30 -0
  93. data/tasks/package.rake +85 -0
  94. data/tasks/test.rake +6 -0
  95. data/tests/client.crt +31 -0
  96. data/tests/client.key +51 -0
  97. data/tests/test_attach.rb +136 -0
  98. data/tests/test_basic.rb +249 -0
  99. data/tests/test_channel.rb +64 -0
  100. data/tests/test_connection_count.rb +35 -0
  101. data/tests/test_defer.rb +49 -0
  102. data/tests/test_deferrable.rb +35 -0
  103. data/tests/test_epoll.rb +160 -0
  104. data/tests/test_error_handler.rb +35 -0
  105. data/tests/test_errors.rb +82 -0
  106. data/tests/test_exc.rb +55 -0
  107. data/tests/test_file_watch.rb +49 -0
  108. data/tests/test_futures.rb +198 -0
  109. data/tests/test_get_sock_opt.rb +30 -0
  110. data/tests/test_handler_check.rb +37 -0
  111. data/tests/test_hc.rb +190 -0
  112. data/tests/test_httpclient.rb +227 -0
  113. data/tests/test_httpclient2.rb +154 -0
  114. data/tests/test_inactivity_timeout.rb +50 -0
  115. data/tests/test_kb.rb +60 -0
  116. data/tests/test_ltp.rb +190 -0
  117. data/tests/test_ltp2.rb +317 -0
  118. data/tests/test_next_tick.rb +133 -0
  119. data/tests/test_object_protocol.rb +37 -0
  120. data/tests/test_pause.rb +70 -0
  121. data/tests/test_pending_connect_timeout.rb +48 -0
  122. data/tests/test_process_watch.rb +50 -0
  123. data/tests/test_processes.rb +128 -0
  124. data/tests/test_proxy_connection.rb +144 -0
  125. data/tests/test_pure.rb +134 -0
  126. data/tests/test_queue.rb +44 -0
  127. data/tests/test_running.rb +42 -0
  128. data/tests/test_sasl.rb +72 -0
  129. data/tests/test_send_file.rb +251 -0
  130. data/tests/test_servers.rb +76 -0
  131. data/tests/test_smtpclient.rb +83 -0
  132. data/tests/test_smtpserver.rb +85 -0
  133. data/tests/test_spawn.rb +322 -0
  134. data/tests/test_ssl_args.rb +79 -0
  135. data/tests/test_ssl_methods.rb +50 -0
  136. data/tests/test_ssl_verify.rb +82 -0
  137. data/tests/test_tick_loop.rb +59 -0
  138. data/tests/test_timers.rb +160 -0
  139. data/tests/test_ud.rb +36 -0
  140. data/tests/testem.rb +31 -0
  141. metadata +240 -0
@@ -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
+
@@ -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
+
@@ -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
+
@@ -0,0 +1,4 @@
1
+ This note details the usage of EventMachine's built-in support for SMTP. EM
2
+ supports both client and server connections, which will be described in
3
+ separate sections.
4
+
@@ -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
+