Repository files navigation

Modern concurrency tools for Ruby. Inspired byErlang,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 betteror 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

This gem depends oncontributions and weappreciate your help. Would you like to contribute? Great! Have a look atissues withlooking-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 tosubscribe to concurrent-ruby on CodeTriage.

Concurrent Ruby makes one of the strongest thread safety guarantees of any Ruby concurrencylibrary, 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 documentedwith each abstraction.

It is critical to remember, however, that Ruby is a language of mutable references.Noconcurrency library for Ruby can ever prevent the user from making thread safety mistakes (such assharing a mutable object between threads and modifying it on both threads) or from creatingdeadlocks through incorrect use of locks. All the library can do is provide safe abstractions whichencourage safe practices. Concurrent Ruby provides more safe concurrency abstractions than anyother 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 andimmutable variable types and data structures.

We've also initiated discussion to document thememory model of Ruby whichwould provide consistent behaviour and guarantees on all three main Ruby interpreters(MRI/CRuby, JRuby, TruffleRuby).

The primary site for documentation is the automatically generatedAPI documentation which is up todate with latest release. This readme matches the master so may contain new stuff not yetreleased.

We also have aIRC (gitter).

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

• Async:A mixin module that provides simple asynchronous behavior to a class. Loosely based on Erlang'sgen_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:Unified implementation of futures and promises which combines features of previousFuture,Promise,IVar,Event,dataflow,Delay, and (partially)TimerTask into a singleframework. It extensively uses the new synchronization layer to make all the featuresnon-blocking andlock-free, with the exception of obviously blocking operations like#wait,#value. It also offers better performance.

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

• Array A thread-safesubclass of Ruby's standardArray.
• Hash A thread-safesubclass of Ruby's standardHash.
• Set A thread-safesubclass of Ruby's standardSet.
• Map A hash-like objectthat should have much better performance characteristics, especially under high concurrency,thanConcurrent::Hash.
• Tuple A fixed sizearray with volatile (synchronized, thread safe) getters/setters.

Value objects inspired by other languages:

• Maybe A thread-safe,immutable object representing an optional value, based onHaskell Data.Maybe.

Structure classes derived from Ruby'sStruct:

• 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 constructionor any time thereafter.

Thread-safe variables:

• Agent: A way tomanage shared, mutable,asynchronous, independent state. Based on Clojure'sAgent.
• Atom: A way to manageshared, mutable,synchronous, independent state. Based on Clojure'sAtom.
• AtomicBooleanA boolean value that can be updated atomically.
• AtomicFixnumA numeric value that can be updated atomically.
• AtomicReferenceAn object reference that may be updated atomically.
• ExchangerA synchronization point at which threads can pair and swap elements within pairs. Based onJava'sExchanger.
• MVar A synchronizedsingle element container. Based on Haskell'sMVar andScala'sMVar.
• ThreadLocalVarA variable where the value is different for each thread.
• TVar A transactionalvariable implementing software transactional memory (STM). Based on Clojure'sRef.

• See thethread pooloverview, which also contains a list of other Executors available.

• CountDownLatchA synchronization object that allows one thread to wait on multiple other threads.
• CyclicBarrierA synchronization aid that allows a set of threads to all wait for each other to reach a common barrier point.
• Event Old schoolkernel-style event.
• ReadWriteLockA lock that supports multiple readers but only one writer.
• ReentrantReadWriteLockA read/write lock with reentrant and upgrade features.
• SemaphoreA counting-based locking mechanism that uses permits.
• AtomicMarkableReference

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

• Future:An asynchronous operation that produces a value. Replaced byPromises.
  • .dataflow:Built on Futures, Dataflow allows you to create a task that will be scheduled when all ofits data dependencies are available. Replaced byPromises.
• Promise: Similarto Futures, with more features. Replaced byPromises.
• Delay Lazy evaluationof a block yielding an immutable result. Based on Clojure'sdelay. Replaced byPromises.
• IVar Similar to a"future" but can be manually assigned once, after which it becomes immutable. Replaced byPromises.

These are available in theconcurrent-ruby-edge companion gem.

These features are under active development and may change frequently. They are expected not tokeep backward compatibility (they may also lack tests and documentation). Semantic versions willbe obeyed though. Features developed inconcurrent-ruby-edge are expected to move toconcurrent-ruby when final.

• Actor: Implementsthe 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 Gochannels with additionalinspiration from Clojurecore.async.Status: Partial documentation and tests.

• LazyRegister

• LockFreeLinkedSetStatus: will be moved to core soon.

• LockFreeStackStatus: missing documentation and tests.

• Promises::ChannelA first in first out channel that accepts messages with push family of methods and returnsmessages 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.

• CancellationThe Cancellation abstraction provides cooperative cancellation.

  The standard methodsThread#raise ofThread#kill available in Rubyare 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 cancellationand if ok block again with the timeout

• ThrottleA tool managing concurrency level of tasks.

• ErlangActorActor implementation which precisely matches Erlang actor behaviour.Requires at least Ruby 2.1 otherwise it's not loaded.

• WrappingExecutorA delegating executor which modifies each task before the task is given tothe target executor it delegates to.

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

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

require'concurrent'

You can also require a specific abstractionpart 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) couldhelp to reveal the problem.

gem install concurrent-ruby

or add the following line to Gemfile:

gem'concurrent-ruby',require:'concurrent'

and runbundle install from your shell.

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 runbundle install from your shell.

Potential performance improvements may be achieved under MRI by installing optional C extensions.To minimise installation errors the C extensions are available in theconcurrent-ruby-extextension gem.concurrent-ruby andconcurrent-ruby-ext are always released together with sameversion. Simply install the extension gem too:

geminstallconcurrent-ruby-ext

or add the following line to Gemfile:

gem'concurrent-ruby-ext'

and runbundle install from your shell.

In code it is only necessary to

require'concurrent'

Theconcurrent-ruby gem will automatically detect the presence of theconcurrent-ruby-ext gemand load the appropriate C extensions.

No gems should depend onconcurrent-ruby-ext. Doing so will force C extensions on your users. Thebest practice is to depend onconcurrent-ruby and let users to decide if they want C extensions.

• Recent CRuby
• JRuby,rbenv install jruby-9.2.17.0
• Set env variableCONCURRENT_JRUBY_HOME to point to it, e.g./usr/local/opt/rbenv/versions/jruby-9.2.17.0
• Install Docker or Podman, required for Windows builds
• Ifbundle config get path is set, usebundle config set --local path.system true otherwise thegem name, path: '.' gems won't be found (Bundler limitation).

• Updateversion.rb
• Update the CHANGELOG
• Add the new version todocs-source/signpost.md. Needs to be done only if there are visible changes in the documentation.
• Commit (and push) the changes.
• Usebundle 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.

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

• Jerry D'Antonio for creating the gem
• Brian Durand for theref gem
• Charles Oliver Nutter for theatomic andthread_safe gems
• thedarkone for thethread_safe gem

to the past maintainers

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

and toRuby Association for sponsoring a project"Enhancing Ruby’s concurrency tooling" in 2018.

Concurrent Ruby is free software released under theMIT License.

TheConcurrent Rubylogo wasdesigned byDavid Jones. It is Copyright © 2014Jerry D'Antonio. All Rights Reserved.