concurrent-ruby

Modern concurrency tools including agents, futures, promises, thread pools, supervisors, and more. Inspired by Erlang, Clojure, Scala, Go, Java, JavaScript, and classic concurrency patterns.

Subscribe to updates I use concurrent-ruby


Statistics on concurrent-ruby

Number of watchers on Github 3987
Number of open issues 65
Average time to close an issue 18 days
Main language Ruby
Average time to merge a PR 4 days
Open pull requests 41+
Closed pull requests 18+
Last commit 11 months ago
Repo Created over 5 years ago
Repo Last Updated 10 months ago
Size 10.8 MB
Homepage http://www.concur...
Organization / Authorruby-concurrency
Latest Releasev1.0.5
Contributors52
Page Updated
Do you use concurrent-ruby? Leave a review!
View open issues (65)
View concurrent-ruby activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating concurrent-ruby for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

Concurrent Ruby

Gem Version Build Status Build status Code Climate Inline docs Dependency 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

Supported Ruby versions

MRI 1.9.3, 2.0 and above, JRuby 1.7x in 1.9 mode, JRuby 9000, 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 is supported.

Thread Safety

Concurrent Ruby makes the strongest thread safety guarantees of any Ruby concurrency library. We are the only library with a published memory model which provides 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. Similarly, all are deadlock free and many are fully lock free. 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.

Features & Documentation

The primary site for documentation is the automatically generated API documentation

We also have a mailing list and IRC (gitter).

General-purpose Concurrency Abstractions

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

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:

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

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

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.

  • Promises Framework: Unified implementation of futures and promises which combines features of previous Future, Promise, IVar, Event, dataflow, Delay, and 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.
  • Actor: Implements the Actor Model, where concurrent actors exchange messages.
  • Channel: Communicating Sequential Processes (CSP). Functionally equivalent to Go channels with additional inspiration from Clojure core.async.
  • LazyRegister
  • AtomicMarkableReference
  • LockFreeLinkedSet
  • LockFreeStack

Statuses:

Why are these not in core?

  • Promises Framework - They are being finalized to be able to be moved to core. They'll deprecate old implementation.
  • Actor - Partial documentation and tests; depends on new future/promise framework; stability is good.
  • Channel - Brand new implementation; partial documentation and tests; stability is good.
  • LazyRegister - Missing documentation and tests.
  • AtomicMarkableReference, LockFreeLinkedSet, LockFreeStack - Need real world battle testing.

Usage

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.

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

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.

concurrent-ruby open issues Ask a question     (View All Issues)
  • about 2 years Promise.all? behavior
  • about 2 years Allow concurrent iteration and writes in Concurrent::Hash
  • about 2 years Evaluate change log generator
  • about 2 years Remove all global state not just configuration
  • about 2 years Concurrent::Hash does not lock on method #each
  • about 2 years Java-based Semaphore does not allow new with 0 passes
  • over 2 years Create a twitter account to share news?
  • over 2 years Setup tests to ensure that we do not produce any warnings
  • over 2 years Rails5, auto-loading, future, circular dependency
  • over 2 years Assign old closed issues/PRs to appropriate milestone when it's missing
  • over 2 years Documentation enhance: Is it possible to upgrade a reentrant rw-lock from read to write?
  • over 2 years Strange interaction between local variables and Concurrent::Array; warn about += usages
  • over 2 years Move documentation of gh-pages to docs
  • over 2 years Make concurrent-ruby work with JRuby+Truffle again
  • over 2 years Thread Safe Set implementation
  • over 2 years Array#slice! broken on Rubinius
  • over 2 years FileLock
  • over 2 years Wishlist: Unique/Serial Task + threading executor
  • over 2 years Debugging a weird Concurrent::Delay
  • over 2 years Concurrent::Map #inspect test error
  • over 2 years 2.0 Async Operations API
  • over 2 years 2.0 Promise API
  • over 2 years 2.0 Some Specific Technical Changes
  • over 2 years 2.0 Guiding Principles
  • over 2 years AtomicBoolean: there's no compare_and_set API
  • over 2 years ConcurrencyError: No message available
  • almost 3 years TimerTask timeout_interval unused
  • almost 3 years Q: Delay odd API
  • almost 3 years Exception catching
  • almost 3 years CSP channels implementation
