-devs%20%26%20users-brightgreen.svg){kind=icon}
|
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:
|
|
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 preferred for JRuby but every Java version on which JRuby 9000 runs will be supported.
We have a roadmap guiding our work toward the v1.0.0 release.
The primary site for documentation is the automatically generated API documentation
We also have a mailing list and IRC (gitter).
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.
- Async: A mixin module that provides simple asynchronous behavior to a class. Loosely based on Erlang's gen_server.
- 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.
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.
- 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:
- Maybe A thread-safe, immutable object representing an optional value, based on Haskell Data.Maybe.
- Delay Lazy evaluation of a block yielding an immutable result. Based on Clojure's delay.
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.
- See the thread pool overview, which also contains a list of other Executors available.
- 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.
- IVar Similar to a "future" but can be manually assigned once, after which it becomes immutable.
- 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.
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.
- New Future Framework:
Unified implementation of futures and promises which combines features of previous
Future,Promise,IVar,Event,dataflow,Delay, andTimerTaskinto 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. - New channel: Functionally equivalent to Go channels with additional inspiration from Clojure core.async.
- Old channel: Communicating Sequential Processes (CSP).
- LazyRegister
- AtomicMarkableReference
- LockFreeLinkedSet
- LockFreeStack
Why are these not in core?
- Actor - Partial documentation and tests; depends on new future/promise framework; stability is good.
- Future/Promise Framework - API changes; partial documentation and tests; stability good.
- New channel - Missing documentation; very new; stability good.
- Old channel - Deprecated; missing documentation; limited features.
- LazyRegister - Missing documentation and tests.
- AtomicMarkableReference, LockFreeLinkedSet, LockFreeStack - Need real world battle testing
Everything within this gem can be loaded simply by requiring it:
require 'concurrent'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.
gem install concurrent-rubyor add the following line to Gemfile:
gem 'concurrent-ruby'and run bundle install from your shell.
The Edge gem must be installed separately from the core gem:
gem install concurrent-ruby-edgeor add the following line to Gemfile:
gem 'concurrent-ruby-edge'and run bundle install from your shell.
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-extor 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.
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 virtually 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
- Brian Durand for the
refgem - Charles Oliver Nutter for the
atomicandthread_safegems - thedarkone for the
thread_safegem
- 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
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.