concurrent-ruby 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f88c2ee3113049d6c98628f54585643f62329249
-  data.tar.gz: 710552f92a683ba9a66ec30f8ea07567890e5dfe
+  metadata.gz: de0e0da91bc658bb4ed962ec88d82b3997b95a09
+  data.tar.gz: 35d3a5d3111ff16f3a7782f38736e84b25007fc1
 SHA512:
-  metadata.gz: d13cfa849aed3f685ba1282f93ee9558bca755cc4c52cfc2b6531f8f585282735f827f89a465fda7c8a0765cdd1aa343477b6d764ee7f1a775ab6048e06ed97d
-  data.tar.gz: 0e70b81e3930680b8771ed2b754425d6786f57ac2b07ebbda3bf4d570b07533e0f388dd430835d8323e9d1c3e9687336543cc97d5dfdb43c601323211bac884a
+  metadata.gz: 804490a05bcf41198363ec31ec285535039dd9beb9a4a46cf2e266c7b26ca333f9dada1ecfafacb8a3f9146c1b63cf5b699385d011306cceea8d6ddbc78f9ff8
+  data.tar.gz: b2a9eaec2ce45a071ee8ef9dc3695f3842c8b23dea252d52e8c3ac5a0fd533aa290ff6e278055173388459a92f0d33c8e41d896d872b04870a9575d5e1a2e4c3

data/README.md

@@ -1,10 +1,7 @@
 # Concurrent Ruby [![Build Status](https://secure.travis-ci.org/jdantonio/concurrent-ruby.png)](https://travis-ci.org/jdantonio/concurrent-ruby?branch=master) [![Coverage Status](https://coveralls.io/repos/jdantonio/concurrent-ruby/badge.png)](https://coveralls.io/r/jdantonio/concurrent-ruby) [![Dependency Status](https://gemnasium.com/jdantonio/concurrent-ruby.png)](https://gemnasium.com/jdantonio/concurrent-ruby)
 
 Modern concurrency tools including agents, futures, promises, thread pools, supervisors, and more.
