|
7 | 7 |
|
8 | 8 | module Concurrent |
9 | 9 |
|
10 | | - # {include:file:doc/agent.md} |
| 10 | + # `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. |
| 11 | + # |
| 12 | + # 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. |
| 13 | + # |
| 14 | + # 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. |
| 15 | + # |
| 16 | + # `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. |
| 17 | + # |
| 18 | + # @!macro copy_options |
| 19 | + # |
| 20 | + # @example Simple Example |
| 21 | + # |
| 22 | + # require 'concurrent' |
| 23 | + # |
| 24 | + # score = Concurrent::Agent.new(10) |
| 25 | + # score.value #=> 10 |
| 26 | + # |
| 27 | + # score << proc{|current| current + 100 } |
| 28 | + # sleep(0.1) |
| 29 | + # score.value #=> 110 |
| 30 | + # |
| 31 | + # score << proc{|current| current * 2 } |
| 32 | + # sleep(0.1) |
| 33 | + # score.value #=> 220 |
| 34 | + # |
| 35 | + # score << proc{|current| current - 50 } |
| 36 | + # sleep(0.1) |
| 37 | + # score.value #=> 170 |
| 38 | + # |
| 39 | + # @example With Validation and Error Handling |
| 40 | + # |
| 41 | + # score = Concurrent::Agent.new(0).validate{|value| value <= 1024 }. |
| 42 | + # rescue(NoMethodError){|ex| puts "Bam!" }. |
| 43 | + # rescue(ArgumentError){|ex| puts "Pow!" }. |
| 44 | + # rescue{|ex| puts "Boom!" } |
| 45 | + # score.value #=> 0 |
| 46 | + # |
| 47 | + # score << proc{|current| current + 2048 } |
| 48 | + # sleep(0.1) |
| 49 | + # score.value #=> 0 |
| 50 | + # |
| 51 | + # score << proc{|current| raise ArgumentError } |
| 52 | + # sleep(0.1) |
| 53 | + # #=> puts "Pow!" |
| 54 | + # score.value #=> 0 |
| 55 | + # |
| 56 | + # score << proc{|current| current + 100 } |
| 57 | + # sleep(0.1) |
| 58 | + # score.value #=> 100 |
| 59 | + # |
| 60 | + # @example With Observation |
| 61 | + # |
| 62 | + # bingo = Class.new{ |
| 63 | + # def update(time, score) |
| 64 | + # puts "Bingo! [score: #{score}, time: #{time}]" if score >= 100 |
| 65 | + # end |
| 66 | + # }.new |
| 67 | + # |
| 68 | + # score = Concurrent::Agent.new(0) |
| 69 | + # score.add_observer(bingo) |
| 70 | + # |
| 71 | + # score << proc{|current| sleep(0.1); current += 30 } |
| 72 | + # score << proc{|current| sleep(0.1); current += 30 } |
| 73 | + # score << proc{|current| sleep(0.1); current += 30 } |
| 74 | + # score << proc{|current| sleep(0.1); current += 30 } |
| 75 | + # |
| 76 | + # sleep(1) |
| 77 | + # #=> Bingo! [score: 120, time: 2013-07-22 21:26:08 -0400] |
11 | 78 | # |
12 | 79 | # @!attribute [r] timeout |
13 | 80 | # @return [Fixnum] the maximum number of seconds before an update is cancelled |
|
0 commit comments