logstash-filter-cache-redis 0.1.0 → 0.2.0

data/vendor/bundle/jruby/1.9/gems/concurrent-ruby-1.0.5-java/README.md

@@ -0,0 +1,247 @@
+# Concurrent Ruby
+
+[![Gem Version](https://badge.fury.io/rb/concurrent-ruby.svg)](http://badge.fury.io/rb/concurrent-ruby)
+[![Build Status](https://travis-ci.org/ruby-concurrency/concurrent-ruby.svg?branch=master)](https://travis-ci.org/ruby-concurrency/concurrent-ruby)
+[![Build status](https://ci.appveyor.com/api/projects/status/iq8aboyuu3etad4w?svg=true)](https://ci.appveyor.com/project/rubyconcurrency/concurrent-ruby)
+[![Code Climate](https://codeclimate.com/github/ruby-concurrency/concurrent-ruby.svg)](https://codeclimate.com/github/ruby-concurrency/concurrent-ruby)
+[![Inline docs](http://inch-ci.org/github/ruby-concurrency/concurrent-ruby.svg)](http://inch-ci.org/github/ruby-concurrency/concurrent-ruby)
+[![Dependency Status](https://gemnasium.com/ruby-concurrency/concurrent-ruby.svg)](https://gemnasium.com/ruby-concurrency/concurrent-ruby)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](http://opensource.org/licenses/MIT)
+[![Gitter chat](https://img.shields.io/badge/IRC%20(gitter)-devs%20%26%20users-brightgreen.svg)](https://gitter.im/ruby-concurrency/concurrent-ruby)
+
+Modern concurrency tools for Ruby. Inspired by
+[Erlang](http://www.erlang.org/doc/reference_manual/processes.html),
+[Clojure](http://clojure.org/concurrent_programming),
+[Scala](http://akka.io/),
+[Haskell](http://www.haskell.org/haskellwiki/Applications_and_libraries/Concurrency_and_parallelism#Concurrent_Haskell),
+[F#](http://blogs.msdn.com/b/dsyme/archive/2010/02/15/async-and-parallel-design-patterns-in-f-part-3-agents.aspx),
+[C#](http://msdn.microsoft.com/en-us/library/vstudio/hh191443.aspx),
+[Java](http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/package-summary.html),
+and classic concurrency patterns.
+
+<img src="https://raw.githubusercontent.com/ruby-concurrency/concurrent-ruby/master/doc/logo/concurrent-ruby-logo-300x300.png" align="right" style="margin-left: 20px;" />
+
+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](https://github.com/ruby-concurrency/concurrent-ruby/blob/master/doc/synchronization.md) 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"](https://blog.golang.org/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](http://ruby-concurrency.github.io/concurrent-ruby/frames.html)
+
+We also have a [mailing list](http://groups.google.com/group/concurrent-ruby) and [IRC (gitter)](https://gitter.im/ruby-concurrency/concurrent-ruby).
+
+#### General-purpose Concurrency Abstractions
+
+* [Async](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Async.html): A mixin module that provides simple asynchronous behavior to a class. Loosely based on Erlang's [gen_server](http://www.erlang.org/doc/man/gen_server.html).
+* [Future](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Future.html): An asynchronous operation that produces a value.
+  * [Dataflow](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent.html#dataflow-class_method): Built on Futures, Dataflow allows you to create a task that will be scheduled when all of its data dependencies are available.
+* [Promise](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Promise.html): Similar to Futures, with more features.
+* [ScheduledTask](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ScheduledTask.html): Like a Future scheduled for a specific future time.
+* [TimerTask](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/TimerTask.html): 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](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Array.html) A thread-safe subclass of Ruby's standard [Array](http://ruby-doc.org/core-2.2.0/Array.html).
+* [Hash](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Hash.html) A thread-safe subclass of Ruby's standard [Hash](http://ruby-doc.org/core-2.2.0/Hash.html).
+* [Map](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Map.html) A hash-like object that should have much better performance characteristics, especially under high concurrency, than `Concurrent::Hash`.
+* [Tuple](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Tuple.html) A fixed size array with volatile (synchronized, thread safe) getters/setters.
+
+Value objects inspired by other languages:
+
+* [Maybe](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Maybe.html) A thread-safe, immutable object representing an optional value, based on
+  [Haskell Data.Maybe](https://hackage.haskell.org/package/base-4.2.0.1/docs/Data-Maybe.html).
+* [Delay](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Delay.html) Lazy evaluation of a block yielding an immutable result. Based on Clojure's [delay](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Delay.html).
+
+Structure classes derived from Ruby's [Struct](http://ruby-doc.org/core-2.2.0/Struct.html):
+
+* [ImmutableStruct](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ImmutableStruct.html) Immutable struct where values are set at construction and cannot be changed later.
+* [MutableStruct](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/MutableStruct.html) Synchronized, mutable struct where values can be safely changed at any time.
+* [SettableStruct](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/SettableStruct.html) Synchronized, write-once struct where values can be set at most once, either at construction or any time thereafter.
+
+Thread-safe variables:
+
+* [Agent](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Agent.html): A way to manage shared, mutable, *asynchronous*, independent state. Based on Clojure's [Agent](http://clojure.org/agents).
+* [Atom](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Atom.html): A way to manage shared, mutable, *synchronous*, independent state. Based on Clojure's [Atom](http://clojure.org/atoms).
+* [AtomicBoolean](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/AtomicBoolean.html) A boolean value that can be updated atomically.
+* [AtomicFixnum](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/AtomicFixnum.html) A numeric value that can be updated atomically.
+* [AtomicReference](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/MutexAtomic.html) An object reference that may be updated atomically.
+* [Exchanger](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Exchanger.html) A synchronization point at which threads can pair and swap elements within pairs. Based on Java's [Exchanger](http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Exchanger.html).
+* [MVar](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/MVar.html) A synchronized single element container. Based on Haskell's [MVar](https://hackage.haskell.org/package/base-4.8.1.0/docs/Control-Concurrent-MVar.html) and Scala's [MVar](http://docs.typelevel.org/api/scalaz/nightly/index.html#scalaz.concurrent.MVar$).
+* [ThreadLocalVar](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ThreadLocalVar.html) A variable where the value is different for each thread.
+* [TVar](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/TVar.html) A transactional variable implementing software transactional memory (STM). Based on Clojure's [Ref](http://clojure.org/refs).
+
+#### Java-inspired ThreadPools and Other Executors
+
+* See the [thread pool](http://ruby-concurrency.github.io/concurrent-ruby/file.thread_pools.html) overview, which also contains a list of other Executors available.
+
+#### Thread Synchronization Classes and Algorithms
+
+* [CountDownLatch](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/CountDownLatch.html) A synchronization object that allows one thread to wait on multiple other threads.
+* [CyclicBarrier](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/CyclicBarrier.html) A synchronization aid that allows a set of threads to all wait for each other to reach a common barrier point.
+* [Event](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Event.html) Old school kernel-style event.
+* [IVar](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/IVar.html) Similar to a "future" but can be manually assigned once, after which it becomes immutable.
+* [ReadWriteLock](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ReadWriteLock.html) A lock that supports multiple readers but only one writer.
+* [ReentrantReadWriteLock](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ReentrantReadWriteLock.html) A read/write lock with reentrant and upgrade features.
+* [Semaphore](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Semaphore.html) 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](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Promises.html):
+  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](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Actor.html):
+  Implements the Actor Model, where concurrent actors exchange messages.
+* [Channel](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/Channel.html):
+  Communicating Sequential Processes ([CSP](https://en.wikipedia.org/wiki/Communicating_sequential_processes)).
+  Functionally equivalent to Go [channels](https://tour.golang.org/concurrency/2) with additional
+  inspiration from Clojure [core.async](https://clojure.github.io/core.async/).
+* [LazyRegister](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/LazyRegister.html)
+* [AtomicMarkableReference](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/AtomicMarkableReference.html)
+* [LockFreeLinkedSet](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Edge/LockFreeLinkedSet.html)
+* [LockFreeStack](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/LockFreeStack.html)
+
+#### 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:
+
+```ruby
+require 'concurrent'
+```
+
+To use the tools in the Edge gem it must be required separately:
+
+```ruby
+require 'concurrent-edge'
+```
+
+If the library does not behave as expected, `Concurrent.use_stdlib_logger(Logger::DEBUG)` could help to reveal the problem.
+
+## Installation
+
+```shell
+gem install concurrent-ruby
+```
+
+or add the following line to Gemfile:
+
+```ruby
+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:
+
+```shell
+gem install concurrent-ruby-edge
+```
+
+or add the following line to Gemfile:
+
+```ruby
+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:
+
+```ruby
+gem install concurrent-ruby-ext
+```
+
+or add the following line to Gemfile:
+
+```ruby
+gem 'concurrent-ruby-ext'
+```
+
+and run `bundle install` from your shell.
+
+In code it is only necessary to
+
+```ruby
+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
+
+* [Petr Chalupa](https://github.com/pitr-ch) (lead maintainer)
+* [Jerry D'Antonio](https://github.com/jdantonio) (creator)
+* [Michele Della Torre](https://github.com/mighe)
+* [Chris Seaton](https://github.com/chrisseaton)
+* [Paweł Obrok](https://github.com/obrok)
+* [Lucas Allan](https://github.com/lucasallan)
+
+### Special Thanks
+
+* [Brian Durand](https://github.com/bdurand) for the `ref` gem
+* [Charles Oliver Nutter](https://github.com/headius) for the `atomic` and `thread_safe` gems
+* [thedarkone](https://github.com/thedarkone) for the `thread_safe` gem
+
+## License and Copyright
+
+*Concurrent Ruby* is free software released under the [MIT License](http://www.opensource.org/licenses/MIT).
+
+The *Concurrent Ruby* [logo](https://github.com/ruby-concurrency/concurrent-ruby/wiki/Logo)
+was designed by [David Jones](https://twitter.com/zombyboy).
+It is Copyright &copy; 2014 [Jerry D'Antonio](https://twitter.com/jerrydantonio). All Rights Reserved.

data/vendor/bundle/jruby/1.9/gems/concurrent-ruby-1.0.5-java/lib/concurrent.rb

@@ -0,0 +1,130 @@
+require 'concurrent/version'
+require 'concurrent/constants'
+require 'concurrent/errors'
+require 'concurrent/configuration'
+
+require 'concurrent/atomics'
+require 'concurrent/executors'
+require 'concurrent/synchronization'
+
+require 'concurrent/atomic/atomic_reference'
+require 'concurrent/agent'
+require 'concurrent/atom'
+require 'concurrent/array'
+require 'concurrent/hash'
+require 'concurrent/map'
+require 'concurrent/tuple'
+require 'concurrent/async'
+require 'concurrent/dataflow'
+require 'concurrent/delay'
+require 'concurrent/exchanger'
+require 'concurrent/future'
+require 'concurrent/immutable_struct'
+require 'concurrent/ivar'
+require 'concurrent/maybe'
+require 'concurrent/mutable_struct'
+require 'concurrent/mvar'
+require 'concurrent/promise'
+require 'concurrent/scheduled_task'
+require 'concurrent/settable_struct'
+require 'concurrent/timer_task'
+require 'concurrent/tvar'
+
+require 'concurrent/thread_safe/synchronized_delegator'
+require 'concurrent/thread_safe/util'
+
+require 'concurrent/options'
+
+# @!macro [new] internal_implementation_note
+#
+#   @note **Private Implementation:** This abstraction is a private, internal
+#     implementation detail. It should never be used directly.
+
+# @!macro [new] monotonic_clock_warning
+#
+#   @note Time calculations one all platforms and languages are sensitive to
+#     changes to the system clock. To alleviate the potential problems
+#     associated with changing the system clock while an application is running,
+#     most modern operating systems provide a monotonic clock that operates
+#     independently of the system clock. A monotonic clock cannot be used to
+#     determine human-friendly clock times. A monotonic clock is used exclusively
+#     for calculating time intervals. Not all Ruby platforms provide access to an
+#     operating system monotonic clock. On these platforms a pure-Ruby monotonic
+#     clock will be used as a fallback. An operating system monotonic clock is both
+#     faster and more reliable than the pure-Ruby implementation. The pure-Ruby
+#     implementation should be fast and reliable enough for most non-realtime
+#     operations. At this time the common Ruby platforms that provide access to an
+#     operating system monotonic clock are MRI 2.1 and above and JRuby (all versions).
+#
+#   @see http://linux.die.net/man/3/clock_gettime Linux clock_gettime(3)
+
+# @!macro [new] copy_options
+#
+#   ## Copy Options
+#
+#   Object references in Ruby are mutable. This can lead to serious
+#   problems when the {#value} of an object is a mutable reference. Which
+#   is always the case unless the value is a `Fixnum`, `Symbol`, or similar
+#   "primitive" data type. Each instance can be configured with a few
+#   options that can help protect the program from potentially dangerous
+#   operations. Each of these options can be optionally set when the object
+#   instance is created:
+#
+#   * `:dup_on_deref` When true the object will call the `#dup` method on
+#     the `value` object every time the `#value` method is called
+#     (default: false)
+#   * `:freeze_on_deref` When true the object will call the `#freeze`
+#     method on the `value` object every time the `#value` method is called
+#     (default: false)
+#   * `:copy_on_deref` When given a `Proc` object the `Proc` will be run
+#     every time   the `#value` method is called. The `Proc` will be given
+#     the current `value` as its only argument and the result returned by
+#     the block will be the return   value of the `#value` call. When `nil`
+#     this option will be ignored (default: nil)
+#
+#   When multiple deref options are set the order of operations is strictly defined.
+#   The order of deref operations is:
+#   * `:copy_on_deref`
+#   * `:dup_on_deref`
+#   * `:freeze_on_deref`
+#
+#   Because of this ordering there is no need to `#freeze` an object created by a
+#   provided `:copy_on_deref` block. Simply set `:freeze_on_deref` to `true`.
+#   Setting both `:dup_on_deref` to `true` and `:freeze_on_deref` to `true` is
+#   as close to the behavior of a "pure" functional language (like Erlang, Clojure,
+#   or Haskell) as we are likely to get in Ruby.
+
+# @!macro [attach] deref_options
+#
+#   @option opts [Boolean] :dup_on_deref (false) Call `#dup` before
+#     returning the data from {#value}
+#   @option opts [Boolean] :freeze_on_deref (false) Call `#freeze` before
+#     returning the data from {#value}
+#   @option opts [Proc] :copy_on_deref (nil) When calling the {#value}
+#     method, call the given proc passing the internal value as the sole
+#     argument then return the new value returned from the proc.
+
+# @!macro [attach] executor_and_deref_options
+#
+#   @param [Hash] opts the options used to define the behavior at update and deref
+#     and to specify the executor on which to perform actions
+#   @option opts [Executor] :executor when set use the given `Executor` instance.
+#     Three special values are also supported: `:task` returns the global task pool,
+#     `:operation` returns the global operation pool, and `:immediate` returns a new
+#     `ImmediateExecutor` object.
+#   @!macro deref_options
+
+# 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:
+#
+# * 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
+module Concurrent
+
+end

data/vendor/bundle/jruby/1.9/gems/concurrent-ruby-1.0.5-java/lib/concurrent/array.rb

@@ -0,0 +1,39 @@
+require 'concurrent/utility/engine'
+require 'concurrent/thread_safe/util'
+
+module Concurrent
+  if Concurrent.on_cruby?
+
+    # Because MRI never runs code in parallel, the existing
+    # non-thread-safe structures should usually work fine.
+
+    # @!macro [attach] concurrent_array
+    #
+    #   A thread-safe subclass of Array. This version locks against the object
+    #   itself for every method call, ensuring only one thread can be reading
+    #   or writing at a time. This includes iteration methods like `#each`.
+    #
+    #   @see http://ruby-doc.org/core-2.2.0/Array.html Ruby standard library `Array`
+    class Array < ::Array;
+    end
+
+  elsif Concurrent.on_jruby?
+    require 'jruby/synchronized'
+
+    # @!macro concurrent_array
+    class Array < ::Array
+      include JRuby::Synchronized
+    end
+
+  elsif Concurrent.on_rbx? || Concurrent.on_truffle?
+    require 'monitor'
+    require 'concurrent/thread_safe/util/array_hash_rbx'
+
+    # @!macro concurrent_array
+    class Array < ::Array
+    end
+
+    ThreadSafe::Util.make_synchronized_on_rbx Array
+  end
+end
+

data/vendor/bundle/jruby/1.9/gems/concurrent-ruby-1.0.5-java/lib/concurrent/async.rb

@@ -0,0 +1,445 @@
+require 'concurrent/configuration'
+require 'concurrent/ivar'
+require 'concurrent/synchronization/lockable_object'
+
+module Concurrent
+
+  # A mixin module that provides simple asynchronous behavior to a class,
+  # turning it into a simple actor. Loosely based on Erlang's
+  # [gen_server](http://www.erlang.org/doc/man/gen_server.html), but without
+  # supervision or linking.
+  #
+  # A more feature-rich {Concurrent::Actor} is also available when the
+  # capabilities of `Async` are too limited.
+  #
+  # ```cucumber
+  # Feature:
+  #   As a stateful, plain old Ruby class
+  #   I want safe, asynchronous behavior
+  #   So my long-running methods don't block the main thread
+  # ```
+  #
+  # The `Async` module is a way to mix simple yet powerful asynchronous
+  # capabilities into any plain old Ruby object or class, turning each object
+  # into a simple Actor. Method calls are processed on a background thread. The
+  # caller is free to perform other actions while processing occurs in the
+  # background.
+  #
+  # Method calls to the asynchronous object are made via two proxy methods:
+  # `async` (alias `cast`) and `await` (alias `call`). These proxy methods post
+  # the method call to the object's background thread and return a "future"
+  # which will eventually contain the result of the method call.
+  #
+  # This behavior is loosely patterned after Erlang's `gen_server` behavior.
+  # When an Erlang module implements the `gen_server` behavior it becomes
+  # inherently asynchronous. The `start` or `start_link` function spawns a
+  # process (similar to a thread but much more lightweight and efficient) and
+  # returns the ID of the process. Using the process ID, other processes can
+  # send messages to the `gen_server` via the `cast` and `call` methods. Unlike
+  # Erlang's `gen_server`, however, `Async` classes do not support linking or
+  # supervision trees.
+  #
+  # ## Basic Usage
+  #
+  # When this module is mixed into a class, objects of the class become inherently
+  # asynchronous. Each object gets its own background thread on which to post
+  # asynchronous method calls. Asynchronous method calls are executed in the
+  # background one at a time in the order they are received.
+  #
+  # To create an asynchronous class, simply mix in the `Concurrent::Async` module:
+  #
+  # ```
+  # class Hello
+  #   include Concurrent::Async
+  #
+  #   def hello(name)
+  #     "Hello, #{name}!"
+  #   end
+  # end
+  # ```
+  #
+  # When defining a constructor it is critical that the first line be a call to
+  # `super` with no arguments. The `super` method initializes the background
+  # thread and other asynchronous components.
+  #
+  # ```
+  # class BackgroundLogger
+  #   include Concurrent::Async
+  #
+  #   def initialize(level)
+  #     super()
+  #     @logger = Logger.new(STDOUT)
+  #     @logger.level = level
+  #   end
+  #
+  #   def info(msg)
+  #     @logger.info(msg)
+  #   end
+  # end
+  # ```
+  #
+  # Mixing this module into a class provides each object two proxy methods:
+  # `async` and `await`. These methods are thread safe with respect to the
+  # enclosing object. The former proxy allows methods to be called
+  # asynchronously by posting to the object's internal thread. The latter proxy
+  # allows a method to be called synchronously but does so safely with respect
+  # to any pending asynchronous method calls and ensures proper ordering. Both
+  # methods return a {Concurrent::IVar} which can be inspected for the result
+  # of the proxied method call. Calling a method with `async` will return a
+  # `:pending` `IVar` whereas `await` will return a `:complete` `IVar`.
+  #
+  # ```
+  # class Echo
+  #   include Concurrent::Async
+  #
+  #   def echo(msg)
+  #     print "#{msg}\n"
+  #   end
+  # end
+  #
+  # horn = Echo.new
+  # horn.echo('zero')      # synchronous, not thread-safe
+  #                        # returns the actual return value of the method
+  #
+  # horn.async.echo('one') # asynchronous, non-blocking, thread-safe
+  #                        # returns an IVar in the :pending state
+  #
+  # horn.await.echo('two') # synchronous, blocking, thread-safe
+  #                        # returns an IVar in the :complete state
+  # ```
+  #
+  # ## Let It Fail
+  #
+  # The `async` and `await` proxy methods have built-in error protection based
+  # on Erlang's famous "let it fail" philosophy. Instance methods should not be
+  # programmed defensively. When an exception is raised by a delegated method
+  # the proxy will rescue the exception, expose it to the caller as the `reason`
+  # attribute of the returned future, then process the next method call.
+  #
+  # ## Calling Methods Internally
+  #
+  # External method calls should *always* use the `async` and `await` proxy
+  # methods. When one method calls another method, the `async` proxy should
+  # rarely be used and the `await` proxy should *never* be used.
+  #
+  # When an object calls one of its own methods using the `await` proxy the
+  # second call will be enqueued *behind* the currently running method call.
+  # Any attempt to wait on the result will fail as the second call will never
+  # run until after the current call completes.
+  #
+  # Calling a method using the `await` proxy from within a method that was
+  # itself called using `async` or `await` will irreversibly deadlock the
+  # object. Do *not* do this, ever.
+  #
+  # ## Instance Variables and Attribute Accessors
+  #
+  # Instance variables do not need to be thread-safe so long as they are private.
+  # Asynchronous method calls are processed in the order they are received and
+  # are processed one at a time. Therefore private instance variables can only
+  # be accessed by one thread at a time. This is inherently thread-safe.
+  #
+  # When using private instance variables within asynchronous methods, the best
+  # practice is to read the instance variable into a local variable at the start
+  # of the method then update the instance variable at the *end* of the method.
+  # This way, should an exception be raised during method execution the internal
+  # state of the object will not have been changed.
+  #
+  # ### Reader Attributes
+  #
+  # The use of `attr_reader` is discouraged. Internal state exposed externally,
+  # when necessary, should be done through accessor methods. The instance
+  # variables exposed by these methods *must* be thread-safe, or they must be
+  # called using the `async` and `await` proxy methods. These two approaches are
+  # subtly different.
+  #
+  # When internal state is accessed via the `async` and `await` proxy methods,
+  # the returned value represents the object's state *at the time the call is
+  # processed*, which may *not* be the state of the object at the time the call
+  # is made.
+  #
+  # To get the state *at the current* time, irrespective of an enqueued method
+  # calls, a reader method must be called directly. This is inherently unsafe
+  # unless the instance variable is itself thread-safe, preferrably using one
+  # of the thread-safe classes within this library. Because the thread-safe
+  # classes within this library are internally-locking or non-locking, they can
+  # be safely used from within asynchronous methods without causing deadlocks.
+  #
+  # Generally speaking, the best practice is to *not* expose internal state via
+  # reader methods. The best practice is to simply use the method's return value.
+  #
+  # ### Writer Attributes
+  #
+  # Writer attributes should never be used with asynchronous classes. Changing
+  # the state externally, even when done in the thread-safe way, is not logically
+  # consistent. Changes to state need to be timed with respect to all asynchronous
+  # method calls which my be in-process or enqueued. The only safe practice is to
+  # pass all necessary data to each method as arguments and let the method update
+  # the internal state as necessary.
+  #
+  # ## Class Constants, Variables, and Methods
+  #
+  # ### Class Constants
+  #
+  # Class constants do not need to be thread-safe. Since they are read-only and
+  # immutable they may be safely read both externally and from within
+  # asynchronous methods.
+  #
+  # ### Class Variables
+  #
+  # Class variables should be avoided. Class variables represent shared state.
+  # Shared state is anathema to concurrency. Should there be a need to share
+  # state using class variables they *must* be thread-safe, preferrably
+  # using the thread-safe classes within this library. When updating class
+  # variables, never assign a new value/object to the variable itself. Assignment
+  # is not thread-safe in Ruby. Instead, use the thread-safe update functions
+  # of the variable itself to change the value.
+  #
+  # The best practice is to *never* use class variables with `Async` classes.
+  #
+  # ### Class Methods
+  #
+  # Class methods which are pure functions are safe. Class methods which modify
+  # class variables should be avoided, for all the reasons listed above.
+  #
+  # ## An Important Note About Thread Safe Guarantees
+  #
+  # > Thread safe guarantees can only be made when asynchronous method calls
+  # > are not mixed with direct method calls. Use only direct method calls
+  # > when the object is used exclusively on a single thread. Use only
+  # > `async` and `await` when the object is shared between threads. Once you
+  # > call a method using `async` or `await`, you should no longer call methods
+  # > directly on the object. Use `async` and `await` exclusively from then on.
+  #
+  # @example
+  #
+  #   class Echo
+  #     include Concurrent::Async
+  #
+  #     def echo(msg)
+  #       print "#{msg}\n"
+  #     end
+  #   end
+  #
+  #   horn = Echo.new
+  #   horn.echo('zero')      # synchronous, not thread-safe
+  #                          # returns the actual return value of the method
+  #
+  #   horn.async.echo('one') # asynchronous, non-blocking, thread-safe
+  #                          # returns an IVar in the :pending state
+  #
+  #   horn.await.echo('two') # synchronous, blocking, thread-safe
+  #                          # returns an IVar in the :complete state
+  #
+  # @see Concurrent::Actor
+  # @see https://en.wikipedia.org/wiki/Actor_model "Actor Model" at Wikipedia
+  # @see http://www.erlang.org/doc/man/gen_server.html Erlang gen_server
+  # @see http://c2.com/cgi/wiki?LetItCrash "Let It Crash" at http://c2.com/
+  module Async
+
+    # @!method self.new(*args, &block)
+    #
+    #   Instanciate a new object and ensure proper initialization of the
+    #   synchronization mechanisms.
+    #
+    #   @param [Array<Object>] args Zero or more arguments to be passed to the
+    #     object's initializer.
+    #   @param [Proc] block Optional block to pass to the object's initializer.
+    #   @return [Object] A properly initialized object of the asynchronous class.
+
+    # Check for the presence of a method on an object and determine if a given
+    # set of arguments matches the required arity.
+    #
+    # @param [Object] obj the object to check against
+    # @param [Symbol] method the method to check the object for
+    # @param [Array] args zero or more arguments for the arity check
+    #
+    # @raise [NameError] the object does not respond to `method` method
+    # @raise [ArgumentError] the given `args` do not match the arity of `method`
+    #
+    # @note This check is imperfect because of the way Ruby reports the arity of
+    #   methods with a variable number of arguments. It is possible to determine
+    #   if too few arguments are given but impossible to determine if too many
+    #   arguments are given. This check may also fail to recognize dynamic behavior
+    #   of the object, such as methods simulated with `method_missing`.
+    #
+    # @see http://www.ruby-doc.org/core-2.1.1/Method.html#method-i-arity Method#arity
+    # @see http://ruby-doc.org/core-2.1.0/Object.html#method-i-respond_to-3F Object#respond_to?
+    # @see http://www.ruby-doc.org/core-2.1.0/BasicObject.html#method-i-method_missing BasicObject#method_missing
+    #
+    # @!visibility private
+    def self.validate_argc(obj, method, *args)
+      argc = args.length
+      arity = obj.method(method).arity
+
+      if arity >= 0 && argc != arity
+        raise ArgumentError.new("wrong number of arguments (#{argc} for #{arity})")
+      elsif arity < 0 && (arity = (arity + 1).abs) > argc
+        raise ArgumentError.new("wrong number of arguments (#{argc} for #{arity}..*)")
+      end
+    end
+
+    # @!visibility private
+    def self.included(base)
+      base.singleton_class.send(:alias_method, :original_new, :new)
+      base.extend(ClassMethods)
+      super(base)
+    end
+
+    # @!visibility private
+    module ClassMethods
+      def new(*args, &block)
+        obj = original_new(*args, &block)
+        obj.send(:init_synchronization)
+        obj
+      end
+    end
+    private_constant :ClassMethods
+
+    # Delegates asynchronous, thread-safe method calls to the wrapped object.
+    #
+    # @!visibility private
+    class AsyncDelegator < Synchronization::LockableObject
+      safe_initialization!
+
+      # Create a new delegator object wrapping the given delegate.
+      #
+      # @param [Object] delegate the object to wrap and delegate method calls to
+      def initialize(delegate)
+        super()
+        @delegate = delegate
+        @queue = []
+        @executor = Concurrent.global_io_executor
+      end
+
+      # Delegates method calls to the wrapped object.
+      #
+      # @param [Symbol] method the method being called
+      # @param [Array] args zero or more arguments to the method
+      #
+      # @return [IVar] the result of the method call
+      #
+      # @raise [NameError] the object does not respond to `method` method
+      # @raise [ArgumentError] the given `args` do not match the arity of `method`
+      def method_missing(method, *args, &block)
+        super unless @delegate.respond_to?(method)
+        Async::validate_argc(@delegate, method, *args)
+
+        ivar = Concurrent::IVar.new
+        synchronize do
+          @queue.push [ivar, method, args, block]
+          @executor.post { perform } if @queue.length == 1
+        end
+
+        ivar
+      end
+
+      # Perform all enqueued tasks.
+      #
+      # This method must be called from within the executor. It must not be
+      # called while already running. It will loop until the queue is empty.
+      def perform
+        loop do
+          ivar, method, args, block = synchronize { @queue.first }
+          break unless ivar # queue is empty
+
+          begin
+            ivar.set(@delegate.send(method, *args, &block))
+          rescue => error
+            ivar.fail(error)
+          end
+
+          synchronize do
+            @queue.shift
+            return if @queue.empty?
+          end
+        end
+      end
+    end
+    private_constant :AsyncDelegator
+
+    # Delegates synchronous, thread-safe method calls to the wrapped object.
+    #
+    # @!visibility private
+    class AwaitDelegator
+
+      # Create a new delegator object wrapping the given delegate.
+      #
+      # @param [AsyncDelegator] delegate the object to wrap and delegate method calls to
+      def initialize(delegate)
+        @delegate = delegate
+      end
+
+      # Delegates method calls to the wrapped object.
+      #
+      # @param [Symbol] method the method being called
+      # @param [Array] args zero or more arguments to the method
+      #
+      # @return [IVar] the result of the method call
+      #
+      # @raise [NameError] the object does not respond to `method` method
+      # @raise [ArgumentError] the given `args` do not match the arity of `method`
+      def method_missing(method, *args, &block)
+        ivar = @delegate.send(method, *args, &block)
+        ivar.wait
+        ivar
+      end
+    end
+    private_constant :AwaitDelegator
+
+    # Causes the chained method call to be performed asynchronously on the
+    # object's thread. The delegated method will return a future in the
+    # `:pending` state and the method call will have been scheduled on the
+    # object's thread. The final disposition of the method call can be obtained
+    # by inspecting the returned future.
+    #
+    # @!macro [attach] async_thread_safety_warning
+    #   @note The method call is guaranteed to be thread safe with respect to
+    #     all other method calls against the same object that are called with
+    #     either `async` or `await`. The mutable nature of Ruby references
+    #     (and object orientation in general) prevent any other thread safety
+    #     guarantees. Do NOT mix direct method calls with delegated method calls.
+    #     Use *only* delegated method calls when sharing the object between threads.
+    #
+    # @return [Concurrent::IVar] the pending result of the asynchronous operation
+    #
+    # @raise [NameError] the object does not respond to the requested method
+    # @raise [ArgumentError] the given `args` do not match the arity of
+    #   the requested method
+    def async
+      @__async_delegator__
+    end
+    alias_method :cast, :async
+
+    # Causes the chained method call to be performed synchronously on the
+    # current thread. The delegated will return a future in either the
+    # `:fulfilled` or `:rejected` state and the delegated method will have
+    # completed. The final disposition of the delegated method can be obtained
+    # by inspecting the returned future.
+    #
+    # @!macro async_thread_safety_warning
+    #
+    # @return [Concurrent::IVar] the completed result of the synchronous operation
+    #
+    # @raise [NameError] the object does not respond to the requested method
+    # @raise [ArgumentError] the given `args` do not match the arity of the
+    #   requested method
+    def await
+      @__await_delegator__
+    end
+    alias_method :call, :await
+
+    # Initialize the internal serializer and other stnchronization mechanisms.
+    #
+    # @note This method *must* be called immediately upon object construction.
+    #   This is the only way thread-safe initialization can be guaranteed.
+    #
+    # @!visibility private
+    def init_synchronization
+      return self if @__async_initialized__
+      @__async_initialized__ = true
+      @__async_delegator__ = AsyncDelegator.new(self)
+      @__await_delegator__ = AwaitDelegator.new(@__async_delegator__)
+      self
+    end
+  end
+end