1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>
File: README
— Concurrent
</title>
<link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
<script type="text/javascript" charset="utf-8">
hasFrames = window.top.frames.main ? true : false;
relpath = '';
framesUrl = "frames.html#!file.README.html";
</script>
<script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
<script type="text/javascript" charset="utf-8" src="js/app.js"></script>
</head>
<body>
<div id="header">
<div id="menu">
<a href="_index.html">Index</a> »
<span class="title">File: README</span>
<div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
</div>
<div id="search">
<a class="full_list_link" id="class_list_link"
href="class_list.html">
Class List
</a>
<a class="full_list_link" id="method_list_link"
href="method_list.html">
Method List
</a>
<a class="full_list_link" id="file_list_link"
href="file_list.html">
File List
</a>
</div>
<div class="clear"></div>
</div>
<iframe id="search_frame"></iframe>
<div id="content"><div id='filecontents'><h1>Concurrent Ruby</h1>
<p><a href="http://badge.fury.io/rb/concurrent-ruby"><img src="https://badge.fury.io/rb/concurrent-ruby.svg" alt="Gem Version"></a>
<a href="https://travis-ci.org/ruby-concurrency/concurrent-ruby"><img src="https://travis-ci.org/ruby-concurrency/concurrent-ruby.svg?branch=master" alt="Build Status"></a>
<a href="https://ci.appveyor.com/project/rubyconcurrency/concurrent-ruby"><img src="https://ci.appveyor.com/api/projects/status/iq8aboyuu3etad4w?svg=true" alt="Build status"></a>
<a href="https://codeclimate.com/github/ruby-concurrency/concurrent-ruby"><img src="https://codeclimate.com/github/ruby-concurrency/concurrent-ruby.svg" alt="Code Climate"></a>
<a href="http://inch-ci.org/github/ruby-concurrency/concurrent-ruby"><img src="http://inch-ci.org/github/ruby-concurrency/concurrent-ruby.svg" alt="Inline docs"></a>
<a href="https://gemnasium.com/ruby-concurrency/concurrent-ruby"><img src="https://gemnasium.com/ruby-concurrency/concurrent-ruby.svg" alt="Dependency Status"></a>
<a href="http://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License"></a>
<a href="https://gitter.im/ruby-concurrency/concurrent-ruby"><img src="https://img.shields.io/badge/IRC%20(gitter)-devs%20%26%20users-brightgreen.svg" alt="Gitter chat"></a></p>
<p>Modern concurrency tools for Ruby. Inspired by
<a href="http://www.erlang.org/doc/reference_manual/processes.html">Erlang</a>,
<a href="http://clojure.org/concurrent_programming">Clojure</a>,
<a href="http://akka.io/">Scala</a>,
<a href="http://www.haskell.org/haskellwiki/Applications_and_libraries/Concurrency_and_parallelism#Concurrent_Haskell">Haskell</a>,
<a href="http://blogs.msdn.com/b/dsyme/archive/2010/02/15/async-and-parallel-design-patterns-in-f-part-3-agents.aspx">F#</a>,
<a href="http://msdn.microsoft.com/en-us/library/vstudio/hh191443.aspx">C#</a>,
<a href="http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/package-summary.html">Java</a>,
and classic concurrency patterns.</p>
<p><img src="https://raw.githubusercontent.com/ruby-concurrency/concurrent-ruby/master/doc/logo/concurrent-ruby-logo-300x300.png" align="right" style="margin-left: 20px;" /></p>
<p>The design goals of this gem are:</p>
<ul>
<li>Be an 'unopinionated' toolbox that provides useful utilities without debating which is better or why</li>
<li>Remain free of external gem dependencies</li>
<li>Stay true to the spirit of the languages providing inspiration</li>
<li>But implement in a way that makes sense for Ruby</li>
<li>Keep the semantics as idiomatic Ruby as possible</li>
<li>Support features that make sense in Ruby</li>
<li>Exclude features that don't make sense in Ruby</li>
<li>Be small, lean, and loosely coupled</li>
</ul>
<h3>Supported Ruby versions</h3>
<p>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.</p>
<h2>Thread Safety</h2>
<p><em>Concurrent Ruby makes the strongest thread safety guarantees of any Ruby concurrency library. We are the only library with a published <a href="https://github.com/ruby-concurrency/concurrent-ruby/blob/master/doc/synchronization.md">memory model</a> which provides consistent behavior and guarantees on all three of the main Ruby interpreters (MRI/CRuby, JRuby, and Rubinius).</em></p>
<p>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.</p>
<p>It is critical to remember, however, that Ruby is a language of mutable references. <em>No</em> 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 <a href="https://blog.golang.org/share-memory-by-communicating">"Do not communicate by sharing memory; instead, share memory by communicating"</a>. Concurrent Ruby is also the only Ruby library which provides a full suite of thread safe and immutable variable types and data structures.</p>
<h2>Features & Documentation</h2>
<p>The primary site for documentation is the automatically generated <a href="http://ruby-concurrency.github.io/concurrent-ruby/index.html">API documentation</a></p>
<p>We also have a <a href="http://groups.google.com/group/concurrent-ruby">mailing list</a> and <a href="https://gitter.im/ruby-concurrency/concurrent-ruby">IRC (gitter)</a>.</p>
<h4>General-purpose Concurrency Abstractions</h4>
<ul>
<li><span class='object_link'><a href="Concurrent/Async.html" title="Concurrent::Async (module)">Async</a></span>.</li>
<li><span class='object_link'><a href="Concurrent/Future.html" title="Concurrent::Future (class)">Future</a></span>: An asynchronous operation that produces a value.
<ul>
<li><a href="http://ruby-concurrency.github.io/concurrent-ruby/Concurrent.html#dataflow-class_method">.dataflow</a>: Built on Futures, Dataflow allows you to create a task that will be scheduled when all of its data dependencies are available.</li>
</ul></li>
<li><span class='object_link'><a href="Concurrent/Promise.html" title="Concurrent::Promise (class)">Promise</a></span>: Similar to Futures, with more features.</li>
<li><span class='object_link'><a href="Concurrent/ScheduledTask.html" title="Concurrent::ScheduledTask (class)">ScheduledTask</a></span>: Like a Future scheduled for a specific future time.</li>
<li><span class='object_link'><a href="Concurrent/TimerTask.html" title="Concurrent::TimerTask (class)">TimerTask</a></span>: A Thread that periodically wakes up to perform work at regular intervals.</li>
</ul>
<h4>Thread-safe Value Objects, Structures, and Collections</h4>
<p>Collection classes that were originally part of the (deprecated) <code>thread_safe</code> gem:</p>
<ul>
<li><span class='object_link'><a href="Concurrent/Array.html" title="Concurrent::Array (class)">Array</a></span>.</li>
<li><span class='object_link'><a href="Concurrent/Hash.html" title="Concurrent::Hash (class)">Hash</a></span>.</li>
<li><span class='object_link'><a href="Concurrent/Map.html" title="Concurrent::Map (class)">Map</a></span> A hash-like object that should have much better performance characteristics, especially under high concurrency, than <code>Concurrent::Hash</code>.</li>
<li><span class='object_link'><a href="Concurrent/Tuple.html" title="Concurrent::Tuple (class)">Tuple</a></span> getters/setters.</li>
</ul>
<p>Value objects inspired by other languages:</p>
<ul>
<li><span class='object_link'><a href="Concurrent/Maybe.html" title="Concurrent::Maybe (class)">Maybe</a></span> A thread-safe, immutable object representing an optional value, based on
<a href="https://hackage.haskell.org/package/base-4.2.0.1/docs/Data-Maybe.html">Haskell Data.Maybe</a>.</li>
<li><span class='object_link'><a href="Concurrent/Delay.html" title="Concurrent::Delay (class)">Delay</a></span>.</li>
</ul>
<p>Structure classes derived from Ruby's <a href="http://ruby-doc.org/core-2.2.0/Struct.html">Struct</a>:</p>
<ul>
<li><span class='object_link'><a href="Concurrent/ImmutableStruct.html" title="Concurrent::ImmutableStruct (module)">ImmutableStruct</a></span> Immutable struct where values are set at construction and cannot be changed later.</li>
<li><span class='object_link'><a href="Concurrent/MutableStruct.html" title="Concurrent::MutableStruct (module)">MutableStruct</a></span> Synchronized, mutable struct where values can be safely changed at any time.</li>
<li><span class='object_link'><a href="Concurrent/SettableStruct.html" title="Concurrent::SettableStruct (module)">SettableStruct</a></span> Synchronized, write-once struct where values can be set at most once, either at construction or any time thereafter.</li>
</ul>
<p>Thread-safe variables:</p>
<ul>
<li><span class='object_link'><a href="Concurrent/Agent.html" title="Concurrent::Agent (class)">Agent</a></span>.</li>
<li><span class='object_link'><a href="Concurrent/Atom.html" title="Concurrent::Atom (class)">Atom</a></span>.</li>
<li><span class='object_link'><a href="Concurrent/AtomicBoolean.html" title="Concurrent::AtomicBoolean (class)">AtomicBoolean</a></span> A boolean value that can be updated atomically.</li>
<li><span class='object_link'><a href="Concurrent/AtomicFixnum.html" title="Concurrent::AtomicFixnum (class)">AtomicFixnum</a></span> A numeric value that can be updated atomically.</li>
<li><span class='object_link'><a href="Concurrent/AtomicReference.html" title="Concurrent::AtomicReference (class)">AtomicReference</a></span> An object reference that may be updated atomically.</li>
<li><span class='object_link'><a href="Concurrent/Exchanger.html" title="Concurrent::Exchanger (class)">Exchanger</a></span>.</li>
<li><span class='object_link'><a href="Concurrent/MVar.html" title="Concurrent::MVar (class)">MVar</a></span>.</li>
<li><span class='object_link'><a href="Concurrent/ThreadLocalVar.html" title="Concurrent::ThreadLocalVar (class)">ThreadLocalVar</a></span> A variable where the value is different for each thread.</li>
<li><span class='object_link'><a href="Concurrent/TVar.html" title="Concurrent::TVar (class)">TVar</a></span>.</li>
</ul>
<h4>Java-inspired ThreadPools and Other Executors</h4>
<ul>
<li>See the <a href="file.thread_pools.html" title="thread pool">thread pool</a> overview, which also contains a list of other Executors available.</li>
</ul>
<h4>Thread Synchronization Classes and Algorithms</h4>
<ul>
<li><span class='object_link'><a href="Concurrent/CountDownLatch.html" title="Concurrent::CountDownLatch (class)">CountDownLatch</a></span> A synchronization object that allows one thread to wait on multiple other threads.</li>
<li><span class='object_link'><a href="Concurrent/CyclicBarrier.html" title="Concurrent::CyclicBarrier (class)">CyclicBarrier</a></span> A synchronization aid that allows a set of threads to all wait for each other to reach a common barrier point.</li>
<li><span class='object_link'><a href="Concurrent/Event.html" title="Concurrent::Event (class)">Event</a></span> Old school kernel-style event.</li>
<li><span class='object_link'><a href="Concurrent/IVar.html" title="Concurrent::IVar (class)">IVar</a></span> Similar to a "future" but can be manually assigned once, after which it becomes immutable.</li>
<li><span class='object_link'><a href="Concurrent/ReadWriteLock.html" title="Concurrent::ReadWriteLock (class)">ReadWriteLock</a></span> A lock that supports multiple readers but only one writer.</li>
<li><span class='object_link'><a href="Concurrent/ReentrantReadWriteLock.html" title="Concurrent::ReentrantReadWriteLock (class)">ReentrantReadWriteLock</a></span> A read/write lock with reentrant and upgrade features.</li>
<li><span class='object_link'><a href="Concurrent/Semaphore.html" title="Concurrent::Semaphore (class)">Semaphore</a></span> A counting-based locking mechanism that uses permits.</li>
</ul>
<h3>Edge Features</h3>
<p>These are available in the <code>concurrent-ruby-edge</code> companion gem.</p>
<p>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 <code>concurrent-ruby-edge</code> are expected to move to <code>concurrent-ruby</code> when final.</p>
<ul>
<li><span class='object_link'><a href="Concurrent/Promises.html" title="Concurrent::Promises (module)">Promises</a></span>:
Unified implementation of futures and promises which combines features of previous <code>Future</code>,
<code>Promise</code>, <code>IVar</code>, <code>Event</code>, <code>dataflow</code>, <code>Delay</code>, and <code>TimerTask</code> into a single framework. It extensively uses the
new synchronization layer to make all the features <strong>non-blocking</strong> and <strong>lock-free</strong>, with the exception of obviously blocking
operations like <code>#wait</code>, <code>#value</code>. It also offers better performance.</li>
<li><span class='object_link'><a href="Concurrent/Actor.html" title="Concurrent::Actor (module)">Actor</a></span>:
Implements the Actor Model, where concurrent actors exchange messages.</li>
<li><span class='object_link'><a href="Concurrent/Channel.html" title="Concurrent::Channel (class)">Channel</a></span>:
Communicating Sequential Processes (<a href="https://en.wikipedia.org/wiki/Communicating_sequential_processes">CSP</a>).
Functionally equivalent to Go <a href="https://tour.golang.org/concurrency/2">channels</a> with additional
inspiration from Clojure <a href="https://clojure.github.io/core.async/">core.async</a>.</li>
<li><span class='object_link'><a href="Concurrent/LazyRegister.html" title="Concurrent::LazyRegister (class)">LazyRegister</a></span></li>
<li><span class='object_link'><a href="Concurrent/Edge/AtomicMarkableReference.html" title="Concurrent::Edge::AtomicMarkableReference (class)">AtomicMarkableReference</a></span></li>
<li><span class='object_link'><a href="Concurrent/Edge/LockFreeLinkedSet.html" title="Concurrent::Edge::LockFreeLinkedSet (class)">LockFreeLinkedSet</a></span></li>
<li><span class='object_link'>LockFreeStack</span></li>
</ul>
<h4>Statuses:</h4>
<p><em>Why are these not in core?</em></p>
<ul>
<li><strong>Promises</strong> - They are being finalized to be able to be moved to core. They'll deprecate old
implementation.</li>
<li><strong>Actor</strong> - Partial documentation and tests; depends on new future/promise framework; stability is good.</li>
<li><strong>Channel</strong> - Brand new implementation; partial documentation and tests; stability is good.</li>
<li><strong>LazyRegister</strong> - Missing documentation and tests.</li>
<li><strong>AtomicMarkableReference, LockFreeLinkedSet, LockFreeStack</strong> - Need real world battle testing.</li>
</ul>
<h2>Usage</h2>
<p>Everything within this gem can be loaded simply by requiring it:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>concurrent</span><span class='tstring_end'>'</span></span>
</code></pre>
<p>To use the tools in the Edge gem it must be required separately:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>concurrent-edge</span><span class='tstring_end'>'</span></span>
</code></pre>
<p>If the library does not behave as expected, <code>Concurrent.use_stdlib_logger(Logger::DEBUG)</code> could help to reveal the problem.</p>
<h2>Installation</h2>
<pre class="code shell"><code class="shell">gem install concurrent-ruby
</code></pre>
<p>or add the following line to Gemfile:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>concurrent-ruby</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='label'>require:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>concurrent</span><span class='tstring_end'>'</span></span>
</code></pre>
<p>and run <code>bundle install</code> from your shell.</p>
<h3>Edge Gem Installation</h3>
<p>The Edge gem must be installed separately from the core gem:</p>
<pre class="code shell"><code class="shell">gem install concurrent-ruby-edge
</code></pre>
<p>or add the following line to Gemfile:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>concurrent-ruby-edge</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='label'>require:</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>concurrent-edge</span><span class='tstring_end'>'</span></span>
</code></pre>
<p>and run <code>bundle install</code> from your shell.</p>
<h3>C Extensions for MRI</h3>
<p>Potential performance improvements may be achieved under MRI by installing optional C extensions.
To minimize installation errors the C extensions are available in the <code>concurrent-ruby-ext</code> extension
gem. <code>concurrent-ruby</code> and <code>concurrent-ruby-ext</code> are always released together with same version.
Simply install the extension gem too:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='id identifier rubyid_install'>install</span> <span class='id identifier rubyid_concurrent'>concurrent</span><span class='op'>-</span><span class='id identifier rubyid_ruby'>ruby</span><span class='op'>-</span><span class='id identifier rubyid_ext'>ext</span>
</code></pre>
<p>or add the following line to Gemfile:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>concurrent-ruby-ext</span><span class='tstring_end'>'</span></span>
</code></pre>
<p>and run <code>bundle install</code> from your shell.</p>
<p>In code it is only necessary to</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>concurrent</span><span class='tstring_end'>'</span></span>
</code></pre>
<p>The <code>concurrent-ruby</code> gem will automatically detect the presence of the <code>concurrent-ruby-ext</code> gem
and load the appropriate C extensions.</p>
<h4>Note For gem developers</h4>
<p>No gems should depend on <code>concurrent-ruby-ext</code>. Doing so will force C extensions on your users.
The best practice is to depend on <code>concurrent-ruby</code> and let users to decide if they want C extensions.</p>
<h2>Maintainers</h2>
<ul>
<li><a href="https://github.com/pitr-ch">Petr Chalupa</a> (lead maintainer)</li>
<li><a href="https://github.com/jdantonio">Jerry D'Antonio</a> (creator)</li>
<li><a href="https://github.com/mighe">Michele Della Torre</a></li>
<li><a href="https://github.com/chrisseaton">Chris Seaton</a></li>
<li><a href="https://github.com/obrok">Paweł Obrok</a></li>
<li><a href="https://github.com/lucasallan">Lucas Allan</a></li>
</ul>
<h3>Special Thanks</h3>
<ul>
<li><a href="https://github.com/bdurand">Brian Durand</a> for the <code>ref</code> gem</li>
<li><a href="https://github.com/headius">Charles Oliver Nutter</a> for the <code>atomic</code> and <code>thread_safe</code> gems</li>
<li><a href="https://github.com/thedarkone">thedarkone</a> for the <code>thread_safe</code> gem</li>
</ul>
<h2>License and Copyright</h2>
<p><em>Concurrent Ruby</em> is free software released under the <a href="http://www.opensource.org/licenses/MIT">MIT License</a>.</p>
<p>The <em>Concurrent Ruby</em> <a href="https://github.com/ruby-concurrency/concurrent-ruby/wiki/Logo">logo</a>
was designed by <a href="https://twitter.com/zombyboy">David Jones</a>.
It is Copyright © 2014 <a href="https://twitter.com/jerrydantonio">Jerry D'Antonio</a>. All Rights Reserved.</p>
</div></div>
<div id="footer">
Generated on Wed Aug 15 13:38:39 2018 by
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
0.8.7.6 (ruby-2.4.3).
</div>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-57940973-1', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>
|