concurrent-ruby 0.8.0 → 0.9.0.pre2

data/lib/concurrent/concern/deprecation.rb

@@ -0,0 +1,27 @@
+require 'concurrent/concern/logging'
+
+module Concurrent
+  module Concern
+
+    # @!visibility private
+    # @!macro internal_implementation_note
+    module Deprecation
+      # TODO require additional parameter: a version. Display when it'll be removed based on that. Error if not removed.
+      include Concern::Logging
+
+      def deprecated(message, strip = 2)
+        caller_line = caller(strip).first
+        klass       = if Class === self
+                        self
+                      else
+                        self.class
+                      end
+        log WARN, klass.to_s, format("[DEPRECATED] %s\ncalled on: %s", message, caller_line)
+      end
+
+      def deprecated_method(old_name, new_name)
+        deprecated "`#{old_name}` is deprecated and it'll removed in next release, use `#{new_name}` instead", 3
+      end
+    end
+  end
+end

data/lib/concurrent/concern/dereferenceable.rb

@@ -0,0 +1,88 @@
+module Concurrent
+  module Concern
+
+    # 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 "primitive" data type.
+    # Most classes in this library that expose a `#value` getter method do so using the
+    # `Dereferenceable` mixin module.
+    #
+    # @!macro copy_options
+    module Dereferenceable
+
+      # Return the value this object represents after applying the options specified
+      # by the `#set_deref_options` method.
+      #
+      # @return [Object] the current value of the object
+      def value
+        mutex.synchronize { apply_deref_options(@value) }
+      end
+      alias_method :deref, :value
+
+      protected
+
+      # Set the internal value of this object
+      #
+      # @param [Object] value the new value
+      def value=(value)
+        mutex.synchronize{ @value = value }
+      end
+
+      # A mutex lock used for synchronizing thread-safe operations. Methods defined
+      # by `Dereferenceable` are synchronized using the `Mutex` returned from this
+      # method. Operations performed by the including class that operate on the
+      # `@value` instance variable should be locked with this `Mutex`.
+      #
+      # @return [Mutex] the synchronization object
+      def mutex
+        @mutex
+      end
+
+      # Initializes the internal `Mutex`.
+      #
+      # @note This method *must* be called from within the constructor of the including class.
+      #
+      # @see #mutex
+      def init_mutex(mutex = Mutex.new)
+        @mutex = mutex
+      end
+
+      # @!macro [attach] dereferenceable_set_deref_options
+      #   Set the options which define the operations #value performs before
+      #   returning data to the caller (dereferencing).
+      #  
+      #   @note Most classes that include this module will call `#set_deref_options`
+      #   from within the constructor, thus allowing these options to be set at
+      #   object creation.
+      #  
+      #   @param [Hash] opts the options defining dereference behavior.
+      #   @option opts [String] :dup_on_deref (false) call `#dup` before returning the data
+      #   @option opts [String] :freeze_on_deref (false) call `#freeze` before returning the data
+      #   @option opts [String] :copy_on_deref (nil) call the given `Proc` passing
+      #     the internal value and returning the value returned from the proc
+      def set_deref_options(opts = {})
+        mutex.synchronize{ ns_set_deref_options(opts) }
+      end
+
+      # @!macro dereferenceable_set_deref_options
+      # @!visibility private
+      def ns_set_deref_options(opts)
+        @dup_on_deref = opts[:dup_on_deref] || opts[:dup]
+        @freeze_on_deref = opts[:freeze_on_deref] || opts[:freeze]
+        @copy_on_deref = opts[:copy_on_deref] || opts[:copy]
+        @do_nothing_on_deref = !(@dup_on_deref || @freeze_on_deref || @copy_on_deref)
+        nil
+      end
+
+      # @!visibility private
+      def apply_deref_options(value)
+        return nil if value.nil?
+        return value if @do_nothing_on_deref
+        value = @copy_on_deref.call(value) if @copy_on_deref
+        value = value.dup if @dup_on_deref
+        value = value.freeze if @freeze_on_deref
+        value
+      end
+    end
+  end
+end

data/lib/concurrent/concern/logging.rb

