| blob | 4fd02ebbf55a24f75da635078f854bbe143d721b |
1 %h1 Rainbows! at a glance
2 %p
3 Confused by all the options we give you? So are we! Here's some tables
4 to help keep your head straight. Remember, engineering is all about
5 trade-offs.
6 %h2 core features and compatibility
7 %br
8 %table.comp
9 %tr.comp_header
10 %th.mod module
11 %th.tee rack.input streaming
12 %th.r18 Ruby 1.8
13 %th.r19 Ruby 1.9
14 %th.rbx Rubinius
15 %th.slow slow clients
16 %tr.comp_base
17 %td.mod Unicorn/Base
18 %td.tee Yes
19 %td.r18 Yes
20 %td.r19 Yes
21 %td.rbx Yes
22 %td.slow No
23 %tr.comp_row
24 %td.mod Revactor
25 %td.tee Yes
26 %td.r18 No
27 %td.r19 Yes
28 %td.rbx No
29 %td.slow Yes
30 %tr.comp_row
31 %td.mod ThreadPool
32 %td.tee Yes
33 %td.r18 Yes
34 %td.r19 Yes
35 %td.rbx Yes
36 %td.slow Yes
37 %tr.comp_row
38 %td.mod Coolio
39 %td.tee No
40 %td.r18 Yes
41 %td.r19 Yes
42 %td.rbx No
43 %td.slow Yes
44 %tr.comp_row
45 %td.mod ThreadSpawn
46 %td.tee Yes
47 %td.r18 Yes
48 %td.r19 Yes
49 %td.rbx Yes
50 %td.slow Yes
51 %tr.comp_row
52 %td.mod EventMachine
53 %td.tee No
54 %td.r18 Yes
55 %td.r19 Yes
56 %td.rbx No
57 %td.slow Yes
58 %tr.comp_row
59 %td.mod CoolioThreadSpawn
60 %td.tee No
61 %td.r18 No
62 %td.r19 Yes
63 %td.rbx No
64 %td.slow Yes
65 %tr.comp_row
66 %td.mod FiberSpawn
67 %td.tee Yes
68 %td.r18 No
69 %td.r19 Yes
70 %td.rbx No
71 %td.slow Yes
72 %tr.comp_row
73 %td.mod FiberPool
74 %td.tee Yes
75 %td.r18 No
76 %td.r19 Yes
77 %td.rbx No
78 %td.slow Yes
79 %tr.comp_base
80 %td.mod ActorSpawn
81 %td.tee Yes
82 %td.r18 Not yet
83 %td.r19 No
84 %td.rbx Yes
85 %td.slow Yes
86 %tr.comp_base
87 %td.mod NeverBlock
88 %td.tee No
89 %td.r18 Yes
90 %td.r19 Yes
91 %td.rbx No
92 %td.slow Yes
93 %tr.comp_row
94 %td.mod CoolioThreadPool
95 %td.tee No
96 %td.r18 Yes
97 %td.r19 No
98 %td.rbx No
99 %td.slow Yes
100 %tr.comp_row
101 %td.mod CoolioFiberSpawn
102 %td.tee Yes
103 %td.r18 No
104 %td.r19 Yes
105 %td.rbx No
106 %td.slow Yes
107 %tr.comp_row
108 %td.mod WriterThreadPool
109 %td.tee Yes
110 %td.r18 Yes
111 %td.r19 Yes
112 %td.rbx Yes
113 %td.slow no
114 %tr.comp_row
115 %td.mod WriterThreadSpawn
116 %td.tee Yes
117 %td.r18 Yes
118 %td.r19 Yes
119 %td.rbx Yes
120 %td.slow no
121 %tr.comp_row
122 %td.mod Epoll
123 %td.tee no
124 %td.r18 Yes
125 %td.r19 Yes
126 %td.rbx Yes
127 %td.slow Yes
128 %tr.comp_row
129 %td.mod XEpoll
130 %td.tee no
131 %td.r18 Yes
132 %td.r19 Yes
133 %td.rbx Yes
134 %td.slow Yes
135 %tr.comp_row
136 %td.mod XEpollThreadSpawn
137 %td.tee Yes
138 %td.r18 Yes
139 %td.r19 Yes
140 %td.rbx Yes
141 %td.slow Yes
142 %tr.comp_row
143 %td.mod XEpollThreadPool
144 %td.tee Yes
145 %td.r18 Yes
146 %td.r19 Yes
147 %td.rbx Yes
148 %td.slow Yes
149 %ul
150 %li
151 Cool.io should also work with Rubinius (though we haven't had time to test).
152 %li
153 CoolioThread* and CoolioThread* requires Ruby 1.9 reasonable performance
154 %li
155 rack.input streaming is what makes
156 %a(href="http://upr.bogomips.org/") upload progress,
157 and BOSH possible
158 %li
159 rack.input streaming is NOT compatible with current versions of nginx
160 or any proxy that fully buffers request bodies before proxying.
161 Keep in mind request body buffering in nginx is a good thing in all
162 other cases where rack.input streaming is not needed.
164 %h2 application requirements
165 %br
166 %table.comp
167 %tr.comp_header
168 %th.mod module
169 %th.slowio slow I/O (backend, not client)
170 %th.thr thread safety
171 %th.reent single thread reentrant
172 %tr.comp_base
173 %td.mod Unicorn/Base
174 %td.slowio avoid
175 %td.thr No
176 %td.reent No
177 %tr.comp_row
178 %td.mod Revactor
179 %td.slowio
180 %a(href="http://coolio.github.com/")Coolio,
181 %a(href="http://revactor.org/")Revactor,
182 %b
183 not
184 %a(href="Rainbows/Fiber/IO.html")Fiber::IO
185 %td.thr No
186 %td.reent Yes
187 %tr.comp_row
188 %td.mod ThreadPool
189 %td.slowio thread-safe Ruby
190 %td.thr Yes
191 %td.reent No
192 %tr.comp_row
193 %td.mod Coolio
194 %td.slowio
195 %a(href="http://coolio.github.com/") Coolio
196 %td.thr No
197 %td.reent No
198 %tr.comp_row
199 %td.mod ThreadSpawn
200 %td.slowio thread-safe Ruby
201 %td.thr Yes
202 %td.reent No
203 %tr.comp_row
204 %td.mod EventMachine
205 %td.slowio
206 %a(href="http://rubyeventmachine.com") EventMachine
207 %td.thr No
208 %td.reent No
209 %tr.comp_row
210 %td.mod CoolioThreadSpawn
211 %td.slowio
212 thread-safe Ruby,
213 %a(href="http://coolio.github.com/") Coolio
214 %td.thr Yes
215 %td.reent No
216 %tr.comp_row
217 %td.mod FiberSpawn
218 %td.slowio
219 %a(href="Rainbows/Fiber/IO.html") Rainbows::Fiber::IO
220 %td.thr No
221 %td.reent Yes
222 %tr.comp_row
223 %td.mod FiberPool
224 %td.slowio
225 %a(href="Rainbows/Fiber/IO.html") Rainbows::Fiber::IO
226 %td.thr No
227 %td.reent Yes
228 %tr.comp_base
229 %td.mod ActorSpawn
230 %td.slowio thread-safe Ruby
231 %td.thr Yes
232 %td.reent Yes
233 %tr.comp_base
234 %td.mod NeverBlock
235 %td.slowio
236 %a(href="http://www.espace.com.eg/neverblock") NeverBlock,
237 %a(href="http://rubyeventmachine.com") EventMachine
238 %td.thr No
239 %td.reent Yes
240 %tr.comp_row
241 %td.mod CoolioThreadPool
242 %td.slowio
243 thread-safe Ruby,
244 %a(href="http://coolio.github.com/") Coolio
245 %td.thr Yes
246 %td.reent No
247 %tr.comp_row
248 %td.mod CoolioFiberSpawn
249 %td.slowio
250 %a(href="Rainbows/Fiber/IO.html") Rainbows::Fiber::IO
251 %td.thr No
252 %td.reent Yes
253 %tr.comp_base
254 %td.mod WriterThreadPool
255 %td.slowio avoid
256 %td.thr Maybe
257 %td.reent Maybe
258 %tr.comp_base
259 %td.mod WriterThreadSpawn
260 %td.slowio avoid
261 %td.thr Maybe
262 %td.reent Maybe
263 %tr.comp_base
264 %td.mod Epoll
265 %td.slowio No
266 %td.thr No
267 %td.reent No
268 %tr.comp_base
269 %td.mod XEpoll
270 %td.slowio No
271 %td.thr No
272 %td.reent No
273 %tr.comp_base
274 %td.mod XEpollThreadSpawn
275 %td.slowio thread-safe Ruby
276 %td.thr Yes
277 %td.reent No
278 %tr.comp_base
279 %td.mod XEpollThreadPool
280 %td.slowio thread-safe Ruby
281 %td.thr Yes
282 %td.reent No
283 %ul
284 %li
285 Requirements for single thread reentrancy are loose in that there is
286 no risk of race conditions and potentially mutually exclusive to
287 thread-safety. In the case where a Fiber yields while holding a
288 resource and another Fiber attempting to acquire it may raise
289 an error or worse, deadlock the entire process.
290 %li
291 Slow I/O means anything that can block/stall on sockets including
292 3rd-party APIs (OpenID providers included) or slow database queries.
293 Properly run Memcached (within the same LAN) is fast and not a blocker.
294 Slow I/O on POSIX filesystems only includes a few operations, namely
295 on UNIX domain sockets and named pipes. Nearly all other operations
296 on POSIX filesystems can be considered "fast", or at least
297 uninterruptible.
298 %li
299 WriterThread{Pool,Spawn} will require thread safety if your response
300 body is dynamically generated during the body#each call.
302 %h2 middlewares and frameworks
303 %br
305 %table.comp
306 %tr.comp_header
307 %th.mod model
308 %th.devfd
309 %a(href="Rainbows/DevFdResponse.html") DevFdResponse
310 %th.app_pool
311 %a(href="Rainbows/AppPool.html") AppPool
312 %th.lock
313 %a(href="http://rdoc.info/gems/rack/Rack/Lock") Rack::Lock
314 %th.async async
315 %tr.comp_row
316 %td.mod Unicorn/Base
317 %td.devfd no-op
318 %td.app_pool no-op
319 %td.lock no-op
320 %td.async lots of RAM :P
321 %tr.comp_row
322 %td.mod Revactor
323 %td.devfd no-op
324 %td.app_pool Yes
325 %td.lock No!
326 %td.async Revactor itself
327 %tr.comp_row
328 %td.mod ThreadPool
329 %td.devfd Yes
330 %td.app_pool Yes
331 %td.lock Yes
332 %td.async thread-safe Ruby
333 %tr.comp_row
334 %td.mod Coolio
335 %td.devfd Yes
336 %td.app_pool no-op
337 %td.lock no-op
338 %td.async DevFdResponse
339 %tr.comp_row
340 %td.mod ThreadSpawn
341 %td.devfd Yes
342 %td.app_pool Yes
343 %td.lock Yes
344 %td.async thread-safe Ruby
345 %tr.comp_row
346 %td.mod EventMachine
347 %td.devfd Yes
348 %td.app_pool no-op
349 %td.lock no-op
350 %td.async async_sinatra, Cramp, rack-fiber_pool
351 %tr.comp_row
352 %td.mod CoolioThreadSpawn
353 %td.devfd Yes
354 %td.app_pool Yes
355 %td.lock Dumb
356 %td.async thread-safe Ruby
357 %tr.comp_row
358 %td.mod FiberSpawn
359 %td.devfd Yes
360 %td.app_pool Yes
361 %td.lock No!
362 %td.async Rainbows::Fiber::IO, Rainbows.sleep
363 %tr.comp_row
364 %td.mod FiberPool
365 %td.devfd Yes
366 %td.app_pool Yes
367 %td.lock No!
368 %td.async Rainbows::Fiber::IO, Rainbows.sleep
369 %tr.comp_row
370 %td.mod ActorSpawn
371 %td.devfd no-op
372 %td.app_pool Yes
373 %td.lock Yes
374 %td.async thread-safe Ruby
375 %tr.comp_row
376 %td.mod NeverBlock
377 %td.devfd Yes
378 %td.app_pool Yes*
379 %td.lock Yes*
380 %td.async NeverBlock, async_sinatra
381 %tr.comp_row
382 %td.mod CoolioThreadPool
383 %td.devfd Yes
384 %td.app_pool Yes
385 %td.lock Dumb
386 %td.async Coolio, thread-safe Ruby
387 %tr.comp_row
388 %td.mod CoolioFiberSpawn
389 %td.devfd Yes
390 %td.app_pool Yes
391 %td.lock No!
392 %td.async Coolio, Rainbows::Fiber::IO, Rainbows.sleep
393 %tr.comp_row
394 %td.mod WriterThreadPool
395 %td.devfd Yes
396 %td.app_pool no-op
397 %td.lock no-op
398 %td.async thread-safe Ruby in response body only
399 %tr.comp_row
400 %td.mod WriterThreadSpawn
401 %td.devfd Yes
402 %td.app_pool no-op
403 %td.lock no-op
404 %td.async thread-safe Ruby in response body only
405 %tr.comp_row
406 %td.mod Epoll
407 %td.devfd Yes
408 %td.app_pool no-op
409 %td.lock no-op
410 %td.async DevFdResponse
411 %tr.comp_row
412 %td.mod XEpoll
413 %td.devfd Yes
414 %td.app_pool no-op
415 %td.lock no-op
416 %td.async DevFdResponse
417 %tr.comp_row
418 %td.mod XEpollThreadPool
419 %td.devfd Yes
420 %td.app_pool Yes
421 %td.lock Yes
422 %td.async thread-safe Ruby
423 %tr.comp_row
424 %td.mod XEpollThreadSpawn
425 %td.devfd Yes
426 %td.app_pool Yes
427 %td.lock Yes
428 %td.async thread-safe Ruby
429 %ul
430 %li
431 "No!" means it's fundamentally incompatible, use an
432 %a(href="Rainbows/AppPool.html") AppPool
433 %b :size
434 of one instead.
435 %li
436 NeverBlock also supports a :pool_size option which is one less
437 layer of complexity than using AppPool.
438 %li
439 NeverBlock can neuter the Mutex class so Rack::Lock effectively
440 becomes a no-op with:
441 %br
442 %code require "never_block/frameworks/rails"
443 (before Rails is loaded)
444 %li
445 Everything that's DevFdResponse-compatible can use it for passing
446 async responses through