concurrent-ruby 1.1.5

data/lib/concurrent/mutable_struct.rb

@@ -0,0 +1,229 @@
+require 'concurrent/synchronization/abstract_struct'
+require 'concurrent/synchronization'
+
+module Concurrent
+
+  # An thread-safe variation of Ruby's standard `Struct`. Values can be set at
+  # construction or safely changed at any time during the object's lifecycle.
+  #
+  # @see http://ruby-doc.org/core-2.2.0/Struct.html Ruby standard library `Struct`
+  module MutableStruct
+    include Synchronization::AbstractStruct
+
+    # @!macro struct_new
+    #
+    #   Factory for creating new struct classes.
+    #
+    #   ```
+    #   new([class_name] [, member_name]+>) -> StructClass click to toggle source
+    #   new([class_name] [, member_name]+>) {|StructClass| block } -> StructClass
+    #   new(value, ...) -> obj
+    #   StructClass[value, ...] -> obj
+    #   ```
+    #
+    #   The first two forms are used to create a new struct subclass `class_name`
+    #   that can contain a value for each   member_name . This subclass can be
+    #   used to create instances of the structure like any other  Class .
+    #
+    #   If the `class_name` is omitted an anonymous struct class will be created.
+    #   Otherwise, the name of this struct will appear as a constant in the struct class,
+    #   so it must be unique for all structs under this base class and must start with a
+    #   capital letter. Assigning a struct class to a constant also gives the class
+    #   the name of the constant.
+    #
+    #   If a block is given it will be evaluated in the context of `StructClass`, passing
+    #   the created class as a parameter. This is the recommended way to customize a struct.
+    #   Subclassing an anonymous struct creates an extra anonymous class that will never be used.
+    #
+    #   The last two forms create a new instance of a struct subclass. The number of value
+    #   parameters must be less than or equal to the number of attributes defined for the
+    #   struct. Unset parameters default to nil. Passing more parameters than number of attributes
+    #   will raise an `ArgumentError`.
+    #
+    #   @see http://ruby-doc.org/core-2.2.0/Struct.html#method-c-new Ruby standard library `Struct#new`
+
+    # @!macro struct_values
+    #
+    #   Returns the values for this struct as an Array.
+    #
+    #   @return [Array] the values for this struct
+    #
+    def values
+      synchronize { ns_values }
+    end
+    alias_method :to_a, :values
+
+    # @!macro struct_values_at
+    #
+    #   Returns the struct member values for each selector as an Array.
+    #
+    #   A selector may be either an Integer offset or a Range of offsets (as in `Array#values_at`).
+    #
+    #   @param [Fixnum, Range] indexes the index(es) from which to obatin the values (in order)
+    def values_at(*indexes)
+      synchronize { ns_values_at(indexes) }
+    end
+
+    # @!macro struct_inspect
+    #
+    #   Describe the contents of this struct in a string.
+    #
+    #   @return [String] the contents of this struct in a string
+    def inspect
+      synchronize { ns_inspect }
+    end
+    alias_method :to_s, :inspect
+
+    # @!macro struct_merge
+    #
+    #   Returns a new struct containing the contents of `other` and the contents
+    #   of `self`. If no block is specified, the value for entries with duplicate
+    #   keys will be that of `other`. Otherwise the value for each duplicate key
+    #   is determined by calling the block with the key, its value in `self` and
+    #   its value in `other`.
+    #
+    #   @param [Hash] other the hash from which to set the new values
+    #   @yield an options block for resolving duplicate keys
+    #   @yieldparam [String, Symbol] member the name of the member which is duplicated
+    #   @yieldparam [Object] selfvalue the value of the member in `self`
+    #   @yieldparam [Object] othervalue the value of the member in `other`
+    #
+    #   @return [Synchronization::AbstractStruct] a new struct with the new values
+    #
+    #   @raise [ArgumentError] of given a member that is not defined in the struct
+    def merge(other, &block)
+      synchronize { ns_merge(other, &block) }
+    end
+
+    # @!macro struct_to_h
+    #
+    #   Returns a hash containing the names and values for the struct’s members.
+    #
+    #   @return [Hash] the names and values for the struct’s members
+    def to_h
+      synchronize { ns_to_h }
+    end
+
+    # @!macro struct_get
+    #
+    #   Attribute Reference
+    #
+    #   @param [Symbol, String, Integer] member the string or symbol name of the member
+    #     for which to obtain the value or the member's index
+    #
+    #   @return [Object] the value of the given struct member or the member at the given index.
+    #
+    #   @raise [NameError] if the member does not exist
+    #   @raise [IndexError] if the index is out of range.
+    def [](member)
+      synchronize { ns_get(member) }
+    end
+
+    # @!macro struct_equality
+    #
+    #   Equality
+    #
+    #   @return [Boolean] true if other has the same struct subclass and has
+    #     equal member values (according to `Object#==`)
+    def ==(other)
+      synchronize { ns_equality(other) }
+    end
+
+    # @!macro struct_each
+    #
+    #   Yields the value of each struct member in order. If no block is given
+    #   an enumerator is returned.
+    #
+    #   @yield the operation to be performed on each struct member
+    #   @yieldparam [Object] value each struct value (in order)
+    def each(&block)
+      return enum_for(:each) unless block_given?
+      synchronize { ns_each(&block) }
+    end
+
+    # @!macro struct_each_pair
+    #
+    #   Yields the name and value of each struct member in order. If no block is
+    #   given an enumerator is returned.
+    #
+    #   @yield the operation to be performed on each struct member/value pair
+    #   @yieldparam [Object] member each struct member (in order)
+    #   @yieldparam [Object] value each struct value (in order)
+    def each_pair(&block)
+      return enum_for(:each_pair) unless block_given?
+      synchronize { ns_each_pair(&block) }
+    end
+
+    # @!macro struct_select
+    #
+    #   Yields each member value from the struct to the block and returns an Array
+    #   containing the member values from the struct for which the given block
+    #   returns a true value (equivalent to `Enumerable#select`).
+    #
+    #   @yield the operation to be performed on each struct member
+    #   @yieldparam [Object] value each struct value (in order)
+    #
+    #   @return [Array] an array containing each value for which the block returns true
+    def select(&block)
+      return enum_for(:select) unless block_given?
+      synchronize { ns_select(&block) }
+    end
+
+    # @!macro struct_set
+    #
+    #   Attribute Assignment
+    #
+    #   Sets the value of the given struct member or the member at the given index.
+    #
+    #   @param [Symbol, String, Integer] member the string or symbol name of the member
+    #     for which to obtain the value or the member's index
+    #
+    #   @return [Object] the value of the given struct member or the member at the given index.
+    #
+    #   @raise [NameError] if the name does not exist
+    #   @raise [IndexError] if the index is out of range.
+    def []=(member, value)
+      if member.is_a? Integer
+        length = synchronize { @values.length }
+        if member >= length
+          raise IndexError.new("offset #{member} too large for struct(size:#{length})")
+        end
+        synchronize { @values[member] = value }
+      else
+        send("#{member}=", value)
+      end
+    rescue NoMethodError
+      raise NameError.new("no member '#{member}' in struct")
+    end
+
+    # @!macro struct_new
+    def self.new(*args, &block)
+      clazz_name = nil
+      if args.length == 0
+        raise ArgumentError.new('wrong number of arguments (0 for 1+)')
+      elsif args.length > 0 && args.first.is_a?(String)
+        clazz_name = args.shift
+      end
+      FACTORY.define_struct(clazz_name, args, &block)
+    end
+
+    FACTORY = Class.new(Synchronization::LockableObject) do
+      def define_struct(name, members, &block)
+        synchronize do
+          clazz = Synchronization::AbstractStruct.define_struct_class(MutableStruct, Synchronization::LockableObject, name, members, &block)
+          members.each_with_index do |member, index|
+            clazz.send :remove_method, member
+            clazz.send(:define_method, member) do
+              synchronize { @values[index] }
+            end
+            clazz.send(:define_method, "#{member}=") do |value|
+              synchronize { @values[index] = value }
+            end
+          end
+          clazz
+        end
+      end
+    end.new
+    private_constant :FACTORY
+  end
+end

