Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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

Merge pull request #302 from pitr-ch/master

Make coverage opt in rather then opt out
latest commit ff3b8cfd54
@pitr-ch pitr-ch authored
Failed to load latest commit information.
build-tests Fixed build tests on Windows.
doc Async now hides :new and provides safe :create factory.
examples Implemented ImmutableStruct, MutableStruct, and Settable Struct.
ext CAtomicReference#get_and_set compares read value on update.
lib Async now hides :new and provides safe :create factory.
spec Merge pull request #302 from pitr-ch/master
tasks Added ruby critic rake task.
yard-template/default Add google analytics
.coveralls.yml Updated badges with new repo location.
.gitignore Add Concurrent.executor as an easy access point to global executors
.rspec ScheduledTask and TimerSet::Task now support deref and executor options.
.travis.yml CI: create CI Rake task
.yardopts Improvements to TimerSet#cancel.
CHANGELOG.md Removed LazyReference now that Delay is better, stronger, faster.
Gemfile Make coverage opt in rather then opt out
LICENSE.txt Improving documentation
README.md Implemented ImmutableStruct, MutableStruct, and Settable Struct.
Rakefile Do not run buggy Exchanger specs on Travis.
concurrent-ruby-edge.gemspec Simplify moving features between gems
concurrent-ruby-ext.gemspec Cleanup the load order in synchronized object
concurrent-ruby.gemspec Added WeakKeyMap to ThreadLocalRubyStorage.

README.md

Concurrent Ruby

Gem Version Build Status Coverage 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, 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.

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

We also have a mailing list.

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.

High-level, general-purpose asynchronous concurrency abstractions

  • Async: A mixin module that provides simple asynchronous behavior to any standard class/object or object.
  • 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.

Java-inspired ThreadPools and other executors

  • See ThreadPool overview, which also contains a list of other Executors available.

  • Thread-safe 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 synchronization classes and algorithms

Thread-safe variables

Edge features

They are available in the concurrent-ruby-edge companion gem, install 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.
  • Agent: A single atomic value that represents an identity.
  • Channel: Communicating Sequential Processes (CSP).
  • Exchanger
  • LazyRegister

Usage

All abstractions within this gem can be loaded simply by requiring it:

require 'concurrent'

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
require 'concurrent/utilities'      # utility methods such as processor count and timers

# individual abstractions

require 'concurrent/agent'          # Concurrent::Agent
require 'concurrent/async'          # Concurrent::Async
require 'concurrent/atomic'         # Concurrent::Atomic (formerly the `atomic` gem)
require 'concurrent/dataflow'       # Concurrent::dataflow
require 'concurrent/delay'          # Concurrent::Delay
require 'concurrent/exchanger'      # Concurrent::Exchanger
require 'concurrent/future'         # Concurrent::Future
require 'concurrent/ivar'           # Concurrent::IVar
require 'concurrent/lazy_register'  # Concurrent::LazyRegister
require 'concurrent/mvar'           # Concurrent::MVar
require 'concurrent/promise'        # Concurrent::Promise
require 'concurrent/scheduled_task' # Concurrent::ScheduledTask
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/channel '       # Concurrent::Channel and supporting code

Installation

gem install concurrent-ruby

or add the following line to Gemfile:

gem 'concurrent-ruby'

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.

Building

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              # Build core and extension gems
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

*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

Maintainers

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

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.

Something went wrong with that request. Please try again.