functional-ruby 1.1.0 → 1.2.0

data/lib/functional/abstract_struct.rb

@@ -1,4 +1,5 @@
-require_relative 'protocol'
+require 'functional/protocol'
+require 'functional/synchronization'
 
 Functional::SpecifyProtocol(:Struct) do
   instance_method :fields
@@ -11,8 +12,7 @@ end
 module Functional
 
   # An abstract base class for immutable struct classes.
-  #
-  # @since 1.0.0
+  # @!visibility private
   module AbstractStruct
 
     # @return [Array] the values of all record fields in order, frozen
@@ -94,7 +94,7 @@ module Functional
     # Set the internal data hash to a copy of the given hash and freeze it.
     # @param [Hash] data the data hash
     #
-    # @!visibility private 
+    # @!visibility private
     def set_data_hash(data)
       @data = data.dup.freeze
     end
@@ -102,7 +102,7 @@ module Functional
     # Set the internal values array to a copy of the given array and freeze it.
     # @param [Array] values the values array
     #
-    # @!visibility private 
+    # @!visibility private
     def set_values_array(values)
       @values = values.dup.freeze
     end
@@ -117,9 +117,9 @@ module Functional
     # @return [Functional::AbstractStruct, Array] the new class and the
     #   (possibly) updated fields array
     #
-    # @!visibility private 
+    # @!visibility private
     def self.define_class(parent, datatype, fields)
-      struct = Class.new{ include AbstractStruct }
+      struct = Class.new(Functional::Synchronization::Object){ include AbstractStruct }
       if fields.first.is_a? String
         parent.const_set(fields.first, struct)
         fields = fields[1, fields.length-1]
@@ -157,7 +157,7 @@ module Functional
       attr_writer :datatype
 
       fields = [].freeze
-      datatype = :struct 
+      datatype = :struct
     end
   end
 end

data/lib/functional/delay.rb

@@ -1,26 +1,25 @@
-require 'thread'
+require 'functional/synchronization'
 
 module Functional
 
-  # Lazy evaluation of a block yielding an immutable result. Useful for expensive
-  # operations that may never be needed.
-  # 
+  # Lazy evaluation of a block yielding an immutable result. Useful for
+  # expensive operations that may never be needed.
+  #
   # When a `Delay` is created its state is set to `pending`. The value and
   # reason are both `nil`. The first time the `#value` method is called the
   # enclosed opration will be run and the calling thread will block. Other
   # threads attempting to call `#value` will block as well. Once the operation
   # is complete the *value* will be set to the result of the operation or the
   # *reason* will be set to the raised exception, as appropriate. All threads
-  # blocked on `#value` will return. Subsequent calls to `#value` will immediately
-  # return the cached value. The operation will only be run once. This means that
-  # any side effects created by the operation will only happen once as well.
-  #
-  # @see http://clojuredocs.org/clojure_core/clojure.core/delay Clojure delay
-  #
-  # @since 1.0.0
+  # blocked on `#value` will return. Subsequent calls to `#value` will
+  # immediately return the cached value. The operation will only be run once.
+  # This means that any side effects created by the operation will only happen
+  # once as well.
   #
   # @!macro thread_safe_immutable_object
-  class Delay
+  #
+  # @see http://clojuredocs.org/clojure_core/clojure.core/delay Clojure delay
+  class Delay < Synchronization::Object
 
     # Create a new `Delay` in the `:pending` state.
     #
@@ -29,79 +28,72 @@ module Functional
     # @raise [ArgumentError] if no block is given
     def initialize(&block)
       raise ArgumentError.new('no block given') unless block_given?
-      @mutex = Mutex.new
-      @state = :pending
-      @task  = block
+      super
+      synchronize do
+        @state = :pending
+        @task  = block
+      end
     end
 
     # Current state of block processing.
     #
     # @return [Symbol] the current state of block processing
     def state
-      @mutex.lock
-      @state
-    ensure
-      @mutex.unlock
+      synchronize{ @state }
     end
 
     # The exception raised when processing the block. Returns `nil` if the
     # operation is still `:pending` or has been `:fulfilled`.
     #
-    # @return [StandardError] the exception raised when processing the block else nil
+    # @return [StandardError] the exception raised when processing the block
+    #   else nil.
     def reason
-      @mutex.lock
-      @reason
-    ensure
-      @mutex.unlock
+      synchronize{ @reason }
     end
 
     # Return the (possibly memoized) value of the delayed operation.