-Inspired by Erlang, Clojure, Go, JavaScript, actors, and classic concurrency patterns.
-
-If you find this gem useful you should check out my [functional-ruby](https://github.com/jdantonio/functional-ruby)
-gem, too. This gem uses several of the tools in that gem.
+Inspired by Erlang, Clojure, Scala, Go, Java, JavaScript, and classic concurrency patterns.
 
 ## Introduction
 

data/lib/concurrent/actor.rb

@@ -82,6 +82,7 @@ module Concurrent
       end
     end
 
+    # FIXME: duplicate the block (thread safety)
     def self.pool(count, &block)
       raise ArgumentError.new('count must be greater than zero') unless count > 0
       mailbox = Queue.new

data/lib/concurrent/runnable.rb

@@ -14,6 +14,7 @@ module Concurrent
           Thread.abort_on_exception = false
           runner.run
         end
+        @thread.join(0.1) # let the thread start
       end
     end
 
@@ -32,11 +33,11 @@ module Concurrent
 
     def run!(abort_on_exception = false)
       raise LifecycleError.new('already running') if @running
-      thread = Thread.new{
+      thread = Thread.new do
         Thread.current.abort_on_exception = abort_on_exception
         self.run
-      }
-      Thread.pass
+      end
+      thread.join(0.1) # let the thread start
       return thread
     end
 

data/lib/concurrent/version.rb

@@ -1,3 +1,3 @@
 module Concurrent
-  VERSION = '0.3.1'
+  VERSION = '0.3.2'
 end

data/md/actor.md

@@ -15,17 +15,25 @@ A good definition of "actor" is:
 The `Concurrent::Actor` class in this library is based solely on the
 [Actor](http://www.scala-lang.org/api/current/index.html#scala.actors.Actor) task
 defined in the Scala standard library. It does not implement all the features of
-Scala's `Actor` but its behavior for what *has* been implemented is nearly identical
+Scala's `Actor` but its behavior for what *has* been implemented is nearly identical.
+The excluded features mostly deal with Scala's message semantics, strong typing,
+and other characteristics of Scala that don't really apply to Ruby.
+
+Unlike most of the abstractions in this library, `Actor` takes an *object-oriented*
+approach to asynchronous concurrency, rather than a *functional programming*
+approach.
 
 ## Definition
 
 Actors are defined by subclassing the `Concurrent::Actor` class and overriding the
 `#act` method. The `#act` method can have any signature/arity but
 
-> def act(*args, &block)
+```ruby
+def act(*args, &block)
+```
 
 is the most flexible and least error-prone signature. The `#act` method is called in
-response to a message being `#post` to the `Actor` instance (see *Behavior* below).
+response to a message being post to the `Actor` instance (see *Behavior* below).
 
 ## Behavior
 
@@ -34,13 +42,133 @@ an `Actor` instance with the necessary methods for running and graceful stopping
 This also means that an `Actor` can be managed by a `Concurrent::Supervisor` for
 fault tolerance.
 
-Messages from any thread can be sent to an `Actor` using either the `#post` method. Calling
-this method causes all arguments and a block (if given) to be passed to the subclass `#act`
-method. Messages are processed one at a time in the order received. Each `Actor` subclass
-must detemine how it will interact with the rest of the system. A common practice is for
+### Message Passing
+
+Messages from any thread can be sent (aka "post") to an `Actor` using several methods.
+When a message is post all arguments are gathered together and queued for processing.
+Messages are processed in the order they are received, one at a time, on a dedicated
+thread. When a message is processed the subclass `#act` method is called and the return
+value (or raised exception) is handled by the superclass based on the rules of the method
+used to post the message.
+
+All message posting methods are compatible with observation (see below).
+
+Message processing within the `#act` method is not limited in any way, but care should
+be taken to behave in a thread-safe, concurrency-friendly manner. A common practice is for
 one `Actor` to send messages to another `Actor` though this is hardly the only approach.
 
-## Pools
+Messages post to an `Actor` that is not running will be rejected.
+
+#### Fire and Forget
+
+The primary method of posting a message to an `Actor` is the simple `#post` method.
+When this method is called the message is queued for processing. The method returns
+false if it cannot be queued (the `Actor` is not running) otherwise it returns the
+size of the queue (after queueing the new message). The caller thread has no way
+to know the result of the message processing. When the `#post` method is used the
+only way to act upon the result of the message processing is via observation
+(see below).
+
+#### Post with an Obligation
+
+A common theme in modern asynchronous concurrency is for operations to return a
+"future" (or "promise"). In this context a "future" is not an instance of the
+`Concurrent::Future` class, but it is an object with similar behavior. Within
+this library "future" behavior is genericized by the `Concurrent::Obligation`
+mixin module (shared by `Future`, `Promise`, and others).
+
+To post a message that returns a `Obligation` use the `#post?` method. If the message
+cannot be queued the method will return `nil`. Otherwise an object implementing
+`Obligation` will returned. The `Obligation` has the exteced states (`:pending`,
+`:fulfilled`, and `:rejected`), the expected state-named predicate methods,
+plus `#value` and `#reason`. These methods all behave identically to `Concurrent::Future`.
+
+#### Post with Timeout
+
+Threads posting messages to an `Actor` should generally not block. Blocking to wait
+for an `Actor` to process a specific message defeats the purpose of asynchronous
+concurrency. The `#post!` method is provided when the caller absolutely must block.
+The first argument to `#post!` is a number of seconds to block while waiting for the
+operation to complete. All subsequent arguments constitute the message and are
+queued for delivery to the `#act` method. If the queued operation completes within
+the timeout period the `#post!` method returns the result of the operation.
+
+Unlike most methods in this library, the `#post!` method does not suppress exceptions.
+Because the `#post!` method return value represents the result of message processing
+the return value cannot effectively communicate failure. Instead, exceptions are used.
+Calls to the `#post!` method should generally be wrapped in `rescue` guards. The
+following exceptions may be raised by the `#post!` method:
+
+* `Concurrent::Runnable::LifecycleError` will be raised if the message cannot be
+  queued, such as when the `Actor` is not running.
+* `Concurrent::TimeoutError` will be raised if the message is not processed within
+  the designated timeout period
+* Any exception raised during message processing will be re-raised after all
+  post-processing operations (such as observer callbacks) have completed
+
+When the `#post!` method results in a timeout the `Actor` will attempt to cancel
+message processing, but cancellation is not guaranteed. If message processing has
+not begun the cancellation will normally occur. If message processing is in-progress
+when `#post!` reaches timeout then processing will be allowed to complete. Code that
+uses the `#post!` method must therefore not assume that a timeout means that message
+processing did not occur.
+
+#### Implicit Forward/Reply
+
+A common idiom is for an `Actor` to send messages to another `Actor`. This creates
+a "data flow" style of design not dissimilar to Unix-style pipe commands. Less common,
+but still frequent, is for an `Actor` to send the result of message processing back
+to the `Actor` that sent the message. In Scala this is easy to do. The underlying
+message passing system implicitly communicates to the receiver the address of the
+sender. Therefore, Scala actors can easily reply to the sender. Ruby has no similar
+message passing subsystem to implicit knowledge of the sender is not possible. This
+`Actor` implementation provides a `#forward` method that encapsulates both
+aforementioned idioms. The first argument to the `#forward` method is a reference
+to another `Actor` to which the receiving `Actor` should forward the result of
+the processed messages. All subsequent arguments constitute the message and are
+queued for delivery to the `#act` method.
+
+Upon successful message processing the `Actor` superclass will automatically
+forward the result to the receiver provided when `#forward` was called. If an
+exception is raised no forwarding occurs.
+
+### Error Handling
+
+Because `Actor` mixes in the `Concurrent::Runnable` module subclasses have access to
+the `#on_error` method and can override it to implement custom error handling. The
+`Actor` base class does not use `#on_error` so as to avoid conflit with subclasses
+which override it. Generally speaking, `#on_error` should not be used. The `Actor`
+base class provides concictent, reliable, and robust error handling already, and
+error handling specifics are tied to the message posting method. Incorrect behavior
+in an `#on_error` override can lead to inconsistent `Actor` behavior that may lead
+to confusion and difficult debugging.
+
+### Observation
+
+The `Actor` superclass mixes in the Ruby standard library
+[Observable](http://ruby-doc.org/stdlib-1.9.3/libdoc/observer/rdoc/Observable.html)
+module to provide consistent callbacks upon message processing completion. The normal
+`Observable` methods, including `#add_observer` behave normally. Once an observer
+is added to an `Actor` it will be notified of all messages processed *after*
+addition. Notification will *not* occur for any messages that have already been
+processed.
+
+Observers will be notified regardless of whether the message processing is successful
+or not. The `#update` method of the observer will receive four arguments. The
+appropriate method signature is:
+
+```ruby
+def update(time, message, result, reason)
+```
+
+These four arguments represent:
+
+* The time that message processing was completed
+* An array containing all elements of the original message, in order
+* The result of the call to `#act` (will be `nil` if an exception was raised)
+* Any exception raised by `#act` (or `nil` if message processing was successful)
+
+### Actor Pools
 
 Every `Actor` instance operates on its own thread. When one thread isn't enough capacity
 to manage all the messages being sent to an `Actor` a *pool* can be used instead. A pool
@@ -58,7 +186,7 @@ load balance.
 ## Examples
 
 Two `Actor`s playing a back and forth game of Ping Pong, adapted from the Scala example
-[here](http://www.somewhere.com/find/the/blog/post):
+[here](http://www.scala-lang.org/old/node/242):
 
 ```ruby
 class Ping < Concurrent::Actor
@@ -146,20 +274,45 @@ pool.post('YAHOO')
 #>> [2013-10-18 09:35:28 -0400] RECEIVED 'YAHOO' to #<FinanceActor:0x0000010331af70>...
 ```
 
-The `#post!` method returns an `Obligation` (same API as `Future`) which can be queried
+The `#post` method simply sends a message to an actor and returns. It's a
+fire-and-forget interaction.
+
+```ruby
+class EchoActor < Concurrent::Actor
+  def act(*message)
+    p message
+  end
+end
+
+echo = EchoActor.new
+echo.run!
+
+echo.post("Don't panic") #=> true
+#=> ["Don't panic"]
+
+echo.post(1, 2, 3, 4, 5) #=> true
+#=> [1, 2, 3, 4, 5]
+
+echo << "There's a frood who really knows where his towel is." #=> #<EchoActor:0x007fc8012b8448...
+#=> ["There's a frood who really knows where his towel is."]
+```
+
+The `#post?` method returns an `Obligation` (same API as `Future`) which can be queried
 for value/reason on fulfillment/rejection.
 
 ```ruby
 class EverythingActor < Concurrent::Actor
   def act(message)
-    sleep(1)
+    sleep(5)
     return 42
   end
 end
 
 life = EverythingActor.new
 life.run!
-universe = life.post!('What do you get when you multiply six by nine?')
+sleep(0.1)
+
+universe = life.post?('What do you get when you multiply six by nine?')
 universe.pending? #=> true
 
 # wait for it...
@@ -168,15 +321,57 @@ universe.fulfilled? #=> true
 universe.value      #=> 42
 ```
 
-The `#post?` method is a blocking call. It takes a number of seconds to wait as the
+The `#post!` method is a blocking call. It takes a number of seconds to wait as the
 first parameter and any number of additional parameters as the message. If the message
 is processed within the given number of seconds the call returns the result of the
 operation. If message processing raises an exception the exception is raised again
-by the `#post?` method. If the call to `#post?` times out a `Concurrent::Timeout`
+by the `#post!` method. If the call to `#post!` times out a `Concurrent::Timeout`
 exception is raised.
 
 ```ruby
-# needs code examples...
+life = EverythingActor.new
+life.run!
+sleep(0.1)
+
+life.post!(1, 'Mostly harmless.')
+
+# wait for it...
+#=> Concurrent::TimeoutError: Concurrent::TimeoutError
+```
+
+And, of course, the `Actor` class mixes in Ruby's `Observable`.
+
+```ruby
+class ActorObserver
+  def update(time, message, result, ex)
+    if result
+      print "(#{time}) Message #{message} returned #{result}\n"
+    elsif ex.is_a?(Concurrent::TimeoutError)
+      print "(#{time}) Message #{message} timed out\n"
+    else
+      print "(#{time}) Message #{message} failed with error #{ex}\n"
+    end
+  end
+end
+
+class SimpleActor < Concurrent::Actor
+  def act(*message)
+    message
+  end
+end
+
+actor = SimpleActor.new
+actor.add_observer(ActorObserver.new)
+actor.run!
+
+actor.post(1)
+#=> (2013-11-07 18:35:33 -0500) Message [1] returned [1]
+
+actor.post(1,2,3)
+#=> (2013-11-07 18:35:54 -0500) Message [1, 2, 3] returned [1, 2, 3]
+
+actor.post('The Nightman Cometh')
+#=> (2013-11-07 18:36:11 -0500) Message ["The Nightman Cometh"] returned ["The Nightman Cometh"]
 ```
 
 ## Copyright

data/md/{event.md → dereferenceable.md}

@@ -1,6 +1,25 @@
-# Event
+# Dereferenceable
 
-TBD...
+Object references in Ruby are mutable. This can lead to serious problems when
+the `#value` of a concurrent object is a mutable reference. Which is always the
+case unless the value is a `Fixnum`, `Symbol`, or similar "primative" data type.
+Most classes in this library that expose a `#value` getter method do so using
+the Dereferenceable mixin module.
+
+
+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)
 
 ## Copyright
 

data/md/scheduled_task.md

@@ -1,8 +1,130 @@
 # I'm late! For a very important date!
 
-TBD
+`ScheduledTask` is a close relative of `Concurrent::Future` but with one
+important difference. A `Future` is set to execute as soon as possible
+whereas a `ScheduledTask` is set to execute at a specific time. This implementation
+is loosely based on Java's
+[ScheduledExecutorService](http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/ScheduledExecutorService.html).
 
-[ScheduledExecutorService](http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/ScheduledExecutorService.html)
+## Scheduling
+
+The scheduled time of task execution is set on object construction. The first
+parameter to `#new` is the task execution time. The time can be a numeric (floating
+point or integer) representing a number of seconds in the future or it can ba a
+`Time` object representing the approximate time of execution. Any other value,
+a numeric equal to or less than zero, or a time in the past will result in
+an `ArgumentError` being raised.
+
+The constructor can also be given zero or more processing options. Currently the
+only supported options are those recognized by the
+[Dereferenceable](https://github.com/jdantonio/concurrent-ruby/blob/master/md/dereferenceable.md)
+module.
+
+The final constructor argument is a block representing the task to be performed
+at the scheduled time. If no block is given an `ArgumentError` will be raised.
+
+### States
+
+`ScheduledTask` mixes in the 
+[Obligation](https://github.com/jdantonio/concurrent-ruby/blob/master/md/obligation.md)
+module thus giving it "future" behavior. This includes the expected lifecycle states.
+`ScheduledTask` has one additional state, however. While the task (block) is being
+executed the state of the object will be `:in_progress`. This additional state is 
+necessary because it has implications for task cancellation.
+
+### Cancellation
+
+A `:pending` task can be cancelled using the `#cancel` method. A task in any other
+state, including `:in_progress`, cannot be cancelled. The `#cancel` method returns
+a boolean indicating the success of the cancellation attempt. A cancelled `ScheduledTask`
+cannot be restarted. It is immutable.
+
+## Obligation and Observation
+
+The result of a `ScheduledTask` can be obtained either synchronously or asynchronously.
+`ScheduledTask` mixes in both the
+[Obligation](https://github.com/jdantonio/concurrent-ruby/blob/master/md/obligation.md)
+module and the
+[Observable](http://ruby-doc.org/stdlib-1.9.3/libdoc/observer/rdoc/Observable.html)
+module from the Ruby standard library. With one exception `ScheduledTask` behaves
+identically to
+[Concurrent::Future](https://github.com/jdantonio/concurrent-ruby/blob/master/md/future.md)
+with regard to these modules.
+
+Unlike `Future`, however, an observer added to a `ScheduledTask` *after* the task
+operation has completed will *not* receive notification. The reason for this is the
+subtle but important difference in intent between the two abstractions. With a
+`Future` there is no way to know when the operation will complete. Therefore the
+*expected* behavior of an observer is to be notified. With a `ScheduledTask` however,
+the approximate time of execution is known. It is often explicitly set as a constructor
+argument. It is always available via the `#schedule_time` attribute reader. Therefore
+it is always possible for calling code to know whether the observer is being added
+prior to task execution. It is also easy to add an observer long before task
+execution begins (since there is never a reason to create a scheduled task that starts
+immediately). Subsequently, the *expectation* is that the caller of `#add_observer`
+is making the call within an appropriate time.
+
+## Examples
+
+Successful task execution using seconds for scheduling:
+
+```ruby
+require 'concurrent'
+
+task = Concurrent::ScheduledTask.new(2){ 'What does the fox say?' }
+task.pending?      #=> true
+task.schedule_time #=> 2013-11-07 12:20:07 -0500
+
+# wait for it...
+sleep(3)
+
+task.pending?   #=> false
+task.fulfilled? #=> true
+task.rejected?  #=> false
+task.value      #=> 'What does the fox say?'
+```
+
+Failed task execution using a `Time` object for scheduling:
+
+```ruby
+require 'concurrent'
+
+t = Time.now + 2
+task = Concurrent::ScheduledTask.new(t){ raise StandardError.new('Call me maybe?') }
+task.pending?      #=> true
+task.schedule_time #=> 2013-11-07 12:22:01 -0500
+
+# wait for it...
+sleep(3)
+
+task.pending?   #=> false
+task.fulfilled? #=> false
+task.rejected?  #=> true
+task.value      #=> nil
+task.reason     #=> #<StandardError: Call me maybe?> 
+```
+
+Task execution with observation:
+
+```ruby
+require 'concurrent'
+
+observer = Class.new{
+  def update(time, value, reason)
+    puts "The task completed at #{time} with value '#{value}'"
+  end
+}.new
+
+task = Concurrent::ScheduledTask.new(2){ 'What does the fox say?' }
+task.add_observer(observer)
+task.pending?      #=> true
+task.schedule_time #=> 2013-11-07 12:20:07 -0500
+
+# wait for it...
+sleep(3)
+
+#>> The task completed at 2013-11-07 12:26:09 -0500 with value 'What does the fox say?'
+```
 
 ## Copyright
 

data/md/timer_task.md

@@ -25,6 +25,9 @@ Unlike other abstraction in this library, `TimerTask` does not run on the global
 In my experience the types of tasks that will benefit from `TimerTask` tend to also be long
 running. For this reason they get their own thread every time the task is executed.
 
+This class is based on the Java class
+[of the same name](http://docs.oracle.com/javase/7/docs/api/java/util/TimerTask.html).
+
 ## Observation
 
 `TimerTask` supports notification through the Ruby standard library
@@ -41,37 +44,54 @@ A basic example:
 ```ruby
 require 'concurrent'
 
-ec = Concurrent::TimerTask.run{ puts 'Boom!' }
+task = Concurrent::TimerTask.new{ puts 'Boom!' }
+task.run!
 
-ec.execution_interval #=> 60 == Concurrent::TimerTask::EXECUTION_INTERVAL
-ec.timeout_interval   #=> 30 == Concurrent::TimerTask::TIMEOUT_INTERVAL
-ec.status             #=> "sleep"
+task.execution_interval #=> 60 (default)
+task.timeout_interval   #=> 30 (default)
 
 # wait 60 seconds...
 #=> 'Boom!'
 
-ec.kill #=> true
+task.stop #=> true
 ```
 
 Both the execution_interval and the timeout_interval can be configured:
 
 ```ruby
-ec = Concurrent::TimerTask.run(execution_interval: 5, timeout_interval: 5) do
+task = Concurrent::TimerTask.new(execution_interval: 5, timeout_interval: 5) do
        puts 'Boom!'
      end
 
-ec.runner.execution_interval #=> 5
-ec.runner.timeout_interval   #=> 5
+task.execution_interval #=> 5
+task.timeout_interval   #=> 5
 ```
 
 By default an `TimerTask` will wait for `:execution_interval` seconds before running the block.
 To run the block immediately set the `:run_now` option to `true`:
 
 ```ruby
-ec = Concurrent::TimerTask.run(run_now: true){ puts 'Boom!' }
-#=> 'Boom!''
-ec.thread.status #=> "sleep"
->> 
+task = Concurrent::TimerTask.new(run_now: true){ puts 'Boom!' }
+task.run!
+
+#=> 'Boom!'
+```
+
+The `TimerTask` class includes the `Dereferenceable` mixin module so the result of
+the last execution is always available via the `#value` method. Derefencing options
+can be passed to the `TimerTask` during construction or at any later time using the
+`#set_deref_options` method.
+
+```ruby
+task = Concurrent::TimerTask.new(
+  dup_on_deref: true,
+  execution_interval: 5
+){ Time.now }
+
+task.run!
+Time.now   #=> 2013-11-07 18:06:50 -0500
+sleep(10)
+task.value #=> 2013-11-07 18:06:55 -0500
 ```
 
 A simple example with observation:
@@ -89,29 +109,56 @@ class TaskObserver
   end
 end
 
-task = Concurrent::TimerTask.run!(execution_interval: 1, timeout_interval: 1){ 42 }
-task.runner.add_observer(TaskObserver.new)
+task = Concurrent::TimerTask.new(execution_interval: 1, timeout_interval: 1){ 42 }
+task.add_observer(TaskObserver.new)
+task.run!
 
 #=> (2013-10-13 19:08:58 -0400) Execution successfully returned 42
 #=> (2013-10-13 19:08:59 -0400) Execution successfully returned 42
 #=> (2013-10-13 19:09:00 -0400) Execution successfully returned 42
-task.runner.stop
+task.stop
 
-task = Concurrent::TimerTask.run!(execution_interval: 1, timeout_interval: 1){ sleep }
-task.runner.add_observer(TaskObserver.new)
+task = Concurrent::TimerTask.new(execution_interval: 1, timeout_interval: 1){ sleep }
+task.add_observer(TaskObserver.new)
+task.run!
 
 #=> (2013-10-13 19:07:25 -0400) Execution timed out
 #=> (2013-10-13 19:07:27 -0400) Execution timed out
 #=> (2013-10-13 19:07:29 -0400) Execution timed out
-task.runner.stop
+task.stop
 
-task = Concurrent::TimerTask.run!(execution_interval: 1){ raise StandardError }
-task.runner.add_observer(TaskObserver.new)
+task = Concurrent::TimerTask.new(execution_interval: 1){ raise StandardError }
+task.add_observer(TaskObserver.new)
+task.run!
 
 #=> (2013-10-13 19:09:37 -0400) Execution failed with error StandardError
 #=> (2013-10-13 19:09:38 -0400) Execution failed with error StandardError
 #=> (2013-10-13 19:09:39 -0400) Execution failed with error StandardError
-task.runner.stop
+task.stop
+```
+
+In some cases it may be necessary for a `TimerTask` to affect its own execution cycle.
+To facilitate this a reference to the task object is passed into the block as a block
+argument every time the task is executed.
+
+```ruby
+timer_task = Concurrent::TimerTask.new(execution_interval: 1) do |task|
+  task.execution_interval.times{ print 'Boom! ' }
+  print "\n"
+  task.execution_interval += 1
+  if task.execution_interval > 5
+    puts 'Stopping...'
+    task.stop
+  end
+end
+
+timer_task.run # blocking call - this task will stop itself
+#=> Boom!
+#=> Boom! Boom!
+#=> Boom! Boom! Boom!
+#=> Boom! Boom! Boom! Boom!
+#=> Boom! Boom! Boom! Boom! Boom!
+#=> Stopping...
 ```
 
 ## Copyright

data/spec/concurrent/runnable_spec.rb

@@ -155,7 +155,8 @@ module Concurrent
       end
 
       it 'creates a new thread' do
-        Thread.should_receive(:new).with(no_args())
+        t = Thread.new{ nil }
+        Thread.should_receive(:new).with(no_args()).and_return(t)
         @thread = subject.run!
       end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: concurrent-ruby
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Jerry D'Antonio
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-06 00:00:00.000000000 Z
+date: 2013-11-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -61,7 +61,7 @@ files:
 - lib/concurrent_ruby.rb
 - md/actor.md
 - md/agent.md
-- md/event.md
+- md/dereferenceable.md
 - md/future.md
 - md/goroutine.md
 - md/obligation.md