Skip to content
This repository has been archived by the owner on Dec 7, 2018. It is now read-only.

celluloid/celluloid-io

Repository files navigation

Celluloid::IO

Gem Version MIT licensed Build Status Maintained: no

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, making it easy to combine both threaded and evented concepts. Celluloid::IO is ideal for servers which handle large numbers of mostly-idle connections, such as Websocket servers or chat/messaging systems.

Celluloid::IO provides a different class of actor: one that's slightly slower and heavier than standard Celluloid actors, but one which contains a high-performance reactor just like EventMachine or Cool.io. This means Celluloid::IO actors have the power of both Celluloid actors and evented I/O loops. Unlike certain other evented I/O systems which limit you to a single event loop per process, Celluloid::IO lets you make as many actors as you want, system resources permitting.

Rather than callbacks, Celluloid::IO exposes a synchronous API built on duck types of Ruby's own IO classes, such as TCPServer and TCPSocket. These classes work identically to their core Ruby counterparts, but in the scope of Celluloid::IO actors provide "evented" performance. Since they're drop-in replacements for the standard classes, there's no need to rewrite every library just to take advantage of Celluloid::IO's event loop and you can freely switch between evented and blocking IO even over the lifetime of a single connection.

Celluloid::IO uses the nio4r gem 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 Celluloid Google Group

Documentation

Please see the Celluloid::IO Wiki for more detailed documentation and usage notes.

YARD documentation is also available

Installation

Add this line to your application's Gemfile:

gem 'celluloid-io'

And then execute:

$ bundle

Or install it yourself as:

$ gem install celluloid-io

Inside of your Ruby program, require Celluloid::IO with:

require 'celluloid/io'

Supported Platforms

Celluloid::IO works on all Ruby (MRI) versions between 1.9.3 & 2.3.1, JRuby's 1.6.*, 1.7.* and 9.* series, and Rubinius' 2.* and 3.* series.

JRuby or Rubinius are the preferred platforms as they support true thread-level parallelism when executing Ruby code, whereas MRI/YARV is constrained by a global interpreter lock (GIL) and can only execute one thread at a time.

Celluloid::IO requires Ruby 1.9 mode on all interpreters, at minimum.

Contributing to Celluloid::IO

  • Fork this repository on github
  • Make your changes and send me a pull request
  • If I like them I'll merge them
  • If I've accepted a patch, feel free to ask for a commit bit!

License

Copyright (c) 2011-2016 Tony Arcieri. Distributed under the MIT License. See LICENSE.txt for further details.

Contains code originally from the RubySpec project also under the MIT License. Copyright (c) 2008 Engine Yard, Inc. All rights reserved.

Contains code originally from the 'OpenSSL for Ruby 2' project released under the Ruby license. Copyright (C) 2001 GOTOU YUUZOU. All rights reserved.