garcun 0.0.2

data/lib/garcon/task/copy_on_write_observer_set.rb

@@ -0,0 +1,153 @@
+# 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 thread safe observer set implemented using copy-on-write approach:
+  # every time an observer is added or removed the whole internal data structure
+  # is duplicated and replaced with a new one.
+  #
+  class CopyOnWriteObserverSet
+
+    def initialize
+      @mutex = Mutex.new
+      @observers = {}
+    end
+
+    # Adds an observer to this set. If a block is passed, the observer will be
+    # created by this method and no other params should be passed
+    #
+    # @param [Object] observer
+    #   the observer to add
+    #
+    # @param [Symbol] func
+    #   the function to call on the observer during notification. The default
+    #   is :update.
+    #
+    # @return [Object]
+    #   the added observer
+    def add_observer(observer=nil, func=:update, &block)
+      if observer.nil? && block.nil?
+        raise ArgumentError, 'should pass observer as a first argument or block'
+      elsif observer && block
+        raise ArgumentError.new('cannot provide both an observer and a block')
+      end
+
+      if block
+        observer = block
+        func = :call
+      end
+
+      begin
+        @mutex.lock
+        new_observers = @observers.dup
+        new_observers[observer] = func
+        @observers = new_observers
+        observer
+      ensure
+        @mutex.unlock
+      end
+    end
+
+    # @param [Object] observer
+    #   the observer to remove
+    # @return [Object]
+    #   the deleted observer
+    def delete_observer(observer)
+      @mutex.lock
+      new_observers = @observers.dup
+      new_observers.delete(observer)
+      @observers = new_observers
+      observer
+    ensure
+      @mutex.unlock
+    end
+
+    # Deletes all observers
+    # @return [CopyOnWriteObserverSet] self
+    def delete_observers
+      self.observers = {}
+      self
+    end
+
+
+    # @return [Integer] the observers count
+    def count_observers
+      observers.count
+    end
+
+    # Notifies all registered observers with optional args
+    #
+    # @param [Object] args
+    #   Arguments to be passed to each observer
+    #
+    # @return [CopyOnWriteObserverSet] self
+    def notify_observers(*args, &block)
+      notify_to(observers, *args, &block)
+      self
+    end
+
+    # Notifies all registered observers with optional args and deletes them.
+    #
+    # @param [Object] args
+    #   Arguments to be passed to each observer
+    #
+    # @return [CopyOnWriteObserverSet] self
+    def notify_and_delete_observers(*args, &block)
+      old = clear_observers_and_return_old
+      notify_to(old, *args, &block)
+      self
+    end
+
+    private #        P R O P R I E T À   P R I V A T A   Vietato L'accesso
+
+    def notify_to(observers, *args)
+      if block_given? && !args.empty?
+        raise ArgumentError.new 'cannot give arguments and a block'
+      end
+      observers.each do |observer, function|
+        args = yield if block_given?
+        observer.send(function, *args)
+      end
+    end
+
+    def observers
+      @mutex.lock
+      @observers
+    ensure
+      @mutex.unlock
+    end
+
+    def observers=(new_set)
+      @mutex.lock
+      @observers = new_set
+    ensure
+      @mutex.unlock
+    end
+
+    def clear_observers_and_return_old
+      @mutex.lock
+      old_observers = @observers
+      @observers = {}
+      old_observers
+    ensure
+      @mutex.unlock
+    end
+  end
+end

data/lib/garcon/task/count_down_latch.rb

