wj_eventmachine 1.3.0.dev.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (180) hide show
  1. checksums.yaml +7 -0
  2. data/CHANGELOG.md +179 -0
  3. data/GNU +281 -0
  4. data/LICENSE +60 -0
  5. data/README.md +110 -0
  6. data/docs/DocumentationGuidesIndex.md +27 -0
  7. data/docs/GettingStarted.md +520 -0
  8. data/docs/old/ChangeLog +211 -0
  9. data/docs/old/DEFERRABLES +246 -0
  10. data/docs/old/EPOLL +141 -0
  11. data/docs/old/INSTALL +13 -0
  12. data/docs/old/KEYBOARD +42 -0
  13. data/docs/old/LEGAL +25 -0
  14. data/docs/old/LIGHTWEIGHT_CONCURRENCY +130 -0
  15. data/docs/old/PURE_RUBY +75 -0
  16. data/docs/old/RELEASE_NOTES +94 -0
  17. data/docs/old/SMTP +4 -0
  18. data/docs/old/SPAWNED_PROCESSES +148 -0
  19. data/docs/old/TODO +8 -0
  20. data/examples/guides/getting_started/01_eventmachine_echo_server.rb +18 -0
  21. data/examples/guides/getting_started/02_eventmachine_echo_server_that_recognizes_exit_command.rb +22 -0
  22. data/examples/guides/getting_started/03_simple_chat_server.rb +149 -0
  23. data/examples/guides/getting_started/04_simple_chat_server_step_one.rb +27 -0
  24. data/examples/guides/getting_started/05_simple_chat_server_step_two.rb +43 -0
  25. data/examples/guides/getting_started/06_simple_chat_server_step_three.rb +98 -0
  26. data/examples/guides/getting_started/07_simple_chat_server_step_four.rb +121 -0
  27. data/examples/guides/getting_started/08_simple_chat_server_step_five.rb +141 -0
  28. data/examples/old/ex_channel.rb +43 -0
  29. data/examples/old/ex_queue.rb +2 -0
  30. data/examples/old/ex_tick_loop_array.rb +15 -0
  31. data/examples/old/ex_tick_loop_counter.rb +32 -0
  32. data/examples/old/helper.rb +2 -0
  33. data/ext/binder.cpp +124 -0
  34. data/ext/binder.h +52 -0
  35. data/ext/cmain.cpp +1046 -0
  36. data/ext/ed.cpp +2238 -0
  37. data/ext/ed.h +460 -0
  38. data/ext/em.cpp +2378 -0
  39. data/ext/em.h +266 -0
  40. data/ext/eventmachine.h +152 -0
  41. data/ext/extconf.rb +285 -0
  42. data/ext/fastfilereader/extconf.rb +120 -0
  43. data/ext/fastfilereader/mapper.cpp +214 -0
  44. data/ext/fastfilereader/mapper.h +59 -0
  45. data/ext/fastfilereader/rubymain.cpp +126 -0
  46. data/ext/kb.cpp +79 -0
  47. data/ext/page.cpp +107 -0
  48. data/ext/page.h +51 -0
  49. data/ext/pipe.cpp +354 -0
  50. data/ext/project.h +174 -0
  51. data/ext/rubymain.cpp +1610 -0
  52. data/ext/ssl.cpp +627 -0
  53. data/ext/ssl.h +103 -0
  54. data/ext/wait_for_single_fd.h +36 -0
  55. data/java/.classpath +8 -0
  56. data/java/.project +17 -0
  57. data/java/src/com/rubyeventmachine/EmReactor.java +625 -0
  58. data/java/src/com/rubyeventmachine/EmReactorException.java +40 -0
  59. data/java/src/com/rubyeventmachine/EmReactorInterface.java +70 -0
  60. data/java/src/com/rubyeventmachine/EventableChannel.java +72 -0
  61. data/java/src/com/rubyeventmachine/EventableDatagramChannel.java +201 -0
  62. data/java/src/com/rubyeventmachine/EventableSocketChannel.java +415 -0
  63. data/java/src/com/rubyeventmachine/NullEmReactor.java +157 -0
  64. data/java/src/com/rubyeventmachine/NullEventableChannel.java +81 -0
  65. data/lib/em/buftok.rb +59 -0
  66. data/lib/em/callback.rb +58 -0
  67. data/lib/em/channel.rb +69 -0
  68. data/lib/em/completion.rb +307 -0
  69. data/lib/em/connection.rb +776 -0
  70. data/lib/em/deferrable.rb +210 -0
  71. data/lib/em/deferrable/pool.rb +2 -0
  72. data/lib/em/file_watch.rb +73 -0
  73. data/lib/em/future.rb +61 -0
  74. data/lib/em/io_streamer.rb +68 -0
  75. data/lib/em/iterator.rb +252 -0
  76. data/lib/em/messages.rb +66 -0
  77. data/lib/em/pool.rb +151 -0
  78. data/lib/em/process_watch.rb +45 -0
  79. data/lib/em/processes.rb +123 -0
  80. data/lib/em/protocols.rb +37 -0
  81. data/lib/em/protocols/header_and_content.rb +138 -0
  82. data/lib/em/protocols/httpclient.rb +303 -0
  83. data/lib/em/protocols/httpclient2.rb +602 -0
  84. data/lib/em/protocols/line_and_text.rb +125 -0
  85. data/lib/em/protocols/line_protocol.rb +33 -0
  86. data/lib/em/protocols/linetext2.rb +179 -0
  87. data/lib/em/protocols/memcache.rb +331 -0
  88. data/lib/em/protocols/object_protocol.rb +46 -0
  89. data/lib/em/protocols/postgres3.rb +246 -0
  90. data/lib/em/protocols/saslauth.rb +175 -0
  91. data/lib/em/protocols/smtpclient.rb +394 -0
  92. data/lib/em/protocols/smtpserver.rb +666 -0
  93. data/lib/em/protocols/socks4.rb +66 -0
  94. data/lib/em/protocols/stomp.rb +205 -0
  95. data/lib/em/protocols/tcptest.rb +54 -0
  96. data/lib/em/pure_ruby.rb +1299 -0
  97. data/lib/em/queue.rb +80 -0
  98. data/lib/em/resolver.rb +232 -0
  99. data/lib/em/spawnable.rb +84 -0
  100. data/lib/em/streamer.rb +118 -0
  101. data/lib/em/threaded_resource.rb +90 -0
  102. data/lib/em/tick_loop.rb +85 -0
  103. data/lib/em/timers.rb +61 -0
  104. data/lib/em/version.rb +3 -0
  105. data/lib/eventmachine.rb +1602 -0
  106. data/lib/jeventmachine.rb +318 -0
  107. data/rakelib/package.rake +120 -0
  108. data/rakelib/test.rake +6 -0
  109. data/rakelib/test_pure.rake +11 -0
  110. data/tests/client.crt +31 -0
  111. data/tests/client.key +51 -0
  112. data/tests/dhparam.pem +13 -0
  113. data/tests/em_ssl_handlers.rb +153 -0
  114. data/tests/em_test_helper.rb +198 -0
  115. data/tests/jruby/test_jeventmachine.rb +38 -0
  116. data/tests/test_attach.rb +199 -0
  117. data/tests/test_basic.rb +321 -0
  118. data/tests/test_channel.rb +75 -0
  119. data/tests/test_completion.rb +178 -0
  120. data/tests/test_connection_count.rb +83 -0
  121. data/tests/test_connection_write.rb +35 -0
  122. data/tests/test_defer.rb +35 -0
  123. data/tests/test_deferrable.rb +35 -0
  124. data/tests/test_epoll.rb +141 -0
  125. data/tests/test_error_handler.rb +38 -0
  126. data/tests/test_exc.rb +37 -0
  127. data/tests/test_file_watch.rb +86 -0
  128. data/tests/test_fork.rb +75 -0
  129. data/tests/test_futures.rb +170 -0
  130. data/tests/test_handler_check.rb +35 -0
  131. data/tests/test_hc.rb +155 -0
  132. data/tests/test_httpclient.rb +238 -0
  133. data/tests/test_httpclient2.rb +132 -0
  134. data/tests/test_idle_connection.rb +31 -0
  135. data/tests/test_inactivity_timeout.rb +102 -0
  136. data/tests/test_io_streamer.rb +47 -0
  137. data/tests/test_ipv4.rb +96 -0
  138. data/tests/test_ipv6.rb +107 -0
  139. data/tests/test_iterator.rb +122 -0
  140. data/tests/test_kb.rb +28 -0
  141. data/tests/test_keepalive.rb +113 -0
  142. data/tests/test_line_protocol.rb +33 -0
  143. data/tests/test_ltp.rb +155 -0
  144. data/tests/test_ltp2.rb +332 -0
  145. data/tests/test_many_fds.rb +21 -0
  146. data/tests/test_next_tick.rb +104 -0
  147. data/tests/test_object_protocol.rb +36 -0
  148. data/tests/test_pause.rb +109 -0
  149. data/tests/test_pending_connect_timeout.rb +52 -0
  150. data/tests/test_pool.rb +196 -0
  151. data/tests/test_process_watch.rb +50 -0
  152. data/tests/test_processes.rb +128 -0
  153. data/tests/test_proxy_connection.rb +180 -0
  154. data/tests/test_pure.rb +156 -0
  155. data/tests/test_queue.rb +64 -0
  156. data/tests/test_resolver.rb +129 -0
  157. data/tests/test_running.rb +14 -0
  158. data/tests/test_sasl.rb +46 -0
  159. data/tests/test_send_file.rb +217 -0
  160. data/tests/test_servers.rb +32 -0
  161. data/tests/test_shutdown_hooks.rb +23 -0
  162. data/tests/test_smtpclient.rb +75 -0
  163. data/tests/test_smtpserver.rb +90 -0
  164. data/tests/test_sock_opt.rb +53 -0
  165. data/tests/test_spawn.rb +290 -0
  166. data/tests/test_ssl_args.rb +41 -0
  167. data/tests/test_ssl_dhparam.rb +57 -0
  168. data/tests/test_ssl_ecdh_curve.rb +57 -0
  169. data/tests/test_ssl_extensions.rb +24 -0
  170. data/tests/test_ssl_methods.rb +31 -0
  171. data/tests/test_ssl_protocols.rb +190 -0
  172. data/tests/test_ssl_verify.rb +52 -0
  173. data/tests/test_stomp.rb +38 -0
  174. data/tests/test_system.rb +46 -0
  175. data/tests/test_threaded_resource.rb +68 -0
  176. data/tests/test_tick_loop.rb +58 -0
  177. data/tests/test_timers.rb +150 -0
  178. data/tests/test_ud.rb +8 -0
  179. data/tests/test_unbind_reason.rb +40 -0
  180. metadata +384 -0