@@ -0,0 +1,25 @@
+require 'logger'
+
+module Concurrent
+  module Concern
+
+    # Include where logging is needed
+    #
+    # @!visibility private
+    module Logging
+      include Logger::Severity
+
+      # Logs through {Configuration#logger}, it can be overridden by setting @logger
+      # @param [Integer] level one of Logger::Severity constants
+      # @param [String] progname e.g. a path of an Actor
+      # @param [String, nil] message when nil block is used to generate the message
+      # @yieldreturn [String] a message
+      def log(level, progname, message = nil, &block)
+        (@logger || Concurrent.global_logger).call level, progname, message, &block
+      rescue => error
+        $stderr.puts "`Concurrent.configuration.logger` failed to log #{[level, progname, message, block]}\n" +
+          "#{error.message} (#{error.class})\n#{error.backtrace.join "\n"}"
+      end
+    end
+  end
+end

data/lib/concurrent/concern/obligation.rb

@@ -0,0 +1,228 @@
+require 'thread'
+require 'timeout'
+
+require 'concurrent/atomic/event'
+require 'concurrent/concern/dereferenceable'
+require 'concurrent/concern/deprecation'
+
+module Concurrent
+  module Concern
+
+    module Obligation
+      include Concern::Dereferenceable
+      include Concern::Deprecation
+
+      # Has the obligation been fulfilled?
+      #
+      # @return [Boolean]
+      def fulfilled?
+        state == :fulfilled
+      end
+      alias_method :realized?, :fulfilled?
+
+      # Has the obligation been rejected?
+      #
+      # @return [Boolean]
+      def rejected?
+        state == :rejected
+      end
+
+      # Is obligation completion still pending?
+      #
+      # @return [Boolean]
+      def pending?
+        state == :pending
+      end
+
+      # Is the obligation still unscheduled?
+      #
+      # @return [Boolean]
+      def unscheduled?
+        state == :unscheduled
+      end
+
+      # Has the obligation completed processing?
+      #
+      # @return [Boolean]
+      def complete?
+        [:fulfilled, :rejected].include? state
+      end
+
+      # Has the obligation completed processing?
+      #
+      # @return [Boolean]
+      #
+      # @deprecated
+      def completed?
+        deprecated_method 'completed?', 'complete?'
+        complete?
+      end
+
+      # Is the obligation still awaiting completion of processing?
+      #
+      # @return [Boolean]
+      def incomplete?
+        ! complete?
+      end
+
+      # The current value of the obligation. Will be `nil` while the state is
+      # pending or the operation has been rejected.
+      #
+      # @param [Numeric] timeout the maximum time in seconds to wait.
+      # @return [Object] see Dereferenceable#deref
+      def value(timeout = nil)
+        wait timeout
+        deref
+      end
+
+      # Wait until obligation is complete or the timeout has been reached.
+      #
+      # @param [Numeric] timeout the maximum time in seconds to wait.
+      # @return [Obligation] self
+      def wait(timeout = nil)
+        event.wait(timeout) if timeout != 0 && incomplete?
+        self
+      end
+
+      # Wait until obligation is complete or the timeout is reached. Will re-raise
+      # any exceptions raised during processing (but will not raise an exception
+      # on timeout).
+      #
+      # @param [Numeric] timeout the maximum time in seconds to wait.
+      # @return [Obligation] self
+      # @raise [Exception] raises the reason when rejected
+      def wait!(timeout = nil)
+        wait(timeout).tap { raise self if rejected? }
+      end
+      alias_method :no_error!, :wait!
+
+      # The current value of the obligation. Will be `nil` while the state is
+      # pending or the operation has been rejected. Will re-raise any exceptions
+      # raised during processing (but will not raise an exception on timeout).
+      #
+      # @param [Numeric] timeout the maximum time in seconds to wait.
+      # @return [Object] see Dereferenceable#deref
+      # @raise [Exception] raises the reason when rejected
+      def value!(timeout = nil)
+        wait(timeout)
+        if rejected?
+          raise self
+        else
+          deref
+        end
+      end
+
+      # The current state of the obligation.
+      #
+      # @return [Symbol] the current state
+      def state
+        mutex.synchronize { @state }
+      end
+
+      # If an exception was raised during processing this will return the
+      # exception object. Will return `nil` when the state is pending or if
+      # the obligation has been successfully fulfilled.
+      #
+      # @return [Exception] the exception raised during processing or `nil`
+      def reason
+        mutex.synchronize { @reason }
+      end
+
+      # @example allows Obligation to be risen
+      #   rejected_ivar = Ivar.new.fail
+      #   raise rejected_ivar
+      def exception(*args)
+        raise 'obligation is not rejected' unless rejected?
+        reason.exception(*args)
+      end
+
+      protected
+
+      # @!visibility private
+      def get_arguments_from(opts = {})
+        [*opts.fetch(:args, [])]
+      end
+
+      # @!visibility private
+      def init_obligation(*args)
+        init_mutex(*args)
+        @event = Event.new
+      end
+
+      # @!visibility private
+      def event
+        @event
+      end
+
+      # @!visibility private
+      def set_state(success, value, reason)
+        if success
+          @value = value
+          @state = :fulfilled
+        else
+          @reason = reason
+          @state  = :rejected
+        end
+      end
+
+      # @!visibility private
+      def state=(value)
+        mutex.synchronize { ns_set_state(value) }
+      end
+
+      # Atomic compare and set operation
+      # State is set to `next_state` only if `current state == expected_current`.
+      #
+      # @param [Symbol] next_state
+      # @param [Symbol] expected_current
+      # 
+      # @return [Boolean] true is state is changed, false otherwise
+      #
+      # @!visibility private
+      def compare_and_set_state(next_state, *expected_current)
+        mutex.synchronize do
+          if expected_current.include? @state
+            @state = next_state
+            true
+          else
+            false
+          end
+        end
+      end
+
+      # Executes the block within mutex if current state is included in expected_states
+      #
+      # @return block value if executed, false otherwise
+      #
+      # @!visibility private
+      def if_state(*expected_states)
+        mutex.synchronize do
+          raise ArgumentError.new('no block given') unless block_given?
+
+          if expected_states.include? @state
+            yield
+          else
+            false
+          end
+        end
+      end
+
+      protected
+
+      # Am I in the current state?
+      #
+      # @param [Symbol] expected The state to check against
+      # @return [Boolean] true if in the expected state else false
+      #
+      # @!visibility private
+      def ns_check_state?(expected)
+        @state == expected
+      end
+
+      # @!visibility private
+      def ns_set_state(value)
+        @state = value
+      end
+    end
+  end
+end