@@ -0,0 +1,92 @@
+# 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 'condition'
+
+module Garcon
+
+  # A synchronization object that allows one thread to wait on multiple other
+  # threads. The thread that will wait creates a `CountDownLatch` and sets the
+  # initial value (normally equal to the number of other threads). The
+  # initiating thread passes the latch to the other threads then waits for the
+  # other threads by calling the `#wait` method. Each of the other threads
+  # calls `#count_down` when done with its work. When the latch counter reaches
+  # zero the waiting thread is unblocked and continues with its work. A
+  # `CountDownLatch` can be used only once. Its value cannot be reset.
+  #
+  class MutexCountDownLatch
+
+    # Create a new `CountDownLatch` with the initial `count`.
+    #
+    # @param [Fixnum] count
+    #   The initial count
+    #
+    # @raise [ArgumentError]
+    #   If `count` is not an integer or is less than zero.
+    #
+    def initialize(count = 1)
+      unless count.is_a?(Fixnum) && count >= 0
+        raise ArgumentError, 'count must be greater than or equal zero'
+      end
+      @mutex     = Mutex.new
+      @condition = Condition.new
+      @count     = count
+    end
+
+    # Block on the latch until the counter reaches zero or until `timeout` is
+    # reached.
+    #
+    # @param [Fixnum] timeout
+    #   The number of seconds to wait for the counter or `nil` to block
+    #   indefinitely.
+    # @return [Boolean]
+    #   True if the count reaches zero else false on timeout.
+    #
+    def wait(timeout = nil)
+      @mutex.synchronize do
+        remaining    = Condition::Result.new(timeout)
+        while @count > 0 && remaining.can_wait?
+          remaining  = @condition.wait(@mutex, remaining.remaining_time)
+        end
+        @count == 0
+      end
+    end
+
+    # Signal the latch to decrement the counter. Will signal all blocked
+    # threads when the `count` reaches zero.
+    #
+    def count_down
+      @mutex.synchronize do
+        @count -= 1 if @count > 0
+        @condition.broadcast if @count == 0
+      end
+    end
+
+    # The current value of the counter.
+    #
+    # @return [Fixnum]
+    #   The current value of the counter.
+    #
+    def count
+      @mutex.synchronize { @count }
+    end
+  end
+
+  class CountDownLatch < MutexCountDownLatch; end
+end

data/lib/garcon/task/delay.rb

@@ -0,0 +1,196 @@
+# 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_relative 'obligation'
+require_relative 'executor_options'
+require_relative 'immediate_executor'
+
+module Garcon
+
+  # Lazy evaluation of a block yielding an immutable result. Useful for
+  # expensive operations that may never be needed. It may be non-blocking,
+  # supports the `Obligation` interface, and accepts the injection of custom
+  # executor upon which to execute the block. Processing of block will be
+  # deferred until the first time `#value` is called. At that time the caller
+  # can choose to return immediately and let the block execute asynchronously,
+  # block indefinitely, or block with a timeout.
+  #
+  # 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.
+  #
+  # `Delay` includes the `Garcon::Dereferenceable` mixin to support thread
+  # safety of the reference returned by `#value`.
+  #
+  # @!macro [attach] delay_note_regarding_blocking
+  #   @note The default behavior of `Delay` is to block indefinitely when
+  #     calling either `value` or `wait`, executing the delayed operation on
+  #     the current thread. This makes the `timeout` value completely
+  #     irrelevant. To enable non-blocking behavior, use the `executor`
+  #     constructor option. This will cause the delayed operation to be
+  #     execute on the given executor, allowing the call to timeout.
+  #
+  # @see Garcon::Dereferenceable
+  class Delay
+    include Obligation
+    include ExecutorOptions
+
+    # Create a new `Delay` in the `:pending` state.
+    #
+    # @yield the delayed operation to perform
+    #
+    # @raise [ArgumentError] if no block is given
+    #
+    def initialize(opts = {}, &block)
+      raise ArgumentError, 'no block given' unless block_given?
+      init_obligation
+      set_deref_options(opts)
+      @task_executor = get_executor_from(opts)
+      @task          = block
+      @state         = :pending
+      @computing     = false
+    end
+
+    # Return the value this object represents after applying the options
+    # specified by the `#set_deref_options` method. If the delayed operation
+    # raised an exception this method will return nil. The execption object
+    # can be accessed via the `#reason` method.
+    #
+    # @param [Numeric]
+    #   Timeout the maximum number of seconds to wait.
+    #
+    # @return [Object] the current value of the object.
+    #
+    def value(timeout = nil)
+      if @task_executor
+        super
+      else
+        mutex.synchronize do
+          execute = @computing = true unless @computing
+          if execute
+            begin
+              set_state(true, @task.call, nil)
+            rescue => e
+              set_state(false, nil, e)
+            end
+          end
+        end
+        if @do_nothing_on_deref
+          @value
+        else
+          apply_deref_options(@value)
+        end
+      end
+    end
+
+    # Return the value this object represents after applying the options
+    # specified by the `#set_deref_options` method. If the delayed operation
+    # raised an exception, this method will raise that exception (even when)
+    # the operation has already been executed).
+    #
+    # @param [Numeric]
+    #   Timeout the maximum number of seconds to wait.
+    #
+    # @raise [Exception] when `#rejected?` raises `#reason`.
+    #
+    # @return [Object]
+    #   The current value of the object.
+    #
+    def value!(timeout = nil)
+      if @task_executor
+        super
+      else
+        result = value
+        raise @reason if @reason
+        result
+      end
+    end
+
+    # Return the value this object represents after applying the options
+    # specified by the `#set_deref_options` method.
+    #
+    # @param [Integer]
+    #   Timeout (nil) the maximum number of seconds to wait for the value to be
+    #   computed. When `nil` the caller will block indefinitely.
+    #
+    # @return [Object] self
+    #
+    def wait(timeout = nil)
+      if @task_executor
+        execute_task_once
+        super(timeout)
+      else
+        value
+      end
+      self
+    end
+
+    # Reconfigures the block returning the value if still `#incomplete?`
+    #
+    # @yield the delayed operation to perform
+    #
+    # @return [true, false] if success
+    #
+    def reconfigure(&block)
+      mutex.lock
+      raise ArgumentError.new('no block given') unless block_given?
+      unless @computing
+        @task = block
+        true
+      else
+        false
+      end
+    ensure
+      mutex.unlock
+    end
+
+    private
+
+    # @!visibility private
+    def execute_task_once
+      mutex.lock
+      execute = @computing = true unless @computing
+      task    = @task
+      mutex.unlock
+
+      if execute
+        @task_executor.post do
+          begin
+            result  = task.call
+            success = true
+          rescue => e
+            reason = e
+          end
+          mutex.lock
+          set_state(success, result, reason)
+          event.set
+          mutex.unlock
+        end
+      end
+    end
+  end
+end

