garcun 0.0.2

data/lib/garcon/task/obligation.rb

@@ -0,0 +1,256 @@
+# encoding: UTF-8
+#
+# Author:    Stefano Harding <riddopic@gmail.com>
+# License:   Apache License, Version 2.0
+# Copyright: (C) 2014-2015 Stefano Harding
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require 'thread'
+require 'timeout'
+require_relative 'dereferenceable'
+require_relative 'event'
+
+module Garcon
+
+  module Obligation
+    include Dereferenceable
+
+    # 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
+
+    # Is the obligation still awaiting completion of processing?
+    #
+    # @return [Boolean]
+    #
+    def incomplete?
+      [:unscheduled, :pending].include? state
+    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 second to wait.
+    #
+    # @raise [Exception]
+    #   Raises the reason when rejected`
+    #
+    # @return [Obligation] self
+    #
+    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.
+    #
+    # @raise [Exception]
+    #   Raises the reason when rejected.
+    #
+    # @return [Object]
+    #   see Dereferenceable#deref
+    #
+    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.lock
+      @state
+    ensure
+      mutex.unlock
+    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.lock
+      @reason
+    ensure
+      mutex.unlock
+    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 #      A T T E N Z I O N E   A R E A   P R O T E T T A
+
+    # @!visibility private
+    def get_arguments_from(opts = {})
+      [*opts.fetch(:args, [])]
+    end
+
+    # @!visibility private
+    def init_obligation
+      init_mutex
+      @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.lock
+      @state = value
+    ensure
+      mutex.unlock
+    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]
+    #   TRrue is state is changed, false otherwise
+    #
+    # @!visibility private
+    def compare_and_set_state(next_state, expected_current) # :nodoc:
+      mutex.lock
+      if @state == expected_current
+        @state = next_state
+        true
+      else
+        false
+      end
+    ensure
+      mutex.unlock
+    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.lock
+      raise ArgumentError, 'no block given' unless block_given?
+
+      if expected_states.include? @state
+        yield
+      else
+        false
+      end
+    ensure
+      mutex.unlock
+    end
+  end
+end

data/lib/garcon/task/observable.rb

@@ -0,0 +1,101 @@
+# encoding: UTF-8
+#
+# Author:    Stefano Harding <riddopic@gmail.com>
+# License:   Apache License, Version 2.0
+# Copyright: (C) 2014-2015 Stefano Harding
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require_relative 'copy_on_notify_observer_set'
+require_relative 'copy_on_write_observer_set'
+
+module Garcon
+
+  # The [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 #      A T T E N Z I O N E   A R E A   P R O T E T T A
+
+    attr_accessor :observers
+  end
+end

data/lib/garcon/task/priority_queue.rb

