README.md in celluloid-io-0.12.1 vs README.md in celluloid-io-0.13.0.pre
- old
+ new
@@ -1,9 +1,10 @@
=============
[](http://travis-ci.org/celluloid/celluloid-io)
[](https://gemnasium.com/celluloid/celluloid-io)
+[](https://codeclimate.com/github/celluloid/celluloid-io)
You don't have to choose between threaded and evented IO! Celluloid::IO
provides an event-driven IO system for building fast, scalable network
applications that integrates directly with the
[Celluloid actor library](https://github.com/celluloid/celluloid), making it
@@ -32,9 +33,40 @@
to monitor IO objects, which provides cross-platform and cross-Ruby
implementation access to high-performance system calls such as epoll
and kqueue.
Like Celluloid::IO? [Join the Google Group](http://groups.google.com/group/celluloid-ruby)
+
+When should I use Celluloid::IO?
+--------------------------------
+
+Unlike systems like Node.js, Celluloid does not require that all I/O be
+"evented". Celluloid fully supports any libraries that support blocking I/O
+and for the *overwhelming majority* of use cases blocking I/O is more than
+sufficient. Using blocking I/O means that any Ruby library you want will
+Just Work without resorting to any kind of theatrics.
+
+Celluloid::IO exists for a few reasons:
+
+* During a blocking I/O operation, Celluloid actors cannot respond to incoming
+ messages to their mailboxes. They will process messages as soon as the
+ method containing a blocking I/O operation completes, however until this
+ happens the entire actor is blocked. If you would like to multiplex both
+ message processing and I/O operations, you will want to use Celluloid::IO.
+ This is especially important for *indefinite* blocking operations, such as
+ listening for incoming TCP connections.
+* Celluloid uses a native thread per actor. While native threads aren't
+ particularly expensive in Ruby (~20kB of RAM), you can use less RAM using
+ Celluloid::IO. You might consider using Celluloid::IO over an
+ actor-per-connection if you are dealing with 10,000 connections or more.
+* The goal of Celluloid::IO is to fully integrate it into the Celluloid
+ ecosystem, including DCell. DCell will hopefully eventually support
+ serializable I/O handles that you can seamlessly transfer between nodes.
+
+All that said, if you are just starting out with Celluloid, you probably want
+to start off using blocking I/O until you understand the fundamentals of
+Celluloid and have encountered one of the above reasons for switching
+over to Celluloid::IO.
Supported Platforms
-------------------
Celluloid::IO requires Ruby 1.9 support on all Ruby VMs.