Modern concurrency tools including agents, futures, promises, thread pools, supervisors, and more. Inspired by Erlang, Clojure, Scala, Go, Java, JavaScript, and classic concurrency patterns.
Ruby Java Other
Latest commit 83bedd8 Jul 13, 2018
Permalink
Failed to load latest commit information.
.github Update documentation Jul 10, 2018
benchmarks Use full truffleruby name May 23, 2018
build-tests Fixed circular reference with native extensions. Sep 24, 2015
doc Merge pull request #687 from olleolleolle/documentation-promises Feb 21, 2018
examples Examples: Try to make sentence read clearer Dec 9, 2017
ext Add sleep_interruptibly utility method to allow sleep and block threa… Jul 7, 2018
lib-edge Add flat aliases Jul 10, 2018
lib Rename Promises::FactoryMethods.create to make_future to avoid name c… Jul 10, 2018
spec fix a typo on the timer_task_spec Jul 13, 2018
support Simplify/merge rake tasks Jul 10, 2018
yard-template/default More documentation Dec 23, 2016
.gitignore Fix .gitignore May 7, 2018
.rspec Output Ruby warnings when running rspec Feb 3, 2017
.travis.yml Drop support for CRuby 1.9, JRuby 1.7, Rubinius. Add TruffleRuby Jul 7, 2018
.yardopts Doc update Jul 10, 2018
BUILDING.md Added CoC, contributor guidelines, and updated README. Oct 5, 2015
CHANGELOG.md Update CHANGELOG.md Jul 12, 2018
CODE_OF_CONDUCT.md Update documentation Jul 10, 2018
Gemfile Update gemspec, gemfile, support files Jul 7, 2018
LICENSE.txt Improving documentation Jun 14, 2014
README.md Update README.md Jul 12, 2018
Rakefile Simplify/merge rake tasks Jul 10, 2018
appveyor.yml Added more Appveyor build targets. Aug 9, 2015
concurrent-ruby-edge.gemspec Split of clearly edge gem files Jul 10, 2018
concurrent-ruby-ext.gemspec Update gemspec, gemfile, support files Jul 7, 2018
concurrent-ruby.gemspec Fix left over require Jul 11, 2018

README.md

Concurrent Ruby

Gem Version Build Status Build status 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:

  • 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
  • Thread-safety
  • Backward compatibility

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.

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 of the main Ruby interpreters (MRI/CRuby, JRuby, and Rubinius).

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 memory model of Ruby which would provide consistent behaviour and guarantees on all three of the main Ruby interpreters (MRI/CRuby, JRuby, Rubinius, 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

  • concurrent-ruby uses Semantic Versioning
  • concurrent-ruby-ext has always same version as concurrent-ruby
  • concurrent-ruby-edge will always be 0.y.z therefore following point 4 applies "Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable." However we additionally use following rules:
    • Minor version increment means incompatible changes were made
    • Patch version increment means only compatible changes were made

General-purpose Concurrency Abstractions

  • Async: A mixin module that provides simple asynchronous behavior to a class. Loosely based on Erlang's gen_server.
  • ScheduledTask: Like a Future scheduled for a specific future time.
  • TimerTask: A Thread that periodically wakes up to perform work at regular intervals.
  • Promises Framework: Unified implementation of futures and promises which combines features of previous Future, Promise, IVar, Event, dataflow, Delay, and (partially) 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.

Thread-safe Value Objects, Structures, and Collections

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

  • Array A thread-safe subclass of Ruby's standard Array.
  • Hash A thread-safe subclass of Ruby's standard Hash.
  • Set A thread-safe subclass of Ruby's standard Set.
  • Map A hash-like object that should have much better performance characteristics, especially under high concurrency, than Concurrent::Hash.
  • Tuple A fixed size array with volatile (synchronized, thread safe) getters/setters.

Value objects inspired by other languages:

Structure classes derived from Ruby's Struct:

  • ImmutableStruct Immutable struct where values are set at construction and cannot be changed later.
  • MutableStruct Synchronized, mutable struct where values can be safely changed at any time.
  • SettableStruct Synchronized, write-once struct where values can be set at most once, either at construction or any time thereafter.

Thread-safe variables:

  • Agent: A way to manage shared, mutable, asynchronous, independent state. Based on Clojure's Agent.
  • Atom: A way to manage shared, mutable, synchronous, independent state. Based on Clojure's Atom.
  • AtomicBoolean A boolean value that can be updated atomically.
  • AtomicFixnum A numeric value that can be updated atomically.
  • AtomicReference An object reference that may be updated atomically.
  • Exchanger A synchronization point at which threads can pair and swap elements within pairs. Based on Java's Exchanger.
  • MVar A synchronized single element container. Based on Haskell's MVar and Scala's MVar.
  • ThreadLocalVar A variable where the value is different for each thread.
  • TVar A transactional variable implementing software transactional memory (STM). Based on Clojure's Ref.

Java-inspired ThreadPools and Other Executors

  • See the thread pool overview, which also contains a list of other Executors available.

Thread Synchronization Classes and Algorithms

  • CountDownLatch A synchronization object that allows one thread to wait on multiple other threads.
  • CyclicBarrier A synchronization aid that allows a set of threads to all wait for each other to reach a common barrier point.
  • Event Old school kernel-style event.
  • ReadWriteLock A lock that supports multiple readers but only one writer.
  • ReentrantReadWriteLock A read/write lock with reentrant and upgrade features.
  • Semaphore A counting-based locking mechanism that uses permits.
  • AtomicMarkableReference

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.

  • Actor: Implements the Actor Model, where concurrent actors exchange messages. Status: Partial documentation and tests; depends on new future/promise framework; stability is good.
  • Channel: Communicating Sequential Processes (CSP). Functionally equivalent to Go channels with additional inspiration from Clojure core.async. Status: Partial documentation and tests.
  • LazyRegister
  • LockFreeLinkedSet Status: will be moved to core soon.
  • LockFreeStack Status: missing documentation and tests.

Supported Ruby versions

MRI 2.0 and above, JRuby 9000, TruffleRuby are supported. This gem should be fully compatible with any interpreter that is compliant with Ruby 2.0 or newer. Java 8 is preferred for JRuby but every Java version on which JRuby 9000 runs is supported.

The legacy support for Rubinius is kept but it is no longer maintained, if you would like to help please respond to #739.

Usage

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

require 'concurrent'

Requiring only specific abstractions from Concurrent Ruby is not yet supported.

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_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 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.

Maintainers

Special Thanks

Maintainers of the past

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.