Moved documentation from wiki to Yardoc.

Author: jdantonio

doc/agent.md

@@ -0,0 +1,82 @@
+`Agent`s are inspired by [Clojure's](http://clojure.org/) [agent](http://clojure.org/agents) function. An `Agent` is a single atomic value that represents an identity. The current value of the `Agent` can be requested at any time (`deref`). Each `Agent` has a work queue and operates on the global thread pool (see below). Consumers can `post` code blocks to the `Agent`. The code block (function) will receive the current value of the `Agent` as its sole parameter. The return value of the block will become the new value of the `Agent`. `Agent`s support two error handling modes: fail and continue. A good example of an `Agent` is a shared incrementing counter, such as the score in a video game. 
+
+An `Agent` must be initialize with an initial value. This value is always accessible via the `value` (or `deref`) methods. Code blocks sent to the `Agent` will be processed in the order received. As each block is processed the current value is updated with the result from the block. This update is an atomic operation so a `deref` will never block and will always return the current value. 
+
+When an `Agent` is created it may be given an optional `validate` block and zero or more `rescue` blocks. When a new value is calculated the value will be checked against the validator, if present. If the validator returns `true` the new value will be accepted. If it returns `false` it will be rejected. If a block raises an exception during execution the list of `rescue` blocks will be seacrhed in order until one matching the current exception is found. That `rescue` block will then be called an passed the exception object. If no matching `rescue` block is found, or none were configured, then the exception will be suppressed. 
+
+`Agent`s also implement Ruby's [Observable](http://ruby-doc.org/stdlib-2.0/libdoc/observer/rdoc/Observable.html). Code that observes an `Agent` will receive a callback with the new value any time the value is changed. 
+
+## Copy Options
+
+Object references in Ruby are mutable. This can lead to serious problems when the value of an `Agent` is a mutable reference. Which is always the case unless the value is a `Fixnum`, `Symbol`, or similar "primative" data type. Each `Agent` 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 `Agent` is created: 
+
+* `:dup_on_deref` when true the `Agent` will call the `#dup` method on the `value` object every time the `#value` methid is called (default: false)
+* `:freeze_on_deref` when true the `Agent` 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 parameter 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)
+
+## Examples
+
+A simple example:
+
+```ruby
+require 'concurrent'
+
+score = Concurrent::Agent.new(10)
+score.value #=> 10
+
+score << proc{|current| current + 100 }
+sleep(0.1)
+score.value #=> 110
+
+score << proc{|current| current * 2 }
+sleep(0.1)
+score.value #=> 220
+
+score << proc{|current| current - 50 }
+sleep(0.1)
+score.value #=> 170
+```
+
+With validation and error handling:
+
+```ruby
+score = Concurrent::Agent.new(0).validate{|value| value <= 1024 }.
+          rescue(NoMethodError){|ex| puts "Bam!" }.
+          rescue(ArgumentError){|ex| puts "Pow!" }.
+          rescue{|ex| puts "Boom!" }
+score.value #=> 0
+
+score << proc{|current| current + 2048 }
+sleep(0.1)
+score.value #=> 0
+
+score << proc{|current| raise ArgumentError }
+sleep(0.1)
+#=> puts "Pow!"
+score.value #=> 0
+
+score << proc{|current| current + 100 }
+sleep(0.1)
+score.value #=> 100
+```
+
+With observation:
+
+```ruby
+bingo = Class.new{
+  def update(time, score)
+    puts "Bingo! [score: #{score}, time: #{time}]" if score >= 100
+  end
+}.new
+
+score = Concurrent::Agent.new(0)
+score.add_observer(bingo)
+
+score << proc{|current| sleep(0.1); current += 30 }
+score << proc{|current| sleep(0.1); current += 30 }
+score << proc{|current| sleep(0.1); current += 30 }
+score << proc{|current| sleep(0.1); current += 30 }
+
+sleep(1)
+#=> Bingo! [score: 120, time: 2013-07-22 21:26:08 -0400]
+```

doc/async.md