@@ -0,0 +1,211 @@
1
+ 01Oct06: Replaced EventMachine#open_datagram_server with a version that can
2
+ take a Class or a Module, instead of just a Module. Thanks to Tobias
3
+ Gustafsson for pointing out the missing case.
4
+ 04Oct06: Supported subsecond timer resolutions, per request by Jason Roelofs.
5
+ 05Oct06: Added EventMachine#set_quantum, which sets the timer resolution.
6
+ 15Nov06: Added Connection#set_comm_inactivity_timeout.
7
+ 15Nov06: Checked in a Line-and-Text Protocol Handler.
8
+ 18Nov06: Checked in a Header-and-Body Protocol Handler.
9
+ 22Nov06: Changed EventMachine#reconnect: no longer excepts when called on an
10
+ already-connected handler.
11
+ 28Nov06: Supported a binary-unix gem.
12
+ 19Dec06: Added EventMachine#set_effective_user.
13
+ 05Jan07: Upped max outstanding timers to 1000.
14
+ 15May07: Applied Solaris patches from Brett Eisenberg
15
+ 22May07: Cleaned up the license text in all the source files.
16
+ 22May07: Released version 0.7.2
17
+
18
+ 23May07: Per suggestion from Bill Kelly, fixed a bug with the initialization
19
+ of the network libraries under Windows. The goal is to enable EM to
20
+ be used without Ruby.
21
+ 28May07: Applied patch from Bill Kelly, refactors the declarations of
22
+ event names to make EM easier to use from C programs without Ruby.
23
+ 31May07: Added a preliminary implementation of EventMachine#popen.
24
+ 01Jun07: Added EM, a "pseudo-alias" for EventMachine.
25
+ 01Jun07: Added EM#next_tick.
26
+ 01Jun07: Added EM::Connection#get_outbound_data_size
27
+ 05Jun07: Removed the code which loads a pure-Ruby EM library in case the
28
+ compiled extension is unavailable. Suggested by Moshe Litvin.
29
+ 06Jun07: Preliminary epoll implementation.
30
+ 12Jun07: Added an evented popen implementation that, like Ruby's, is
31
+ full-duplex and makes the subprocess PID available to the caller.
32
+ 06Jul07: Performance-tweaked the callback dispatcher in eventmachine.rb.
33
+ 10Jul07: Released version 0.8.0.
34
+ 12Jul07: Applied patches from Tim Pease to fix Solaris build problems.
35
+ 15Jul07: Created a new provisional source branch, experiments/jruby-1.
36
+ This is a preliminary implementation of the EM reactor in Java,
37
+ suitable for use with JRuby.
38
+ 17Jul07: Added EventMachine#stop_server, per request from Kirk Haines,
39
+ and associated unit tests.
40
+ 22Jul07: Added EventMachine#stream_file_data. This is a very fast and scalable
41
+ way of sending data from static files over network connections. It
42
+ has separate implementations for small files and large file, and
43
+ has tunings to minimize memory consumption.
44
+ 26Jul07: Added some patches by Kirk Haines to improve the behavior of
45
+ EM::Connection#send_file_data_to_connection.
46
+ 26Jul07: Added a C++ module for directly integrating EM into C++ programs
47
+ with no Ruby dependencies. Needs example code.
48
+ 29Jul07: Added EventMachine::Protocols::LineText2.
49
+ 29Jul07: Added EventMachine::Protocols::Stomp.
50
+ 30Jul07: Added sys/stat.h to project.h to fix compilation bug on Darwin.
51
+ 13Aug07: Added EventMachine#reactor_running?
52
+ 15Aug07: Added parameters for EventMachine::Connection:start_tls that can be
53
+ used to specify client-side private keys and certificates.
54
+ 17Aug07: Added EventMachine#run_block, a sugaring for a common use case.
55
+ 24Aug07: Added a preliminary keyboard handler. Needs docs and testing on
56
+ windows.
57
+ 26Aug07: Created EventMachine::Spawnable, an implementation of Erlang-like
58
+ processes.
59
+ 27Aug07: Silenced some -w warnings, requested by James Edward Gray II.
60
+ 30Aug07: Added cookies to EM::HttpClient#request.
61
+ 04Sep07: Added an initial implementation of an evented SMTP client.
62
+ 04Sep07: Added an initial implementation of an evented SMTP server.
63
+ 10Sep07: Changed EM#spawn to run spawned blocks in the context of the
64
+ SpawnedProcess object, not of whatever was the active object at the
65
+ time of the spawn.
66
+ 14Sep07: Heartbeats weren't working with EPOLL. Noticed by Brian Candler.
67
+ 15Sep07: Added some features, tests and documents to Deferrable.
68
+ 16Sep07: Added [:content] parameter to EM::Protocols::SmtpClient#send.
69
+ 16Sep07: Bumped version to 0.9.0 in anticipation of a release.
70
+ 18Sep07: Released version 0.9.0.
71
+ 19Sep07: Added #receive_reset to EM::Protocols::SmtpServer.
72
+ 19Sep07: User overrides of EM::Protocols::SmtpServer#receive_recipient can now
73
+ return a Deferrable. Also fixed bug: SmtpClient now raises a protocol
74
+ error if none of its RCPT TO: commands are accepted by the server.
75
+ 26Sep07: Fixed missing keyboard support for Windows.
76
+ 03Oct07: Added a default handler for RuntimeErrors emitted from user-written
77
+ code. Suggested by Brian Candler.
78
+ 19Oct07: Set the SO_BROADCAST option automatically on all UDP sockets.
79
+ 10Nov07: Forced integer conversion of send_datagram's port parameter.
80
+ Suggested by Matthieu Riou.
81
+ 12Nov07: Added saslauth.rb, a protocol module to replace the Cyrus SASL
82
+ daemons saslauthd and pwcheck.
83
+ 15Nov07: Fixed bug reported by Mark Zvillius. We were failing to dispatch
84
+ zero-length datagrams under certain conditions.
85
+ 19Nov07: Added EventMachine#set_max_timers. Requested by Matthieu Riou and
86
+ others.
87
+ 19Nov07: Fixed bug with EM::Connection#start_tls. Was not working with server
88
+ connections. Reported by Michael S. Fischer.
89
+ 26Nov07: Supported a hack for EventMachine#popen so it can return an exit
90
+ status from subprocesses. Requested by Michael S. Fischer.
91
+ 30Nov07: Changed Pipe descriptors so that the child-side of the socketpair is
92
+ NOT set nonblocking. Suggested by Duane Johnson.
93
+ 05Dec07: Re-enabled the pure-Ruby implementation.
94
+ 06Dec07: Released Version 0.10.0.
95
+ 13Dec07: Added EM::DeferrableChildProcess
96
+ 24Dec07: Added a SASL client for simple password authentication.
97
+ 27Dec07: Removed the hookable error handler. No one was using it and it significantly
98
+ degraded performance.
99
+ 30Dec07: Implemented Kqueue support for OSX and BSD.
100
+ 04Jan08: Fixed bug in epoll ("Bad file descriptor"), patch supplied by Chris
101
+ Heath.
102
+ 04Jan08: Fixed bug reported by Michael S. Fischer. We were terminating
103
+ SSL connections that sent data before the handshake was complete.
104
+ 08Jan08: Added an OpenBSD branch for extconf.rb, contributed by Guillaume
105
+ Sellier.
106
+ 19Jan08: Added EM::Connection::get_sockname per request by Michael Fischer.
107
+ 19Jan08: Supported IPv6 addresses.
108
+ 30Apr08: Set the NODELAY option on sockets that we connect to other servers.
109
+ Omission noted by Roger Pack.
110
+ 14May08: Generated a 0.12 release.
111
+ 15May08: Supported EM#get_sockname for acceptors (TCP server sockets).
112
+ Requested by Roger Pack.
113
+ 15May08; Accepted a patch from Dan Aquino that allows the interval of a
114
+ PeriodicTimer to be changed on the fly.
115
+ 15Jun08: Supported nested calls to EM#run. Many people contributed ideas to
116
+ this, notably raggi and tmm1.
117
+ 20Jul08: Accepted patch from tmm1 for EM#fork_reactor.
118
+ 28Jul08: Added a Postgres3 implementation, written by FCianfrocca.
119
+ 14Aug08: Added a patch by Mike Murphy to support basic auth in the http
120
+ client.
121
+ 28Aug08: Added a patch by tmm1 to fix a longstanding problem with Java
122
+ data-sends.
123
+ 13Sep08: Added LineText2#set_binary_mode, a back-compatibility alias.
124
+ 13Sep08: Modified the load order of protocol libraries in eventmachine.rb
125
+ to permit a modification of HeaderAndContentProtocol.
126
+ 13Sep08: Modified HeaderAndContent to use LineText2, which is less buggy
127
+ than LineAndTextProtocol. This change may be reversed if we can fix
128
+ the bugs in buftok.
129
+ 13Sep08: Improved the password handling in the Postgres protocol handler.
130
+ 15Sep08: Added attach/detach, contributed by Aman Gupta (tmm1) and Riham Aldakkak,
131
+ to support working with file descriptors not created in the reactor.
132
+ 16Sep08: Added an optional version string to the HTTP client. This is a hack
133
+ that allows a client to specify a version 1.0 request, which
134
+ keeps the server from sending a chunked response. The right way to
135
+ solve this, of course, is to support chunked responses.
136
+ 23Sep08: ChangeLog Summary for Merge of branches/raggi
137
+ Most notable work and patches by Aman Gupta, Roger Pack, and James Tucker.
138
+ Patches / Tickets also submitted by: Jeremy Evans, aanand, darix, mmmurf,
139
+ danielaquino, macournoyer.
140
+ - Moved docs into docs/ dir
141
+ - Major refactor of rakefile, added generic rakefile helpers in tasks
142
+ - Added example CPP build rakefile in tasks/cpp.rake
143
+ - Moved rake tests out to tasks/tests.rake
144
+ - Added svn ignores where appropriate
145
+ - Fixed jruby build on older java platforms
146
+ - Gem now builds from Rakefile rather than directly via extconf
147
+ - Gem unified for jruby, C++ and pure ruby.
148
+ - Correction for pure C++ build, removing ruby dependency
149
+ - Fix for CYGWIN builds on ipv6
150
+ - Major refactor for extconf.rb
151
+ - Working mingw builds
152
+ - extconf optionally uses pkg_config over manual configuration
153
+ - extconf builds for 1.9 on any system that has 1.9
154
+ - extconf no longer links pthread explicitly
155
+ - looks for kqueue on all *nix systems
156
+ - better error output on std::runtime_error, now says where it came from
157
+ - Fixed some tests on jruby
158
+ - Added test for general send_data flaw, required for a bugfix in jruby build
159
+ - Added timeout to epoll tests
160
+ - Added fixes for java reactor ruby api
161
+ - Small addition of some docs in httpclient.rb and httpcli2.rb
162
+ - Some refactor and fixes in smtpserver.rb
163
+ - Added parenthesis where possible to avoid excess ruby warnings
164
+ - Refactor of $eventmachine_library logic for accuracy and maintenance, jruby
165
+ - EM::start_server now supports unix sockets
166
+ - EM::connect now supports unix sockets
167
+ - EM::defer @threadqueue now handled more gracefully
168
+ - Added better messages on exceptions raised
169
+ - Fix edge case in timer fires
170
+ - Explicitly require buftok.rb
171
+ - Add protocols to autoload, rather than require them all immediately
172
+ - Fix a bug in pr_eventmachine for outbound_q
173
+ - Refactors to take some of the use of defer out of tests.
174
+ - Fixes in EM.defer under start/stop conditions. Reduced scope of threads.
175
+ 23Sep08: Added patch from tmm1 to avoid popen errors on exit.
176
+ 30Sep08: Added File.exists? checks in the args for start_tls, as suggested by
177
+ Brian Lopez (brianmario).
178
+ 10Nov08: ruby 1.9 compatibility enhancements
179
+ 28Nov08: Allow for older ruby builds where RARRAY_LEN is not defined
180
+ 03Dec08: allow passing arguments to popen handlers
181
+ 13Jan09: SSL support for httpclient2 (David Smalley)
182
+ 22Jan09: Fixed errors on OSX with the kqueue reactor, fixed errors in the pure
183
+ ruby reactor. Added EM.current_time. Added EM.epoll? and EM.kqueue?
184
+ 27Jan09: Reactor errors are now raised as ruby RuntimeErrors.
185
+ 28Jan09: Documentation patch from alloy
186
+ 29Jan09: (Late sign-off) Use a longer timeout for connect_server (Ilya
187
+ Grigorik)
188
+ 07Feb09: Fix signal handling issues with threads+epoll
189
+ 07Feb09: Use rb_thread_schedule in the epoll reactor
190
+ 07Feb09: Use TRAP_BEG/END and rb_thread_schedule in kqueue reactor
191
+ 08Feb09: Added fastfilereader from swiftiply
192
+ 08Feb09: 1.9 fix for rb_trap_immediate
193
+ 08Feb09: Enable rb_thread_blocking_region for 1.9.0 and 1.9.1
194
+ 10Feb09: Support win32 builds for fastfilereader
195
+ 10Feb09: Added a new event to indicate completion of SSL handshake on TCP
196
+ connections
197
+ 10Feb09: Working get_peer_cert method. Returns the certificate as a Ruby
198
+ String in PEM format. (Jake Douglas)
199
+ 10Feb09: Added EM.get_max_timers
200
+ 11Feb09: Fix compile options for sun compiler (Alasdairrr)
201
+ 11Feb09: get_status returns a Process::Status object
202
+ 12Feb09: Add EM::Protocols::Memcache with simple get/set functionality
203
+ 19Feb09: Add catch-all EM.error_handler
204
+ 20Feb09: Support miniunit (1.9)
205
+ 20Feb09: Return success on content-length = 0 instead of start waiting forever
206
+ (Ugo Riboni)
207
+ 25Feb09: Allow next_tick to be used to pre-schedule reactor operations before
208
+ EM.run
209
+ 26Feb09: Added EM.get_connection_count
210
+ 01Mar09: Switch back to extconf for compiling gem extensions
211
+ 01Mar09: fixed a small bug with basic auth (mmmurf)
@@ -0,0 +1,246 @@
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 deferrables. For more information, see the
4
+ separate document LIGHTWEIGHT_CONCURRENCY.
5
+
6
+ === What are Deferrables?
7
+
8
+ EventMachine's Deferrable borrows heavily from the "deferred" object in
9
+ Python's "Twisted" event-handling framework. Here's a minimal example that
10
+ illustrates Deferrable:
11
+
12
+ require 'eventmachine'
13
+
14
+ class MyClass
15
+ include EM::Deferrable
16
+
17
+ def print_value x
18
+ puts "MyClass instance received #{x}"
19
+ end
20
+ end
21
+
22
+ EM.run {
23
+ df = MyClass.new
24
+ df.callback {|x|
25
+ df.print_value(x)
26
+ EM.stop
27
+ }
28
+
29
+ EM::Timer.new(2) {
30
+ df.set_deferred_status :succeeded, 100
31
+ }
32
+ }
33
+
34
+
35
+ This program will spin for two seconds, print out the string "MyClass
36
+ instance received 100" and then exit. The Deferrable pattern relies on
37
+ an unusual metaphor that may be unfamiliar to you, unless you've used
38
+ Python's Twisted. You may need to read the following material through
39
+ more than once before you get the idea.
40
+
41
+ EventMachine::Deferrable is simply a Ruby Module that you can include
42
+ in your own classes. (There also is a class named
43
+ EventMachine::DefaultDeferrable for when you want to create one without
44
+ including it in code of your own.)
45
+
46
+ An object that includes EventMachine::Deferrable is like any other Ruby
47
+ object: it can be created whenever you want, returned from your functions,
48
+ or passed as an argument to other functions.
49
+
50
+ The Deferrable pattern allows you to specify any number of Ruby code
51
+ blocks (callbacks or errbacks) that will be executed at some future time
52
+ when the status of the Deferrable object changes.
53
+
54
+ How might that be useful? Well, imagine that you're implementing an HTTP
55
+ server, but you need to make a call to some other server in order to fulfill
56
+ a client request.
57
+
58
+ When you receive a request from one of your clients, you can create and
59
+ return a Deferrable object. Some other section of your program can add a
60
+ callback to the Deferrable that will cause the client's request to be
61
+ fulfilled. Simultaneously, you initiate an event-driven or threaded client
62
+ request to some different server. And then your EM program will continue to
63
+ process other events and service other client requests.
64
+
65
+ When your client request to the other server completes some time later, you
66
+ will call the #set_deferred_status method on the Deferrable object, passing
67
+ either a success or failure status, and an arbitrary number of parameters
68
+ (which might include the data you received from the other server).
69
+
70
+ At that point, the status of the Deferrable object becomes known, and its
71
+ callback or errback methods are immediately executed. Callbacks and errbacks
72
+ are code blocks that are attached to Deferrable objects at any time through
73
+ the methods #callback and #errback.
74
+
75
+ The deep beauty of this pattern is that it decouples the disposition of one
76
+ operation (such as a client request to an outboard server) from the
77
+ subsequent operations that depend on that disposition (which may include
78
+ responding to a different client or any other operation).
79
+
80
+ The code which invokes the deferred operation (that will eventually result
81
+ in a success or failure status together with associated data) is completely
82
+ separate from the code which depends on that status and data. This achieves
83
+ one of the primary goals for which threading is typically used in
84
+ sophisticated applications, with none of the nondeterminacy or debugging
85
+ difficulties of threads.
86
+
87
+ As soon as the deferred status of a Deferrable becomes known by way of a call
88
+ to #set_deferred_status, the Deferrable will IMMEDIATELY execute all of its
89
+ callbacks or errbacks in the order in which they were added to the Deferrable.
90
+
91
+ Callbacks and errbacks can be added to a Deferrable object at any time, not
92
+ just when the object is created. They can even be added after the status of
93
+ the object has been determined! (In this case, they will be executed
94
+ immediately when they are added.)
95
+
96
+ A call to Deferrable#set_deferred_status takes :succeeded or :failed as its
97
+ first argument. (This determines whether the object will call its callbacks
98
+ or its errbacks.) #set_deferred_status also takes zero or more additional
99
+ parameters, that will in turn be passed as parameters to the callbacks or
100
+ errbacks.
101
+
102
+ In general, you can only call #set_deferred_status ONCE on a Deferrable
103
+ object. A call to #set_deferred_status will not return until all of the
104
+ associated callbacks or errbacks have been called. If you add callbacks or
105
+ errbacks AFTER making a call to #set_deferred_status, those additional
106
+ callbacks or errbacks will execute IMMEDIATELY. Any given callback or
107
+ errback will be executed AT MOST once.
108
+
109
+ It's possible to call #set_deferred_status AGAIN, during the execution a
110
+ callback or errback. This makes it possible to change the parameters which
111
+ will be sent to the callbacks or errbacks farther down the chain, enabling
112
+ some extremely elegant use-cases. You can transform the data returned from
113
+ a deferred operation in arbitrary ways as needed by subsequent users, without
114
+ changing any of the code that generated the original data.
115
+
116
+ A call to #set_deferred_status will not return until all of the associated
117
+ callbacks or errbacks have been called. If you add callbacks or errbacks
118
+ AFTER making a call to #set_deferred_status, those additional callbacks or
119
+ errbacks will execute IMMEDIATELY.
120
+
121
+ Let's look at some more sample code. It turns out that many of the internal
122
+ protocol implementations in the EventMachine package rely on Deferrable. One
123
+ of these is EM::Protocols::HttpClient.
124
+
125
+ To make an evented HTTP request, use the module function
126
+ EM::Protocols::HttpClient#request, which returns a Deferrable object.
127
+ Here's how:
128
+
129
+ require 'eventmachine'
130
+
131
+ EM.run {
132
+ df = EM::Protocols::HttpClient.request( :host=>"www.example.com",
133
+ :request=>"/index.html" )
134
+
135
+ df.callback {|response|
136
+ puts "Succeeded: #{response[:content]}"
137
+ EM.stop
138
+ }
139
+
140
+ df.errback {|response|
141
+ puts "ERROR: #{response[:status]}"
142
+ EM.stop
143
+ }
144
+ }
145
+
146
+ (See the documentation of EventMachine::Protocols::HttpClient for information
147
+ on the object returned by #request.)
148
+
149
+ In this code, we make a call to HttpClient#request, which immediately returns
150
+ a Deferrable object. In the background, an HTTP client request is being made
151
+ to www.example.com, although your code will continue to run concurrently.
152
+
153
+ At some future point, the HTTP client request will complete, and the code in
154
+ EM::Protocols::HttpClient will process either a valid HTTP response (including
155
+ returned content), or an error.
156
+
157
+ At that point, EM::Protocols::HttpClient will call
158
+ EM::Deferrable#set_deferred_status on the Deferrable object that was returned
159
+ to your program, as the return value from EM::Protocols::HttpClient.request.
160
+ You don't have to do anything to make this happen. All you have to do is tell
161
+ the Deferrable what to do in case of either success, failure, or both.
162
+
163
+ In our code sample, we set one callback and one errback. The former will be
164
+ called if the HTTP call succeeds, and the latter if it fails. (For
165
+ simplicity, we have both of them calling EM#stop to end the program, although
166
+ real programs would be very unlikely to do this.)
167
+
168
+ Setting callbacks and errbacks is optional. They are handlers to defined
169
+ events in the lifecycle of the Deferrable event. It's not an error if you
170
+ fail to set either a callback, an errback, or both. But of course your
171
+ program will then fail to receive those notifications.
172
+
173
+ If through some bug it turns out that #set_deferred_status is never called
174
+ on a Deferrable object, then that object's callbacks or errbacks will NEVER
175
+ be called. It's also possible to set a timeout on a Deferrable. If the
176
+ timeout elapses before any other call to #set_deferred_status, the Deferrable
177
+ object will behave as is you had called set_deferred_status(:failed) on it.
178
+
179
+
180
+ Now let's modify the example to illustrate some additional points:
181
+
182
+ require 'eventmachine'
183
+
184
+ EM.run {
185
+ df = EM::Protocols::HttpClient.request( :host=>"www.example.com",
186
+ :request=>"/index.html" )
187
+
188
+ df.callback {|response|
189
+ df.set_deferred_status :succeeded, response[:content]
190
+ }
191
+
192
+ df.callback {|string|
193
+ puts "Succeeded: #{string}"
194
+ EM.stop
195
+ }
196
+
197
+ df.errback {|response|
198
+ puts "ERROR: #{response[:status]}"
199
+ EM.stop
200
+ }
201
+ }
202
+
203
+
204
+ Just for the sake of illustration, we've now set two callbacks instead of
205
+ one. If the deferrable operation (the HTTP client-request) succeeds, then
206
+ both of the callbacks will be executed in order.
207
+
208
+ But notice that we've also made our own call to #set_deferred_status in the
209
+ first callback. This isn't required, because the HttpClient implementation
210
+ already made a call to #set_deferred_status. (Otherwise, of course, the
211
+ callback would not be executing.)
212
+
213
+ But we used #set_deferred_status in the first callback in order to change the
214
+ parameters that will be sent to subsequent callbacks in the chain. In this
215
+ way, you can construct powerful sequences of layered functionality. If you
216
+ want, you can even change the status of the Deferrable from :succeeded to
217
+ :failed, which would abort the chain of callback calls, and invoke the chain
218
+ of errbacks instead.
219
+
220
+ Now of course it's somewhat trivial to define two callbacks in the same
221
+ method, even with the parameter-changing effect we just described. It would
222
+ be much more interesting to pass the Deferrable to some other function (for
223
+ example, a function defined in another module or a different gem), that would
224
+ in turn add callbacks and/or errbacks of its own. That would illustrate the
225
+ true power of the Deferrable pattern: to isolate the HTTP client-request
226
+ from other functions that use the data that it returns without caring where
227
+ those data came from.
228
+
229
+ Remember that you can add a callback or an errback to a Deferrable at any
230
+ point in time, regardless of whether the status of the deferred operation is
231
+ known (more precisely, regardless of when #set_deferred_status is called on
232
+ the object). Even hours or days later.
233
+
234
+ When you add a callback or errback to a Deferrable object on which
235
+ #set_deferred_status has not yet been called, the callback/errback is queued
236
+ up for future execution, inside the Deferrable object. When you add a
237
+ callback or errback to a Deferrable on which #set_deferred_status has
238
+ already been called, the callback/errback will be executed immediately.
239
+ Your code doesn't have to worry about the ordering, and there are no timing
240
+ issues, as there would be with a threaded approach.
241
+
242
+ For more information on Deferrables and their typical usage patterns, look
243
+ in the EM unit tests. There are also quite a few sugarings (including
244
+ EM::Deferrable#future) that make typical Deferrable usages syntactically
245
+ easier to work with.
246
+