README.md

Concurrent Ruby

Be an 'unopinionated' toolbox that provides useful utilities without debating which is better or why

Remain free of external gem dependencies

Stay true to the spirit of the languages providing inspiration

But implement in a way that makes sense for Ruby

Keep the semantics as idiomatic Ruby as possible

Support features that make sense in Ruby

Exclude features that don't make sense in Ruby

Be small, lean, and loosely coupled

Supported Ruby versions

MRI 1.9.3, 2.0 and above, JRuby 1.7x in 1.9 mode, JRuby 9000, and Rubinius 2.x are supported.
This gem should be fully compatible with any interpreter that is compliant with Ruby 1.9.3 or newer.
Java 8 is preferred for JRuby but every Java version on which JRuby 9000 runs is supported.

Thread Safety

Concurrent Ruby makes the strongest thread safety guarantees of any Ruby concurrency library. We are the only library with a published memory model which provides consistent behavior and guarantees on all three of the main Ruby interpreters (MRI/CRuby, JRuby, and Rubinius).

Every abstraction in this library is thread safe. Similarly, all are deadlock free and many are fully lock free. Specific thread safety guarantees are documented with each abstraction.

It is critical to remember, however, that Ruby is a language of mutable references. No concurrency library for Ruby can ever prevent the user from making thread safety mistakes (such as sharing a mutable object between threads and modifying it on both threads) or from creating deadlocks through incorrect use of locks. All the library can do is provide safe abstractions which encourage safe practices. Concurrent Ruby provides more safe concurrency abstractions than any other Ruby library, many of which support the mantra of "Do not communicate by sharing memory; instead, share memory by communicating". Concurrent Ruby is also the only Ruby library which provides a full suite of thread safe and immutable variable types and data structures.

Edge Features

These are available in the concurrent-ruby-edge companion gem.

These features are under active development and may change frequently. They are expected not to
keep backward compatibility (there may also lack tests and documentation). Semantic versions will
be obeyed though. Features developed in concurrent-ruby-edge are expected to move to concurrent-ruby when final.

New Future Framework:
Unified implementation of futures and promises which combines features of previous Future,
Promise, IVar, Event, dataflow, Delay, and TimerTask into a single framework. It extensively uses the
new synchronization layer to make all the features non-blocking and lock-free, with the exception of obviously blocking
operations like #wait, #value. It also offers better performance.

Usage

If the library does not behave as expected, Concurrent.use_stdlib_logger(Logger::DEBUG) could help to reveal the problem.

Installation

gem install concurrent-ruby

or add the following line to Gemfile:

gem'concurrent-ruby', require:'concurrent'

and run bundle install from your shell.

Edge Gem Installation

The Edge gem must be installed separately from the core gem:

gem install concurrent-ruby-edge

or add the following line to Gemfile:

gem'concurrent-ruby-edge', require:'concurrent-edge'

and run bundle install from your shell.

C Extensions for MRI

Potential performance improvements may be achieved under MRI by installing optional C extensions.
To minimize installation errors the C extensions are available in the concurrent-ruby-ext extension
gem. concurrent-ruby and concurrent-ruby-ext are always released together with same version.
Simply install the extension gem too:

gem install concurrent-ruby-ext

or add the following line to Gemfile:

gem'concurrent-ruby-ext'

and run bundle install from your shell.

In code it is only necessary to

require'concurrent'

The concurrent-ruby gem will automatically detect the presence of the concurrent-ruby-ext gem
and load the appropriate C extensions.

Note For gem developers

No gems should depend on concurrent-ruby-ext. Doing so will force C extensions on your users.
The best practice is to depend on concurrent-ruby and let users to decide if they want C extensions.