concurrent-ruby open pull requests (View All Pulls)
  • Fix Future + Executor example
  • Promise.race
  • add an udp server example
  • Move AtomicMarkableReference out of Edge
  • [WIP] Integrate CSP channels from Normandy
  • TimerTask uses timeout interval
  • Merging new futures
  • Concurrent::Atom#swap fixed: reraise the exceptions from block
  • Transaction.leave_transaction: speling in docs
  • Concurrent#flat: speling error in the example code
  • Added bundler cache for faster builds
  • Minimal changes to avoid Fixnum deprecation warnings
  • Use block form of IO.popen to prevent zombies
  • Add ISSUE_TEMPLATE
  • Avoid forking for processor_count if possible
  • Match Semaphore behaviors between Mutex and Java
  • Fix typo
  • Add Cyclic Barrier example.
  • Adding dynamic thread pool executor length setters
  • Add Event documentation example
  • Add Semaphore documentation example
  • #inspect should not output negative object IDs.
  • Fix promise example in comments
  • Futures 1.1 preparation
  • Travis: jruby-9.1.10.0, jruby-1.7.27
  • Promise.zip execution changes
  • Fixes a couple of typos in channel documentation
  • Fix misspellings
  • Docs edits to Promise docs
  • Avoid RSpec warnings about unused variables
  • Avoid RSpec warnings about raise_error
  • Disable Channel tests in CI
  • Avoid RSpec monkey patching, persist spec results locally, use RSpec v3.7.0
  • add missing require
  • bumping ruby version on travis yaml file
  • Travis: jruby-9.1.15.0 - and disable Actor-related tests on JRuby
  • thread safe set implementation
  • Add specs for Promise#zip/Promise.zip ordering
  • Fix missing monkeypatch of #new on TruffleRuby
  • Add 'truffleruby' to engine test per docs
  • Do not use global pool in actor tests
concurrent-ruby questions on Stackoverflow (View All Questions)
  • Advantages of non-concurrent Ruby Threads in Ruby 1.9?
  • How ought I limit Thread creation using Concurrent-Ruby?
concurrent-ruby list of languages used
concurrent-ruby latest release notes
v1.0.5 v1.0.5

concurrent-ruby:

  • Documentation for Event and Semaphore
  • Use Unsafe#fullFence and #loadFence directly since the shortcuts were removed in JRuby
  • Do not depend on org.jruby.util.unsafe.UnsafeHolder

concurrent-ruby-edge:

  • (#620) Actors on Pool raise an error
  • (#624) Delayed promises did not interact correctly with flatting
    • Fix arguments yielded by callback methods
  • Overridable default executor in promises factory methods
  • Asking actor to terminate will always resolve to true
v1.0.4 v1.0.4

Patch release.

concurrent-ruby:

  • Nothing

concurrent-ruby-edge:

  • New promises' API renamed, lots of improvements, edge bumped to 0.3.0
    • Incompatible with previous 0.2.3 version
    • see https://github.com/ruby-concurrency/concurrent-ruby/pull/522
v1.0.3 v1.0.3

Patch release

  • Trigger execution of flattened delayed futures
  • Avoid forking for processor_count if possible
  • Semaphore Mutex and JRuby parity
  • Adds Map#each as alias to Map#each_pair
  • Fix uninitialized instance variables
  • Make Fixnum, Bignum merger ready
  • Allows Promise#then to receive an executor
  • TimerSet now survives a fork
  • Reject promise on any exception
  • Allow ThreadLocalVar to be initialized with a block
  • Support Alpha with Concurrent::processor_count
  • Fixes format-security error when compiling ruby_193_compatible.h
  • Concurrent::Atom#swap fixed: reraise the exceptions from block
More projects by ruby-concurrency View all
Other projects in Ruby