@@ -0,0 +1,134 @@
+A mixin module that provides simple asynchronous behavior to any standard
+class/object or object. 
+
+```cucumber
+Feature:
+  As a stateful, plain old Ruby class/object
+  I want safe, asynchronous behavior
+  So my long-running methods don't block the main thread
+```
+
+Stateful, mutable objects must be managed carefully when used asynchronously.
+But Ruby is an object-oriented language so designing with objects and classes
+plays to Ruby's strengths and is often more natural to many Ruby programmers.
+The `Async` module is a way to mix simple yet powerful asynchronous capabilities
+into any plain old Ruby object or class. These capabilities provide a reasonable
+level of thread safe guarantees when used correctly.
+
+When this module is mixed into a class or object it provides to new methods:
+`async` and `await`. These methods are thread safe with respect to the enclosing
+object. The former method allows methods to be called asynchronously by posting
+to the global thread pool. The latter allows a method to be called synchronously
+on the current thread but does so safely with respect to any pending asynchronous
+method calls. Both methods return an `Obligation` which can be inspected for
+the result of the method call. Calling a method with `async` will return a
+`:pending` `Obligation` whereas `await` will return a `:complete` `Obligation`.
+
+Very loosely based on the `async` and `await` keywords in C#.
+
+#### An Important Note About Initialization
+
+> This module depends on several internal synchronization objects that
+> must be initialized prior to calling any of the async/await/executor methods.
+> The best practice is to call `init_mutex` from within the constructor
+> of the including class. A less ideal but acceptable practice is for the
+> thread creating the asynchronous object to explicitly call the `init_mutex`
+> method prior to calling any of the async/await/executor methods. If
+> `init_mutex` is *not* called explicitly the async/await/executor methods
+> will raise a `Concurrent::InitializationError`. This is the only way 
+> thread-safe initialization can be guaranteed.
+
+#### An Important Note About Thread Safe Guarantees
+
+> Thread safe guarantees can only be made when asynchronous method calls
+> are not mixed with synchronous method calls. Use only synchronous 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`, you should no longer call any methods
+> directly on the object. Use `async` and `await` exclusively from then on.
+> With careful programming it is possible to switch back and forth but it's
+> also very easy to create race conditions and break your application.
+> Basically, it's "async all the way down."
+
+### Examples
+
+#### Defining an asynchronous class
+
+```cucumber
+Scenario: Defining an asynchronous class
+  Given a class definition
+  When I include the Concurrent::Async module
+  Then an `async` method is defined for all objects of the class
+  And an `await` method is defined for all objects of the class
+
+Scenario: Calling the `async` method
+  Given a class which includes Concurrent::Async module
+  When I call a normal method through the `async` delegate method
+  Then the method returns a Concurrent::Future object
+  And the method is executed on a background thread using the global thread pool
+  And the current thread does not block
+  And thread safety is provided with respect to other `async` and `await` calls
+  And the returned future can be interrogated for the status of the method call
+  And the returned future will eventually contain the `value` of the method call
+  Or the returned future will eventually contain the `reason` the method call failed
+
+Scenario: Calling the `await` method
+  Given a class which includes Concurrent::Async module
+  When I call a normal method through the `await` delegate method
+  Then the method returns a Concurrent::IVar object
+  And the method is executed on the current thread
+  And thread safety is provided with respect to other `async` and `await` calls
+  And the returned ivar will be in the :fulfilled state
+  Or the returned ivar will be in the :rejected state
+  And the returned ivar will immediately contain the `value` of the method call
+  Or the returned ivar will immediately contain the `reason` the method call failed
+```
+
+```ruby
+class Echo
+  include Concurrent::Async
+
+  def initialize
+    init_mutex # initialize the internal synchronization objects
+  end
+
+  def echo(msg)
+    sleep(rand)
+    print "#{msg}\n"
+    nil
+  end
+end
+
+horn = Echo.new
+horn.echo('zero') # synchronous, not thread-safe
+
+horn.async.echo('one') # asynchronous, non-blocking, thread-safe
+horn.await.echo('two') # synchronous, blocking, thread-safe
+```
+
+#### Monkey-patching an existing object
+
+```cucumber
+Scenario: Monkey-patching an existing object
+  Given an object of a class that does not include the Concurrent::Async module
+  When I extend the object with the Concurrent::Async module
+  Then an `async` method is monkey-patched onto the object
+  And an `await` method is monkey-patched onto the object
+  And the object behaved as though Concurrent::Async were included in the class
+  And the `async` and `await` methods perform as expected
+  And no other objects of that class are affected
+```
+
+```ruby
+numbers = 1_000_000.times.collect{ rand }
+numbers.extend(Concurrent::Async)
+numbers.init_mutex # initialize the internal synchronization objects
+  
+future = numbers.async.max
+future.state #=> :pending
+  
+sleep(2)
+  
+future.state #=> :fulfilled
+future.value #=> 0.999999138918843
+```