-    # 
+    #
     # If the state is `:pending` then the calling thread will block while the
     # operation is performed. All other threads simultaneously calling `#value`
     # will block as well. Once the operation is complete (either `:fulfilled` or
     # `:rejected`) all waiting threads will unblock and the new value will be
     # returned.
     #
-    # If the state is not `:pending` when `#value` is called the (possibly memoized)
-    # value will be returned without blocking and without performing the operation
-    # again.
+    # If the state is not `:pending` when `#value` is called the (possibly
+    # memoized) value will be returned without blocking and without performing
+    # the operation again.
     #
     # @return [Object] the (possibly memoized) result of the block operation
     def value
-      @mutex.lock
-      execute_task_once
-      @value
-    ensure
-      @mutex.unlock
+      synchronize{ execute_task_once }
     end
 
     # Has the delay been fulfilled?
     # @return [Boolean]
     def fulfilled?
-      state == :fulfilled
+      synchronize{ @state == :fulfilled }
     end
     alias_method :value?, :fulfilled?
 
     # Has the delay been rejected?
     # @return [Boolean]
     def rejected?
-      state == :rejected
+      synchronize{ @state == :rejected }
     end
     alias_method :reason?, :rejected?
 
     # Is delay completion still pending?
     # @return [Boolean]
     def pending?
-      state == :pending
+      synchronize{ @state == :pending }
     end
 
     protected
 
     # @!visibility private
     #
-    # Execute the enclosed task then cache and return the result if
-    # the current state is pending. Otherwise, return the cached result.
+    # Execute the enclosed task then cache and return the result if the current
+    # state is pending. Otherwise, return the cached result.
     #
     # @return [Object] the result of the block operation
     def execute_task_once
@@ -114,6 +106,7 @@ module Functional
           @state  = :rejected
         end
       end
+      @value
     end
   end
 end

data/lib/functional/either.rb

@@ -1,5 +1,6 @@
-require_relative 'abstract_struct'
-require_relative 'protocol'
+require 'functional/abstract_struct'
+require 'functional/protocol'
+require 'functional/synchronization'
 
 Functional::SpecifyProtocol(:Either) do
   instance_method :left, 0
@@ -10,45 +11,47 @@ end
 
 module Functional
 
-  # The `Either` type represents a value of one of two possible types (a disjoint union).
-  # It is an immutable structure that contains one and only one value. That value can
-  # be stored in one of two virtual position, `left` or `right`. The position provides
-  # context for the encapsulated data.
+  # The `Either` type represents a value of one of two possible types (a
+  # disjoint union). It is an immutable structure that contains one and only one
+  # value. That value can be stored in one of two virtual position, `left` or
+  # `right`. The position provides context for the encapsulated data.
   #
-  # One of the main uses of `Either` is as a return value that can indicate either
-  # success or failure. Object oriented programs generally report errors through
-  # either state or exception handling, neither of which work well in functional
-  # programming. In the former case, a method is called on an object and when an
-  # error occurs the state of the object is updated to reflect the error. This does
-  # not translate well to functional programming because they eschew state and
-  # mutable objects. In the latter, an exception handling block provides branching
-  # logic when an exception is thrown. This does not translate well to functional
-  # programming because it eschews side effects like structured exception handling
-  # (and structured exception handling tends to be very expensive). `Either` provides
-  # a powerful and easy-to-use alternative.
+  # One of the main uses of `Either` is as a return value that can indicate
+  # either success or failure. Object oriented programs generally report errors
+  # through either state or exception handling, neither of which work well in
+  # functional programming. In the former case, a method is called on an object
+  # and when an error occurs the state of the object is updated to reflect the
+  # error. This does not translate well to functional programming because they
+  # eschew state and mutable objects. In the latter, an exception handling block
+  # provides branching logic when an exception is thrown. This does not
+  # translate well to functional programming because it eschews side effects
+  # like structured exception handling (and structured exception handling tends
+  # to be very expensive). `Either` provides a powerful and easy-to-use
+  # alternative.
   #
-  # A function that may generate an error can choose to return an immutable `Either`
-  # object in which the position of the value (left or right) indicates the nature
-  # of the data. By convention, a `left` value indicates an error and a `right` value
-  # indicates success. This leaves the caller with no ambiguity regarding success or
-  # failure, requires no persistent state, and does not require expensive exception
-  # handling facilities.
+  # A function that may generate an error can choose to return an immutable
+  # `Either` object in which the position of the value (left or right) indicates
+  # the nature of the data. By convention, a `left` value indicates an error and
+  # a `right` value indicates success. This leaves the caller with no ambiguity
+  # regarding success or failure, requires no persistent state, and does not
+  # require expensive exception handling facilities.
   #
