Module: Concurrent

=== Concurrent Ruby

Modern concurrency tools for Ruby. Inspired by href="http://www.erlang.org/doc/reference_manual/processes.html">http://www.erlang.org/doc/reference_manual/processes.html Erlang, Clojure, Scala, Haskell, F#, C#, href="http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/package-summary.html">http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/package-summary.html 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.

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.

==== 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

• 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

• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Async.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Async.html Async: A mixin module that provides simple asynchronous behavior to a class. Loosely based on Erlang's href="http://www.erlang.org/doc/man/gen_server.html">http://www.erlang.org/doc/man/gen_server.html gen_server.
• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/ScheduledTask.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/ScheduledTask.html ScheduledTask: Like a Future scheduled for a specific future time.
• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/TimerTask.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/TimerTask.html TimerTask: A Thread that periodically wakes up to perform work at regular intervals.
• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Promises.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Promises.html Promises: 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:

• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Array.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Array.html Array A thread-safe subclass of Ruby's standard href="http://ruby-doc.org/core/Array.html">http://ruby-doc.org/core/Array.html Array.
• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Hash.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Hash.html Hash A thread-safe subclass of Ruby's standard href="http://ruby-doc.org/core/Hash.html">http://ruby-doc.org/core/Hash.html Hash.
• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Set.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Set.html Set A thread-safe subclass of Ruby's standard href="http://ruby-doc.org/stdlib-2.4.0/libdoc/set/rdoc/Set.html">http://ruby-doc.org/stdlib-2.4.0/libdoc/set/rdoc/Set.html Set.
• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Map.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Map.html Map A hash-like object that should have much better performance characteristics, especially under high concurrency, than Hash.
• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Tuple.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Tuple.html Tuple A fixed size array with volatile (synchronized, thread safe) getters/setters.

Value objects inspired by other languages:

• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Maybe.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Maybe.html Maybe A thread-safe, immutable object representing an optional value, based on Haskell Data.Maybe.

Structure classes derived from Ruby's href="http://ruby-doc.org/core/Struct.html">http://ruby-doc.org/core/Struct.html Struct:

• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/ImmutableStruct.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/ImmutableStruct.html ImmutableStruct Immutable struct where values are set at construction and cannot be changed later.
• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/MutableStruct.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/MutableStruct.html MutableStruct Synchronized, mutable struct where values can be safely changed at any time.
• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/SettableStruct.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/SettableStruct.html SettableStruct Synchronized, write-once struct where values can be set at most once, either at construction or any time thereafter.

Thread-safe variables:

• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Agent.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Agent.html Agent: A way to manage shared, mutable, asynchronous, independent state. Based on Clojure's Agent.
• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Atom.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Atom.html Atom: A way to manage shared, mutable, synchronous, independent state. Based on Clojure's Atom.
• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/AtomicBoolean.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/AtomicBoolean.html AtomicBoolean A boolean value that can be updated atomically.
• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/AtomicFixnum.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/AtomicFixnum.html AtomicFixnum A numeric value that can be updated atomically.
• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/AtomicReference.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/AtomicReference.html AtomicReference An object reference that may be updated atomically.
• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Exchanger.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Exchanger.html Exchanger A synchronization point at which threads can pair and swap elements within pairs. Based on Java's href="http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Exchanger.html">http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Exchanger.html Exchanger.
• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/MVar.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/MVar.html MVar A synchronized single element container. Based on Haskell's href="https://hackage.haskell.org/package/base-4.8.1.0/docs/Control-Concurrent-MVar.html">https://hackage.haskell.org/package/base-4.8.1.0/docs/Control-Concurrent-MVar.html MVar and Scala's MVar.
• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/ThreadLocalVar.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/ThreadLocalVar.html ThreadLocalVar A variable where the value is different for each thread.
• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/TVar.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/TVar.html 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

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

====== Deprecated

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

• ~~href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Future.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Future.html Future: An asynchronous operation that produces a value.~~ Replaced by href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Promises.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Promises.html Promises.
  • ~~.dataflow: Built on Futures, Dataflow allows you to create a task that will be scheduled when all of its data dependencies are available.~~ Replaced by href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Promises.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Promises.html Promises.
