Documentation/comparison.haml

   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 OK
  37   %tr.comp_row
  38     %td.mod Rev
  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 OK
  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 RevThreadSpawn
  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 RevThreadPool
  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 RevFiberSpawn
 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 %ul
 122   %li
 123     All Rev-based options can also use "Coolio" instead.  Cool.io should
 124     also work with Rubinius (though we haven't had time to test).
 125   %li
 126     CoolioThread* and RevThread* requires Ruby 1.9 reasonable performance
 127   %li
 128     rack.input streaming is what makes
 129     %a(href="http://upr.bogomips.org/") upload progress,
 130     and BOSH possible
 131   %li
 132     rack.input streaming is NOT compatible with current versions of nginx
 133     or any proxy that fully buffers request bodies before proxying.
 134     Keep in mind request body buffering in nginx is a good thing in all
 135     other cases where rack.input streaming is not needed.
 136
 137 %h2 application requirements
 138 %br
 139 %table.comp
 140   %tr.comp_header
 141     %th.mod module
 142     %th.slowio slow I/O (backend, not client)
 143     %th.thr thread safety
 144     %th.reent single thread reentrant
 145   %tr.comp_base
 146     %td.mod Unicorn/Base
 147     %td.slowio avoid
 148     %td.thr No
 149     %td.reent No
 150   %tr.comp_row
 151     %td.mod Revactor
 152     %td.slowio
 153       %a(href="http://rev.rubyforge.org/")Rev,
 154       %a(href="http://revactor.org/")Revactor,
 155       %b
 156         not
 157       %a(href="Rainbows/Fiber/IO.html")Fiber::IO
 158     %td.thr No
 159     %td.reent Yes
 160   %tr.comp_row
 161     %td.mod ThreadPool
 162     %td.slowio thread-safe Ruby
 163     %td.thr Yes
 164     %td.reent No
 165   %tr.comp_row
 166     %td.mod Rev
 167     %td.slowio
 168       %a(href="http://rev.rubyforge.org/") Rev
 169     %td.thr No
 170     %td.reent No
 171   %tr.comp_row
 172     %td.mod ThreadSpawn
 173     %td.slowio thread-safe Ruby
 174     %td.thr Yes
 175     %td.reent No
 176   %tr.comp_row
 177     %td.mod EventMachine
 178     %td.slowio
 179       %a(href="http://rubyeventmachine.com") EventMachine
 180     %td.thr No
 181     %td.reent No
 182   %tr.comp_row
 183     %td.mod RevThreadSpawn
 184     %td.slowio
 185       thread-safe Ruby,
 186       %a(href="http://rev.rubyforge.org/") Rev
 187     %td.thr Yes
 188     %td.reent No
 189   %tr.comp_row
 190     %td.mod FiberSpawn
 191     %td.slowio
 192       %a(href="Rainbows/Fiber/IO.html") Rainbows::Fiber::IO
 193     %td.thr No
 194     %td.reent Yes
 195   %tr.comp_row
 196     %td.mod FiberPool
 197     %td.slowio
 198       %a(href="Rainbows/Fiber/IO.html") Rainbows::Fiber::IO
 199     %td.thr No
 200     %td.reent Yes
 201   %tr.comp_base
 202     %td.mod ActorSpawn
 203     %td.slowio thread-safe Ruby
 204     %td.thr Yes
 205     %td.reent Yes
 206   %tr.comp_base
 207     %td.mod NeverBlock
 208     %td.slowio
 209       %a(href="http://www.espace.com.eg/neverblock") NeverBlock,
 210       %a(href="http://rubyeventmachine.com") EventMachine
 211     %td.thr No
 212     %td.reent Yes
 213   %tr.comp_row
 214     %td.mod RevThreadPool
 215     %td.slowio
 216       thread-safe Ruby,
 217       %a(href="http://rev.rubyforge.org/") Rev
 218     %td.thr Yes
 219     %td.reent No
 220   %tr.comp_row
 221     %td.mod RevFiberSpawn
 222     %td.slowio
 223       %a(href="Rainbows/Fiber/IO.html") Rainbows::Fiber::IO
 224     %td.thr No
 225     %td.reent Yes
 226   %tr.comp_base
 227     %td.mod WriterThreadPool
 228     %td.slowio avoid
 229     %td.thr Maybe
 230     %td.reent Maybe
 231   %tr.comp_base
 232     %td.mod WriterThreadSpawn
 233     %td.slowio avoid
 234     %td.thr Maybe
 235     %td.reent Maybe
 236 %ul
 237   %li
 238     Requirements for single thread reentrancy are loose in that there is
 239     no risk of race conditions and potentially mutually exclusive to
 240     thread-safety.  In the case where a Fiber yields while holding a
 241     resource and another Fiber attempting to acquire it may raise
 242     an error or worse, deadlock the entire process.
 243   %li
 244     Slow I/O means anything that can block/stall on sockets including
 245     3rd-party APIs (OpenID providers included) or slow database queries.
 246     Properly run Memcached (within the same LAN) is fast and not a blocker.
 247     Slow I/O on POSIX filesystems only includes a few operations, namely
 248     on UNIX domain sockets and named pipes.  Nearly all other operations
 249     on POSIX filesystems can be considered "fast", or at least
 250     uninterruptible.
 251   %li
 252     WriterThread{Pool,Spawn} will require thread safety if your response
 253     body is dynamically generated during the body#each call.
 254
 255 %h2 middlewares and frameworks
 256 %br
 257
 258 %table.comp
 259   %tr.comp_header
 260     %th.mod model
 261     %th.devfd
 262       %a(href="Rainbows/DevFdResponse.html") DevFdResponse
 263     %th.app_pool
 264       %a(href="Rainbows/AppPool.html") AppPool
 265     %th.lock
 266       %a(href="http://rack.rubyforge.org/doc/Rack/Lock.html") Rack::Lock
 267     %th.async async
 268     %th.ws Web Sockets
 269   %tr.comp_row
 270     %td.mod Unicorn/Base
 271     %td.devfd no-op
 272     %td.app_pool no-op
 273     %td.lock no-op
 274     %td.async lots of RAM :P
 275     %td.ws no
 276   %tr.comp_row
 277     %td.mod Revactor
 278     %td.devfd no-op
 279     %td.app_pool Yes
 280     %td.lock No!
 281     %td.async Revactor itself
 282     %td.ws Sunshowers
 283   %tr.comp_row
 284     %td.mod ThreadPool
 285     %td.devfd Yes
 286     %td.app_pool Yes
 287     %td.lock Yes
 288     %td.async standard Ruby
 289     %td.ws Sunshowers
 290   %tr.comp_row
 291     %td.mod Rev
 292     %td.devfd Yes
 293     %td.app_pool no-op
 294     %td.lock no-op
 295     %td.async DevFdResponse
 296     %td.ws no
 297   %tr.comp_row
 298     %td.mod ThreadSpawn
 299     %td.devfd Yes
 300     %td.app_pool Yes
 301     %td.lock Yes
 302     %td.async standard Ruby
 303     %td.ws Sunshowers
 304   %tr.comp_row
 305     %td.mod EventMachine
 306     %td.devfd Yes
 307     %td.app_pool no-op
 308     %td.lock no-op
 309     %td.async async_sinatra, Cramp, rack-fiber_pool
 310     %td.ws no
 311   %tr.comp_row
 312     %td.mod RevThreadSpawn
 313     %td.devfd Yes
 314     %td.app_pool Yes
 315     %td.lock Dumb
 316     %td.async standard Ruby
 317     %td.ws no
 318   %tr.comp_row
 319     %td.mod FiberSpawn
 320     %td.devfd Yes
 321     %td.app_pool Yes
 322     %td.lock No!
 323     %td.async Rainbows::Fiber::IO, Rainbows.sleep
 324     %td.ws Sunshowers
 325   %tr.comp_row
 326     %td.mod FiberPool
 327     %td.devfd Yes
 328     %td.app_pool Yes
 329     %td.lock No!
 330     %td.async Rainbows::Fiber::IO, Rainbows.sleep
 331     %td.ws Sunshowers
 332   %tr.comp_row
 333     %td.mod ActorSpawn
 334     %td.devfd no-op
 335     %td.app_pool Yes
 336     %td.lock Yes
 337     %td.async standard Ruby
 338     %td.ws Sunshowers
 339   %tr.comp_row
 340     %td.mod NeverBlock
 341     %td.devfd Yes
 342     %td.app_pool Yes*
 343     %td.lock Yes*
 344     %td.async NeverBlock, async_sinatra
 345     %td.ws no
 346   %tr.comp_row
 347     %td.mod RevThreadPool
 348     %td.devfd Yes
 349     %td.app_pool Yes
 350     %td.lock Dumb
 351     %td.async Rev, standard Ruby
 352     %td.ws no
 353   %tr.comp_row
 354     %td.mod RevFiberSpawn
 355     %td.devfd Yes
 356     %td.app_pool Yes
 357     %td.lock No!
 358     %td.async Rev, Rainbows::Fiber::IO, Rainbows.sleep
 359   %tr.comp_row
 360     %td.mod WriterThreadPool
 361     %td.devfd Yes
 362     %td.app_pool no-op
 363     %td.lock no-op
 364     %td.async Standard Ruby in response body only
 365     %td.ws response body only
 366   %tr.comp_row
 367     %td.mod WriterThreadSpawn
 368     %td.devfd Yes
 369     %td.app_pool no-op
 370     %td.lock no-op
 371     %td.async Standard Ruby in response body only
 372     %td.ws response body only
 373 %ul
 374   %li
 375     "No!" means it's fundamentally incompatible, use an
 376     %a(href="Rainbows/AppPool.html") AppPool
 377     %b :size
 378     of one instead.
 379   %li
 380     NeverBlock also supports a :pool_size option which is one less
 381     layer of complexity than using AppPool.
 382   %li
 383     NeverBlock can neuter the Mutex class so Rack::Lock effectively
 384     becomes a no-op with:
 385     %br
 386     %code require "never_block/frameworks/rails"
 387     (before Rails is loaded)
 388   %li
 389     Everything that's DevFdResponse-compatible can use it for passing
 390     async responses through