data/lib/concurrent/concern/observable.rb

@@ -0,0 +1,85 @@
+require 'concurrent/collection/copy_on_notify_observer_set'
+require 'concurrent/collection/copy_on_write_observer_set'
+
+module Concurrent
+  module Concern
+
+    # The [observer pattern](http://en.wikipedia.org/wiki/Observer_pattern) is one
+    # of the most useful design patterns.
+    #
+    # The workflow is very simple:
+    # - an `observer` can register itself to a `subject` via a callback
+    # - many `observers` can be registered to the same `subject`
+    # - the `subject` notifies all registered observers when its status changes
+    # - an `observer` can deregister itself when is no more interested to receive
+    #     event notifications
+    #
+    # In a single threaded environment the whole pattern is very easy: the
+    # `subject` can use a simple data structure to manage all its subscribed
+    # `observer`s and every `observer` can react directly to every event without
+    # caring about synchronization.
+    #
+    # In a multi threaded environment things are more complex. The `subject` must
+    # synchronize the access to its data structure and to do so currently we're
+    # using two specialized ObserverSet: CopyOnWriteObserverSet and
+    # CopyOnNotifyObserverSet.
+    #
+    # When implementing and `observer` there's a very important rule to remember:
+    # **there are no guarantees about the thread that will execute the callback**
+    #
+    # Let's take this example
+    # ```
+    # class Observer
+    #   def initialize
+    #     @count = 0
+    #   end
+    #
+    #   def update
+    #     @count += 1
+    #   end
+    # end
+    #
+    # obs = Observer.new
+    # [obj1, obj2, obj3, obj4].each { |o| o.add_observer(obs) }
+    # # execute [obj1, obj2, obj3, obj4]
+    # ```
+    #
+    # `obs` is wrong because the variable `@count` can be accessed by different
+    # threads at the same time, so it should be synchronized (using either a Mutex
+    # or an AtomicFixum)
+    module Observable
+
+      # @return [Object] the added observer
+      def add_observer(*args, &block)
+        observers.add_observer(*args, &block)
+      end
+
+      # as #add_observer but it can be used for chaining
+      # @return [Observable] self
+      def with_observer(*args, &block)
+        add_observer(*args, &block)
+        self
+      end
+
+      # @return [Object] the deleted observer
+      def delete_observer(*args)
+        observers.delete_observer(*args)
+      end
+
+      # @return [Observable] self
+      def delete_observers
+        observers.delete_observers
+        self
+      end
+
+      # @return [Integer] the observers count
+      def count_observers
+        observers.count_observers
+      end
+
+      protected
+
+      attr_accessor :observers
+    end
+  end
+end