data/lib/garcon/task/dereferenceable.rb

@@ -0,0 +1,144 @@
+# 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
+
+  # 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.
+  #
+  # Objects with this mixin can be configured with a few options that can help
+  # protect the program from potentially dangerous operations.
+  #
+  # * `:dup_on_deref`: when true will call the `#dup` method on the `value`
+  #     object every time the `#value` method is called (default: false)
+  # * `:freeze_on_deref`: when true  will call the `#freeze` method on the
+  #     `value` object every time the `#value` method is called (default: false)
+  # * `:copy_on_deref`: when given a `Proc` object the `Proc` will be run every
+  #     time the `#value` method is called. The `Proc` will be given the current
+  #     `value` as its only parameter and the result returned by the block will
+  #     be the return value of the `#value` call. When `nil` this option will be
+  #     ignored (default: nil)
+  #
+  module Dereferenceable
+
+    # Return the value this object represents after applying the options
+    # specified by the `#set_deref_options` method.
+    #
+    # When multiple deref options are set the order of operations is strictly
+    # defined. The order of deref operations is:
+    # * `:copy_on_deref`
+    # * `:dup_on_deref`
+    # * `:freeze_on_deref`
+    #
+    # Because of this ordering there is no need to `#freeze` an object created
+    # by a provided `:copy_on_deref` block. Simply set `:freeze_on_deref` to
+    # `true`. Setting both `:dup_on_deref` to `true` and `:freeze_on_deref` to
+    # `true` is as close to the behavior of a "pure" functional language as we
+    # are likely to get in Ruby.
+    #
+    # This method is thread-safe and synchronized with the internal `#mutex`.
+    #
+    # @return [Object]
+    #   the current value of the object
+    def value
+      mutex.lock
+      apply_deref_options(@value)
+    ensure
+      mutex.unlock
+    end
+
+    alias_method :deref, :value
+
+    protected #      A T T E N Z I O N E   A R E A   P R O T E T T A
+
+    # Set the internal value of this object
+    #
+    # @param [Object] val
+    #   the new value
+    def value=(val)
+      mutex.lock
+      @value = val
+    ensure
+      mutex.unlock
+    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
+    end
+
+    # 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.lock
+      @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]
+      @nothing_on_deref = !(@dup_on_deref || @freeze_on_deref || @copy_on_deref)
+      nil
+    ensure
+      mutex.unlock
+    end
+
+    # @!visibility private
+    def apply_deref_options(value)
+      return nil if value.nil?
+      return value if @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