|
| 1 | +require 'concurrent/dereferenceable' |
| 2 | +require 'concurrent/atomic/atomic_reference' |
| 3 | +require 'concurrent/synchronization/object' |
| 4 | + |
| 5 | +module Concurrent |
| 6 | + |
| 7 | + # Atoms provide a way to manage shared, synchronous, independent state. |
| 8 | + # |
| 9 | + # An atom is initialized with an initial value and an optional validation |
| 10 | + # proc. At any time the value of the atom can be synchronously and safely |
| 11 | + # changed. If a validator is given at construction then any new value |
| 12 | + # will be checked against the validator and will be rejected if the |
| 13 | + # validator returns false or raises an exception. |
| 14 | + # |
| 15 | + # There are two ways to change the value of an atom: {#compare_and_set} and |
| 16 | + # {#swap}. The former will set the new value if and only if it validates and |
| 17 | + # the current value matches the new value. The latter will atomically set the |
| 18 | + # new value to the result of running the given block if and only if that |
| 19 | + # value validates. |
| 20 | + # |
| 21 | + # @!macro copy_options |
| 22 | + # |
| 23 | + # @see http://clojure.org/atoms Clojure Atoms |
| 24 | + class Atom < Synchronization::Object |
| 25 | + include Dereferenceable |
| 26 | + |
| 27 | + # @!macro [attach] atom_initialize |
| 28 | + # |
| 29 | + # Create a new atom with the given initial value. |
| 30 | + # |
| 31 | + # @param [Object] value The initial value |
| 32 | + # @param [Hash] opts The options used to configure the atom |
| 33 | + # @option opts [Proc] :validator (nil) Optional proc used to validate new |
| 34 | + # values. It must accept one and only one argument which will be the |
| 35 | + # intended new value. The validator will return true if the new value |
| 36 | + # is acceptable else return false (preferrably) or raise an exception. |
| 37 | + # |
| 38 | + # @!macro deref_options |
| 39 | + # |
| 40 | + # @raise [ArgumentError] if the validator is not a `Proc` (when given) |
| 41 | + def initialize(value, opts = {}) |
| 42 | + super() |
| 43 | + synchronize{ ns_initialize(value, opts) } |
| 44 | + end |
| 45 | + |
| 46 | + # The current value of the atom. |
| 47 | + # |
| 48 | + # @return [Object] The current value. |
| 49 | + def value |
| 50 | + apply_deref_options(@value.value) |
| 51 | + end |
| 52 | + alias_method :deref, :value |
| 53 | + |
| 54 | + # Atomically swaps the value of atom using the given block. The current |
| 55 | + # value will be passed to the block, as will any arguments passed as |
| 56 | + # arguments to the function. The new value will be validated against the |
| 57 | + # (optional) validator proc given at construction. If validation fails the |
| 58 | + # value will not be changed. |
| 59 | + # |
| 60 | + # Internally, {#swap} reads the current value, applies the block to it, and |
| 61 | + # attempts to compare-and-set it in. Since another thread may have changed |
| 62 | + # the value in the intervening time, it may have to retry, and does so in a |
| 63 | + # spin loop. The net effect is that the value will always be the result of |
| 64 | + # the application of the supplied block to a current value, atomically. |
| 65 | + # However, because the block might be called multiple times, it must be free |
| 66 | + # of side effects. |
| 67 | + # |
| 68 | + # @note The given block may be called multiple times, and thus should be free |
| 69 | + # of side effects. |
| 70 | + # |
| 71 | + # @param [Object] args Zero or more arguments passed to the block. |
| 72 | + # |
| 73 | + # @yield [value, args] Calculates a new value for the atom based on the |
| 74 | + # current value and any supplied agruments. |
| 75 | + # @yieldparam value [Object] The current value of the atom. |
| 76 | + # @yieldparam args [Object] All arguments passed to the function, in order. |
| 77 | + # @yieldreturn [Object] The intended new value of the atom. |
| 78 | + # |
| 79 | + # @return [Object] The final value of the atom after all operations and |
| 80 | + # validations are complete. |
| 81 | + # |
| 82 | + # @raise [ArgumentError] When no block is given. |
| 83 | + def swap(*args) |
| 84 | + raise ArgumentError.new('no block given') unless block_given? |
| 85 | + |
| 86 | + begin |
| 87 | + loop do |
| 88 | + old_value = @value.value |
| 89 | + new_value = yield(old_value, *args) |
| 90 | + return old_value unless @validator.call(new_value) |
| 91 | + return new_value if compare_and_set!(old_value, new_value) |
| 92 | + end |
| 93 | + rescue |
| 94 | + return @value.value |
| 95 | + end |
| 96 | + end |
| 97 | + |
| 98 | + # @!macro [attach] atom_compare_and_set |
| 99 | + # Atomically sets the value of atom to the new value if and only if the |
| 100 | + # current value of the atom is identical to the old value and the new |
| 101 | + # value successfully validates against the (optional) validator given |
| 102 | + # at construction. |
| 103 | + # |
| 104 | + # @param [Object] old_value The expected current value. |
| 105 | + # @param [Object] new_value The intended new value. |
| 106 | + # |
| 107 | + # @return [Boolean] True if the value is changed else false. |
| 108 | + def compare_and_set(old_value, new_value) |
| 109 | + compare_and_set!(old_value, new_value) |
| 110 | + rescue |
| 111 | + false |
| 112 | + end |
| 113 | + |
| 114 | + private |
| 115 | + |
| 116 | + # @!macro atom_initialize |
| 117 | + # @!visibility private |
| 118 | + def ns_initialize(value, opts) |
| 119 | + @validator = opts.fetch(:validator, ->(v){ true }) |
| 120 | + raise ArgumentError.new('validator must be a proc') unless @validator.is_a? Proc |
| 121 | + @value = Concurrent::AtomicReference.new(value) |
| 122 | + ns_set_deref_options(opts) |
| 123 | + end |
| 124 | + |
| 125 | + # @!macro atom_compare_and_set |
| 126 | + # @raise [Exception] if the validator proc raises an exception |
| 127 | + # @!visibility private |
| 128 | + def compare_and_set!(old_value, new_value) |
| 129 | + if @validator.call(new_value) # may raise exception |
| 130 | + @value.compare_and_set(old_value, new_value) |
| 131 | + else |
| 132 | + false |
| 133 | + end |
| 134 | + end |
| 135 | + end |
| 136 | +end |
0 commit comments