• ~~href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Promise.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Promise.html Promise: Similar to Futures, with more features.~~ Replaced by href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Promises.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Promises.html Promises.
• ~~href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Delay.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Delay.html Delay Lazy evaluation of a block yielding an immutable result. Based on Clojure's delay.~~ Replaced by href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Promises.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Promises.html Promises.
• ~~href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/IVar.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/IVar.html IVar Similar to a "future" but can be manually assigned once, after which it becomes immutable.~~ Replaced by href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Promises.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Promises.html Promises.

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

• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Actor.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Actor.html Actor: Implements the Actor Model, where concurrent actors exchange messages. Status: Partial documentation and tests; depends on new future/promise framework; stability is good.
• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Channel.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Channel.html Channel: Communicating Sequential Processes (CSP). Functionally equivalent to Go channels with additional inspiration from Clojure core.async. Status: Partial documentation and tests.
• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/LazyRegister.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/LazyRegister.html LazyRegister
• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Edge/LockFreeLinkedSet.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Edge/LockFreeLinkedSet.html LockFreeLinkedSet Status: will be moved to core soon.
• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/LockFreeStack.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/LockFreeStack.html LockFreeStack Status: missing documentation and tests.
• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Promises/Channel.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Promises/Channel.html Promises::Channel A first in first out channel that accepts messages with push family of methods and returns messages with pop family of methods. Pop and push operations can be represented as futures, see #pop_op and #push_op. The capacity of the channel can be limited to support back pressure, use capacity option in #initialize. #pop method blocks ans #pop_op returns pending future if there is no message in the channel. If the capacity is limited the #push method blocks and #push_op returns pending future.

• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Cancellation.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Cancellation.html Cancellation The Cancellation abstraction provides cooperative cancellation.

  The standard methods Thread#raise of Thread#kill available in Ruby are very dangerous (see linked the blog posts bellow). Therefore concurrent-ruby provides an alternative.

  • https://jvns.ca/blog/2015/11/27/why-rubys-timeout-is-dangerous-and-thread-dot-raise-is-terrifying/
  • http://www.mikeperham.com/2015/05/08/timeout-rubys-most-dangerous-api/
  • http://blog.headius.com/2008/02/rubys-threadraise-threadkill-timeoutrb.html

  It provides an object which represents a task which can be executed, the task has to get the reference to the object and periodically cooperatively check that it is not cancelled. Good practices to make tasks cancellable:

  • check cancellation every cycle of a loop which does significant work,
  • do all blocking actions in a loop with a timeout then on timeout check cancellation and if ok block again with the timeout

• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Throttle.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Throttle.html Throttle A tool managing concurrency level of tasks.

• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/ErlangActor.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/ErlangActor.html ErlangActor Actor implementation which precisely matches Erlang actor behaviour. Requires at least Ruby 2.1 otherwise it's not loaded.

• href="http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/WrappingExecutor.html">http://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/WrappingExecutor.html WrappingExecutor A delegating executor which modifies each task before the task is given to the target executor it delegates to.

==== Supported Ruby versions

• MRI 2.3 and above
• Latest JRuby 9000
• Latest TruffleRuby

==== 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

• Recent CRuby
• JRuby, rbenv install jruby-9.2.17.0
• Set env variable CONCURRENT_JRUBY_HOME to point to it, e.g. /usr/local/opt/rbenv/versions/jruby-9.2.17.0
• Install Docker, required for Windows builds

===== Publishing the Gem

• Update version.rb
• Update the CHANGELOG
• Add the new version to docs-source/signpost.md. Needs to be done only if there are visible changes in the documentation.
• Commit (and push) the changes.
• Use bundle exec rake release to release the gem. It consists of ['release:checks', 'release:build', 'release:test', 'release:publish'] steps. It will ask at the end before publishing anything. Steps can also be executed individually.

==== Maintainers

• Benoit Daloze
• Matthew Draper
• Rafael França
• Charles Oliver Nutter
• Ben Sheldon
• Samuel Williams

===== Special Thanks to

• Jerry D'Antonio for creating the gem
• Brian Durand for the ref gem
• Charles Oliver Nutter for the atomic and thread_safe gems
• thedarkone for the thread_safe gem

to the past maintainers

• Chris Seaton
• Petr Chalupa
• Michele Della Torre
• Paweł Obrok
• Lucas Allan

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.