123456789_123456789_123456789_123456789_123456789_

Concurrent Ruby

Gem Version License Gitter chat

Modern concurrency tools for Ruby. Inspired by Erlang, Clojure, Scala, Haskell, F#, C#, Java, and classic concurrency patterns.

The design goals of this gem are:

Contributing

This gem depends on contributions and we appreciate your help. Would you like to contribute? Great! Have a look at issues with looking-for-contributor label. And if you pick something up let us know on the issue.

You can also get started by triaging issues which may include reproducing bug reports or asking for vital information, such as version numbers or reproduction instructions. If you would like to start triaging issues, one easy way to get started is to subscribe to concurrent-ruby on CodeTriage. Open Source Helpers

Thread Safety

Concurrent Ruby makes one of the strongest thread safety guarantees of any Ruby concurrency library, providing consistent behavior and guarantees on all three main Ruby interpreters (MRI/CRuby, JRuby, TruffleRuby).

Every abstraction in this library is thread safe. 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.

We've also initiated discussion to document the memory model of Ruby which would provide consistent behaviour and guarantees on all three main Ruby interpreters (MRI/CRuby, JRuby, TruffleRuby).

Features & Documentation

The primary site for documentation is the automatically generated API documentation which is up to date with latest release. This readme matches the master so may contain new stuff not yet released.

We also have a IRC (gitter).

Versioning

General-purpose Concurrency Abstractions

Thread-safe Value Objects, Structures, and Collections

Collection classes that were originally part of the (deprecated) thread_safe gem:

Value objects inspired by other languages:

Structure classes derived from Ruby's Struct:

Thread-safe variables:

Java-inspired ThreadPools and Other Executors

Thread Synchronization Classes and Algorithms

Deprecated

Deprecated features are still available and bugs are being fixed, but new features will not be added.

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.

Supported Ruby versions

Usage

Everything within this gem can be loaded simply by requiring it:

require 'concurrent'

You can also require a specific abstraction part of the public documentation since concurrent-ruby 1.2.0, for example:

require 'concurrent/map'
require 'concurrent/atomic/atomic_reference'
require 'concurrent/executor/fixed_thread_pool'

To use the tools in the Edge gem it must be required separately:

require 'concurrent-edge'

If the library does not behave as expected, Concurrent.use_simple_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 minimise 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.

Building the gem

Requirements

Publishing the Gem

Maintainers

Special Thanks to

to the past maintainers

and to Ruby Association for sponsoring a project "Enhancing Ruby’s concurrency tooling" in 2018.

License and Copyright

Concurrent Ruby is free software released under the MIT License.

The Concurrent Ruby logo was designed by David Jones. It is Copyright © 2014 Jerry D'Antonio. All Rights Reserved.