-  # `Either` provides several aliases and convenience functions to facilitate these
-  # failure/success conventions. The `left` and `right` functions, including their
-  # derivatives, are mirrored by `reason` and `value`. Failure is indicated by the
-  # presence of a `reason` and success is indicated by the presence of a `value`.
-  # When an operation has failed the either is in a `rejected` state, and when an
-  # operation has successed the either is in a `fulfilled` state. A common convention
-  # is to use a Ruby `Exception` as the `reason`. The factory method `error` facilitates
-  # this. The semantics and conventions of `reason`, `value`, and their derivatives
-  # follow the conventions of the Concurrent Ruby gem.
+  # `Either` provides several aliases and convenience functions to facilitate
+  # these failure/success conventions. The `left` and `right` functions,
+  # including their derivatives, are mirrored by `reason` and `value`. Failure
+  # is indicated by the presence of a `reason` and success is indicated by the
+  # presence of a `value`. When an operation has failed the either is in a
+  # `rejected` state, and when an operation has successed the either is in a
+  # `fulfilled` state. A common convention is to use a Ruby `Exception` as the
+  # `reason`. The factory method `error` facilitates this. The semantics and
+  # conventions of `reason`, `value`, and their derivatives follow the
+  # conventions of the Concurrent Ruby gem.
   #
-  # The `left`/`right` and `reason`/`value` methods are not mutually exclusive. They
-  # can be commingled and still result in functionally correct code. This practice
-  # should be avoided, however. Consistent use of either `left`/`right` or
-  # `reason`/`value` against each `Either` instance will result in more expressive,
-  # intent-revealing code.
+  # The `left`/`right` and `reason`/`value` methods are not mutually exclusive.
+  # They can be commingled and still result in functionally correct code. This
+  # practice should be avoided, however. Consistent use of either `left`/`right`
+  # or `reason`/`value` against each `Either` instance will result in more
+  # expressive, intent-revealing code.
   #
   # @example
   #
@@ -77,16 +80,14 @@ module Functional
   # @see https://hackage.haskell.org/package/base-4.2.0.1/docs/Data-Either.html Haskell Data.Either
   # @see http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Obligation.html Concurrent Ruby
   #
-  # @since 1.0.0
-  #
   # @!macro thread_safe_immutable_object
-  class Either
+  class Either < Synchronization::Object
     include AbstractStruct
 
     self.datatype = :either
     self.fields = [:left, :right].freeze
 
-    # @!visibility private 
+    # @!visibility private
     NO_VALUE = Object.new.freeze
 
     private_class_method :new
@@ -119,7 +120,7 @@ module Functional
       # given error class will be used.
       #
       # @example
-      # 
+      #
       #   either = Functional::Either.error("You're a bad monkey, Mojo Jojo")
       #   either.fulfilled? #=> false
       #   either.rejected?  #=> true
@@ -137,7 +138,7 @@ module Functional
     end
 
     # Projects this either as a left.
-    # 
+    #
     # @return [Object] The left value or `nil` when `right`.
     def left
       left? ? to_h[:left] : nil
@@ -145,7 +146,7 @@ module Functional
     alias_method :reason, :left
 
     # Projects this either as a right.
-    # 
+    #
     # @return [Object] The right value or `nil` when `left`.
     def right
       right? ? to_h[:right] : nil
@@ -213,12 +214,14 @@ module Functional
     # @param [Object] value the value of this either
     # @param [Boolean] is_left is this a left either or right?
     #
-    # @!visibility private 
+    # @!visibility private
     def initialize(value, is_left)
+      super
       @is_left = is_left
       hsh = is_left ? {left: value, right: nil} : {left: nil, right: value}
       set_data_hash(hsh)
       set_values_array(hsh.values)
+      ensure_ivar_visibility!
     end
   end
 end

data/lib/functional/final_struct.rb

@@ -1,5 +1,5 @@
-require_relative 'final_var'
-require 'thread'
+require 'functional/final_var'
+require 'functional/synchronization'
 
 module Functional
 
@@ -41,14 +41,11 @@ module Functional
   #
   #   name.first = 'Sam'   #=> Functional::FinalityError: final accessor 'first' has already been set
   #
-  # @since 1.1.0
-  #
-  # @see Functional::FinalVar
   # @see http://www.ruby-doc.org/stdlib-2.1.2/libdoc/ostruct/rdoc/OpenStruct.html
   # @see http://en.wikipedia.org/wiki/Final_(Java) Java `final` keyword
   #
   # @!macro thread_safe_final_object
