The design goals of this gem are:
Supported Ruby versions
MRI 1.9.3, 2.0, 2.1, 2.2, JRuby (1.9 mode), 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 required for JRuby (Java 7 support is deprecated in version 0.9 and will be removed in 1.0).
Features & Documentation
We have a roadmap guiding our work toward the v1.0.0 release.
The primary site for documentation is the automatically generated API documentation
This library contains a variety of concurrency abstractions at high and low levels. One of the high-level abstractions is likely to meet most common needs.
General-purpose Concurrency Abstractions
- Async: A mixin module that provides simple asynchronous behavior to any standard class/object or object.
- Atom: A way to manage shared, synchronous, independent state.
- Future: An asynchronous operation that produces a value.
- Dataflow: Built on Futures, Dataflow allows you to create a task that will be scheduled when all of its data dependencies are available.
- Promise: Similar to Futures, with more features.
- ScheduledTask: Like a Future scheduled for a specific future time.
- TimerTask: A Thread that periodically wakes up to perform work at regular intervals.
Thread-safe Value Objects
MaybeA thread-safe, immutable object representing an optional value, based on Haskell Data.Maybe.
DelayLazy evaluation of a block yielding an immutable result. Based on Clojure's delay.
Derived from Ruby's Struct:
ImmutableStructImmutable struct where values are set at construction and cannot be changed later.
MutableStructSynchronized, mutable struct where values can be safely changed at any time.
SettableStructSynchronized, write-once struct where values can be set at most once, either at construction or any time thereafter.
Java-inspired ThreadPools and Other Executors
- See ThreadPool overview, which also contains a list of other Executors available.
Thread Synchronization Classes and Algorithms
- I-Structures (IVar)
- M-Structures (MVar)
- Thread-local variables
- Software transactional memory (TVar)
These are available in the
concurrent-ruby-edge companion gem, installed with
gem install concurrent-ruby-edge.
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.
- new Future Framework - new
unified implementation of Futures and Promises which combines Features of previous
TimerTaskinto single framework. It uses extensively new synchronization layer to make all the features non-blocking and lock-free with exception of obviously blocking operations like
#value. It also offers better performance.
- Agent: A single atomic value that represents an identity.
- Channel: Communicating Sequential Processes (CSP).
- Atomic Markable Reference
- LockFreeLinked Set
Why are these not in core?
- Actor - Partial documentation and tests; stability is good.
- Future/Promise Framework - API changes; partial documentation and tests; stability good.
- Agent - Incomplete behaviour compared to Clojure's models; stability good.
- Channel - Missing documentation; limted features; stability good.
- Exchanger - Known race condition requiring a new implementation.
- LazyRegister - Missing documentation and tests.
- AtomicMarkableReference, LockFreeLinkedSet, LockFreeStack - Needs real world battle testing
All abstractions within this gem can be loaded simply by requiring it:
To reduce the amount of code loaded at runtime, subsets of this gem can be required:
require 'concurrent' # everything # groups require 'concurrent/atomics' # atomic and thread synchronization classes require 'concurrent/executors' # Thread pools and other executors # individual abstractions require 'concurrent/async' # Concurrent::Async require 'concurrent/atom' # Concurrent::Atom require 'concurrent/dataflow' # Concurrent::dataflow require 'concurrent/delay' # Concurrent::Delay require 'concurrent/future' # Concurrent::Future require 'concurrent/immutable_struct' # Concurrent::ImmutableStruct require 'concurrent/ivar' # Concurrent::IVar require 'concurrent/maybe' # Concurrent::Maybe require 'concurrent/mutable_struct' # Concurrent::MutableStruct require 'concurrent/mvar' # Concurrent::MVar require 'concurrent/promise' # Concurrent::Promise require 'concurrent/scheduled_task' # Concurrent::ScheduledTask require 'concurrent/settable_struct' # Concurrent::SettableStruct require 'concurrent/timer_task' # Concurrent::TimerTask require 'concurrent/tvar' # Concurrent::TVar # experimental - available in `concurrent-ruby-edge` companion gem require 'concurrent/actor' # Concurrent::Actor and supporting code require 'concurrent/edge/future' # new Future Framework require 'concurrent/agent' # Concurrent::Agent require 'concurrent/channel ' # Concurrent::Channel and supporting code
If the library does not behave as expected,
Concurrent.use_stdlib_logger(Logger::DEBUG) could help to reveal the problem.
gem install concurrent-ruby
or add the following line to Gemfile:
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 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:
bundle install from your shell.
In code it is only necessary to
concurrent-ruby gem will automatically detect the presence of the
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.
All published versions of this gem (core, extension, and several platform-specific packages) are compiled, packaged, tested, and published using an open, automated process. This process can also be used to create pre-compiled binaries of the extension gem for virtally any platform. Documentation is forthcoming...
*MRI only* bundle exec rake build:native # Build concurrent-ruby-ext-<version>-<platform>.gem into the pkg dir bundle exec rake compile:extension # Compile extension *JRuby only* bundle exec rake build # Build JRuby-specific core gem (alias for `build:core`) bundle exec rake build:core # Build concurrent-ruby-<version>-java.gem into the pkg directory *All except JRuby* bundle exec rake build:core # Build concurrent-ruby-<version>.gem into the pkg directory bundle exec rake build:ext # Build concurrent-ruby-ext-<version>.gem into the pkg directory *When Docker IS installed* bundle exec rake build:windows # Build the windows binary <version> gems per rake-compiler-dock bundle exec rake build # Build core, extension, and edge gems, including Windows binaries *When Docker is NOT installed* bundle exec rake build # Build core, extension, and edge gems (excluding Windows binaries) *All* bundle exec rake clean # Remove any temporary products bundle exec rake clobber # Remove any generated file bundle exec rake compile # Compile all the extensions
- Fork it
- Create your feature branch (
git checkout -b my-new-feature)
- Commit your changes (
git commit -am 'Add some feature')
- Push to the branch (
git push origin my-new-feature)
- Create new Pull Request
License and Copyright
Concurrent Ruby is free software released under the MIT License.