@@ -0,0 +1,234 @@
+# encoding: UTF-8
+#
+# Author:    Stefano Harding <riddopic@gmail.com>
+# License:   Apache License, Version 2.0
+# Copyright: (C) 2014-2015 Stefano Harding
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+module Garcon
+
+  # A queue collection in which the elements are sorted based on their
+  # comparison (spaceship) operator `<=>`. Items are added to the queue at a
+  # position relative to their priority. On removal the element with the
+  # "highest" priority is removed. By default the sort order is from highest to
+  # lowest, but a lowest-to-highest sort order can be set on construction.
+  #
+  # The API is based on the `Queue` class from the Ruby standard library.
+  #
+  class MutexPriorityQueue
+
+    # Create a new priority queue with no items.
+    #
+    # @param [Hash] opts
+    #   The options for creating the queue.
+    #
+    # @option opts [Symbol] :order (:max)
+    #   dictates the order in which items are stored: from highest to lowest
+    #   when `:max` or `:high`; from lowest to highest when `:min` or `:low`
+    #
+    def initialize(opts = {})
+      order = opts.fetch(:order, :max)
+      @comparator = [:min, :low].include?(order) ? -1 : 1
+      clear
+    end
+
+    # Removes all of the elements from this priority queue.
+    #
+    def clear
+      @queue = [nil]
+      @length = 0
+      true
+    end
+
+    # Deletes all items from `self` that are equal to `item`.
+    #
+    # @param [Object] item
+    #   The item to be removed from the queue.
+    #
+    # @return [Object]
+    #   True if the item is found else false.
+    #
+    def delete(item)
+      original_length = @length
+      k = 1
+      while k <= @length
+        if @queue[k] == item
+          swap(k, @length)
+          @length -= 1
+          sink(k)
+          @queue.pop
+        else
+          k += 1
+        end
+      end
+      @length != original_length
+    end
+
+    # Returns `true` if `self` contains no elements.
+    #
+    # @return [Boolean]
+    #   True if there are no items in the queue else false.
+    #
+    def empty?
+      size == 0
+    end
+
+    # Returns `true` if the given item is present in `self` (that is, if any
+    # element == `item`), otherwise returns false.
+    #
+    # @param [Object] item
+    #   The item to search for
+    #
+    # @return [Boolean]
+    #   True if the item is found else false.
+    #
+    def include?(item)
+      @queue.include?(item)
+    end
+    alias_method :has_priority?, :include?
+
+    # The current length of the queue.
+    #
+    # @return [Fixnum]
+    #   The number of items in the queue.
+    #
+    def length
+      @length
+    end
+    alias_method :size, :length
+
+    # Retrieves, but does not remove, the head of this queue, or returns `nil`
+    # if this queue is empty.
+    #
+    # @return [Object]
+    #   The head of the queue or `nil` when empty.
+    #
+    def peek
+      @queue[1]
+    end
+
+    # Retrieves and removes the head of this queue, or returns `nil` if this
+    # queue is empty.
+    #
+    # @return [Object]
+    #   The head of the queue or `nil` when empty.
+    #
+    def pop
+      max = @queue[1]
+      swap(1, @length)
+      @length -= 1
+      sink(1)
+      @queue.pop
+      max
+    end
+    alias_method :deq, :pop
+    alias_method :shift, :pop
+
+    # Inserts the specified element into this priority queue.
+    #
+    # @param [Object]
+    #   Item the item to insert onto the queue.
+    #
+    def push(item)
+      @length += 1
+      @queue << item
+      swim(@length)
+      true
+    end
+    alias_method :<<, :push
+    alias_method :enq, :push
+
+    # Create a new priority queue from the given list.
+    #
+    # @param [Enumerable] list
+    #   The list to build the queue from.
+    #
+    # @param [Hash] opts
+    #   The options for creating the queue.
+    #
+    # @return [PriorityQueue]
+    #   The newly created and populated queue.
+    #
+    def self.from_list(list, opts = {})
+      queue = new(opts)
+      list.each { |item| queue << item }
+      queue
+    end
+
+    protected #      A T T E N Z I O N E   A R E A   P R O T E T T A
+
+    # Exchange the values at the given indexes within the internal array.
+    #
+    # @param [Integer] x
+    #   The first index to swap.
+    #
+    # @param [Integer] y
+    #   The second index to swap.
+    #
+    # @!visibility private
+    def swap(x, y)
+      temp = @queue[x]
+      @queue[x] = @queue[y]
+      @queue[y] = temp
+    end
+
+    # Are the items at the given indexes ordered based on the priority
+    # order specified at construction?
+    #
+    # @param [Integer] x
+    #   The first index from which to retrieve a comparable value.
+    #
+    # @param [Integer] y
+    #   The second index from which to retrieve a comparable value.
+    #
+    # @return [Boolean]
+    #   True if the two elements are in the correct priority order else false.
+    #
+    # @!visibility private
+    def ordered?(x, y)
+      (@queue[x] <=> @queue[y]) == @comparator
+    end
+
+    # Percolate down to maintain heap invariant.
+    #
+    # @param [Integer] k
+    #   The index at which to start the percolation.
+    #
+    # @!visibility private
+    def sink(k)
+      while (j = (2 * k)) <= @length do
+        j += 1 if j < @length && ! ordered?(j, j+1)
+        break if ordered?(k, j)
+        swap(k, j)
+        k = j
+      end
+    end
+
+    # Percolate up to maintain heap invariant.
+    #
+    # @param [Integer] k
+    #   The index at which to start the percolation.
+    #
+    # @!visibility private
+    def swim(k)
+      while k > 1 && ! ordered?(k/2, k) do
+        swap(k, k/2)
+        k = k/2
+      end
+    end
+  end
+
+  class PriorityQueue < MutexPriorityQueue; end
+end