-  class FinalStruct
+  class FinalStruct < Synchronization::Object
 
     # Creates a new `FinalStruct` object. By default, the resulting `FinalStruct`
     # object will have no attributes. The optional hash, if given, will generate
@@ -57,10 +54,12 @@ module Functional
     # @param [Hash] attributes the field/value pairs to set on creation
     def initialize(attributes = {})
       raise ArgumentError.new('attributes must be given as a hash or not at all') unless attributes.respond_to?(:to_h)
-      @mutex = Mutex.new
-      @attribute_hash = {}
-      attributes.to_h.each_pair do |field, value|
-        set_attribute(field, value)
+      super
+      synchronize do
+        @attribute_hash = {}
+        attributes.to_h.each_pair do |field, value|
+          ns_set_attribute(field, value)
+        end
       end
     end
 
@@ -71,9 +70,7 @@ module Functional
     #   @param [Symbol] field the field to retrieve the value for
     #   @return [Object] the value of the field is set else nil
     def get(field)
-      @mutex.synchronize {
-        get_attribute(field)
-      }
+      synchronize { ns_get_attribute(field) }
     end
     alias_method :[], :get
 
@@ -91,13 +88,13 @@ module Functional
     #
     # @raise [Functional::FinalityError] if the given field has already been set
     def set(field, value)
-      @mutex.synchronize {
-        if attribute_has_been_set?(field)
+      synchronize do
+        if ns_attribute_has_been_set?(field)
           raise FinalityError.new("final accessor '#{field}' has already been set")
         else
-          set_attribute(field, value)
+          ns_set_attribute(field, value)
         end
-      }
+      end
     end
     alias_method :[]=, :set
 
@@ -109,9 +106,7 @@ module Functional
     #   @param [Symbol] field the field to get the value for
     #   @return [Boolean] true if the field has been set else false
     def set?(field)
-      @mutex.synchronize {
-        attribute_has_been_set?(field)
-      }
+      synchronize { ns_attribute_has_been_set?(field) }
     end
 
     # Get the current value of the given field if already set else set the value of
@@ -121,9 +116,7 @@ module Functional
     # @param [Object] value the value to set the field to when not previously set
     # @return [Object] the final value of the given field
     def get_or_set(field, value)
-      @mutex.synchronize {
-        attribute_has_been_set?(field) ? get_attribute(field) : set_attribute(field, value)
-      }
+      synchronize { ns_attribute_has_been_set?(field) ? ns_get_attribute(field) : ns_set_attribute(field, value) }
     end
 
     # Get the current value of the given field if already set else return the given
@@ -133,9 +126,7 @@ module Functional
     # @param [Object] default the value to return if the field has not been set
     # @return [Object] the value of the given field else the given default value
     def fetch(field, default)
-      @mutex.synchronize {
-        attribute_has_been_set?(field) ? get_attribute(field) : default
-      }
+      synchronize { ns_attribute_has_been_set?(field) ? ns_get_attribute(field) : default }
     end
 
     # Calls the block once for each attribute, passing the key/value pair as parameters.
@@ -147,11 +138,11 @@ module Functional
     # @return [Enumerable] when no block is given
     def each_pair
       return enum_for(:each_pair) unless block_given?
-      @mutex.synchronize {
+      synchronize do
         @attribute_hash.each do |field, value|
           yield(field, value)
         end
-      }
+      end
     end
 
     # Converts the `FinalStruct` to a `Hash` with keys representing each attribute
@@ -159,9 +150,7 @@ module Functional
     # 
     # @return [Hash] a `Hash` representing this struct
     def to_h
-      @mutex.synchronize {
-        @attribute_hash.dup
-      }
+      synchronize { @attribute_hash.dup }
     end
 
     # Compares this object and other for equality. A `FinalStruct` is `eql?` to
@@ -190,19 +179,19 @@ module Functional
 
     # @!macro final_struct_get_method
     # @!visibility private
-    def get_attribute(field)
+    def ns_get_attribute(field)
       @attribute_hash[field.to_sym]
     end
 
     # @!macro final_struct_set_method
     # @!visibility private
-    def set_attribute(field, value)
+    def ns_set_attribute(field, value)
       @attribute_hash[field.to_sym] = value
     end
 
     # @!macro final_struct_set_predicate
     # @!visibility private
-    def attribute_has_been_set?(field)
+    def ns_attribute_has_been_set?(field)
       @attribute_hash.has_key?(field.to_sym)
     end