data/lib/concurrent/mvar.rb

@@ -0,0 +1,242 @@
+require 'concurrent/concern/dereferenceable'
+require 'concurrent/synchronization'
+
+module Concurrent
+
+  # An `MVar` is a synchronized single element container. They are empty or
+  # contain one item. Taking a value from an empty `MVar` blocks, as does
+  # putting a value into a full one. You can either think of them as blocking
+  # queue of length one, or a special kind of mutable variable.
+  #
+  # On top of the fundamental `#put` and `#take` operations, we also provide a
+  # `#mutate` that is atomic with respect to operations on the same instance.
+  # These operations all support timeouts.
+  #
+  # We also support non-blocking operations `#try_put!` and `#try_take!`, a
+  # `#set!` that ignores existing values, a `#value` that returns the value
+  # without removing it or returns `MVar::EMPTY`, and a `#modify!` that yields
+  # `MVar::EMPTY` if the `MVar` is empty and can be used to set `MVar::EMPTY`.
+  # You shouldn't use these operations in the first instance.
+  #
+  # `MVar` is a [Dereferenceable](Dereferenceable).
+  #
+  # `MVar` is related to M-structures in Id, `MVar` in Haskell and `SyncVar` in Scala.
+  #
+  # Note that unlike the original Haskell paper, our `#take` is blocking. This is how
+  # Haskell and Scala do it today.
+  #
+  # @!macro copy_options
+  #
+  # ## See Also
+  #
+  # 1. P. Barth, R. Nikhil, and Arvind. [M-Structures: Extending a parallel, non- strict, functional language with state](http://dl.acm.org/citation.cfm?id=652538). In Proceedings of the 5th
+  #    ACM Conference on Functional Programming Languages and Computer Architecture (FPCA), 1991.
+  #
+  # 2. S. Peyton Jones, A. Gordon, and S. Finne. [Concurrent Haskell](http://dl.acm.org/citation.cfm?id=237794).
+  #    In Proceedings of the 23rd Symposium on Principles of Programming Languages
+  #    (PoPL), 1996.
+  class MVar < Synchronization::Object
+    include Concern::Dereferenceable
+    safe_initialization!
+
+    # Unique value that represents that an `MVar` was empty
+    EMPTY = ::Object.new
+
+    # Unique value that represents that an `MVar` timed out before it was able
+    # to produce a value.
+    TIMEOUT = ::Object.new
+
+    # Create a new `MVar`, either empty or with an initial value.
+    #
+    # @param [Hash] opts the options controlling how the future will be processed
+    #
+    # @!macro deref_options
+    def initialize(value = EMPTY, opts = {})
+      @value = value
+      @mutex = Mutex.new
+      @empty_condition = ConditionVariable.new
+      @full_condition = ConditionVariable.new
+      set_deref_options(opts)
+    end
+
+    # Remove the value from an `MVar`, leaving it empty, and blocking if there
+    # isn't a value. A timeout can be set to limit the time spent blocked, in
+    # which case it returns `TIMEOUT` if the time is exceeded.
+    # @return [Object] the value that was taken, or `TIMEOUT`
+    def take(timeout = nil)
+      @mutex.synchronize do
+        wait_for_full(timeout)
+
+        # If we timed out we'll still be empty
+        if unlocked_full?
+          value = @value
+          @value = EMPTY
+          @empty_condition.signal
+          apply_deref_options(value)
+        else
+          TIMEOUT
+        end
+      end
+    end
+
+    # acquires lock on the from an `MVAR`, yields the value to provided block,
+    # and release lock. A timeout can be set to limit the time spent blocked,
+    # in which case it returns `TIMEOUT` if the time is exceeded.
+    # @return [Object] the value returned by the block, or `TIMEOUT`
+    def borrow(timeout = nil)
+      @mutex.synchronize do
+        wait_for_full(timeout)
+
+        # if we timeoud out we'll still be empty
+        if unlocked_full?
+          yield @value
+        else
+          TIMEOUT
+        end
+      end
+    end
+
+    # Put a value into an `MVar`, blocking if there is already a value until
+    # it is empty. A timeout can be set to limit the time spent blocked, in
+    # which case it returns `TIMEOUT` if the time is exceeded.
+    # @return [Object] the value that was put, or `TIMEOUT`
+    def put(value, timeout = nil)
+      @mutex.synchronize do
+        wait_for_empty(timeout)
+
+        # If we timed out we won't be empty
+        if unlocked_empty?
+          @value = value
+          @full_condition.signal
+          apply_deref_options(value)
+        else
+          TIMEOUT
+        end
+      end
+    end
+
+    # Atomically `take`, yield the value to a block for transformation, and then
+    # `put` the transformed value. Returns the transformed value. A timeout can
+    # be set to limit the time spent blocked, in which case it returns `TIMEOUT`
+    # if the time is exceeded.
+    # @return [Object] the transformed value, or `TIMEOUT`
+    def modify(timeout = nil)
+      raise ArgumentError.new('no block given') unless block_given?
+
+      @mutex.synchronize do
+        wait_for_full(timeout)
+
+        # If we timed out we'll still be empty
+        if unlocked_full?
+          value = @value
+          @value = yield value
+          @full_condition.signal
+          apply_deref_options(value)
+        else
+          TIMEOUT
+        end
+      end
+    end
+
+    # Non-blocking version of `take`, that returns `EMPTY` instead of blocking.
+    def try_take!
+      @mutex.synchronize do
+        if unlocked_full?
+          value = @value
+          @value = EMPTY
+          @empty_condition.signal
+          apply_deref_options(value)
+        else
+          EMPTY
+        end
+      end
+    end
+
+    # Non-blocking version of `put`, that returns whether or not it was successful.
+    def try_put!(value)
+      @mutex.synchronize do
+        if unlocked_empty?
+          @value = value
+          @full_condition.signal
+          true
+        else
+          false
+        end
+      end
+    end
+
+    # Non-blocking version of `put` that will overwrite an existing value.
+    def set!(value)
+      @mutex.synchronize do
+        old_value = @value
+        @value = value
+        @full_condition.signal
+        apply_deref_options(old_value)
+      end
+    end
+
+    # Non-blocking version of `modify` that will yield with `EMPTY` if there is no value yet.
+    def modify!
+      raise ArgumentError.new('no block given') unless block_given?
+
+      @mutex.synchronize do
+        value = @value
+        @value = yield value
+        if unlocked_empty?
+          @empty_condition.signal
+        else
+          @full_condition.signal
+        end
+        apply_deref_options(value)
+      end
+    end
+
+    # Returns if the `MVar` is currently empty.
+    def empty?
+      @mutex.synchronize { @value == EMPTY }
+    end
+
+    # Returns if the `MVar` currently contains a value.
+    def full?
+      !empty?
+    end
+
+    protected
+
+    def synchronize(&block)
+      @mutex.synchronize(&block)
+    end
+
+    private
+
+    def unlocked_empty?
+      @value == EMPTY
+    end
+
+    def unlocked_full?
+      ! unlocked_empty?
+    end
+
+    def wait_for_full(timeout)
+      wait_while(@full_condition, timeout) { unlocked_empty? }
+    end
+
+    def wait_for_empty(timeout)
+      wait_while(@empty_condition, timeout) { unlocked_full? }
+    end
+
+    def wait_while(condition, timeout)
+      if timeout.nil?
+        while yield
+          condition.wait(@mutex)
+        end
+      else
+        stop = Concurrent.monotonic_time + timeout
+        while yield && timeout > 0.0
+          condition.wait(@mutex, timeout)
+          timeout = stop - Concurrent.monotonic_time
+        end
+      end
+    end
+  end
+end