garcun 0.0.2

data/lib/garcon/task/future.rb

@@ -0,0 +1,107 @@
+# 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 'ivar'
+require_relative 'safe_task_executor'
+require_relative 'executor_options'
+
+module Garcon
+
+  class Future < IVar
+    include ExecutorOptions
+
+    # Create a new `Future` in the `:unscheduled` state.
+    #
+    # @yield the asynchronous operation to perform
+    #
+    # @!macro executor_and_deref_options
+    #
+    # @option opts [object, Array] :args
+    #  Zero or more arguments to be passed the task block on execution.
+    #
+    # @raise [ArgumentError] if no block is given
+    #
+    def initialize(opts = {}, &block)
+      raise ArgumentError.new('no block given') unless block_given?
+      super(IVar::NO_VALUE, opts)
+      @state    = :unscheduled
+      @task     = block
+      @executor = get_executor_from(opts) || Garcon.global_io_executor
+      @args     = get_arguments_from(opts)
+    end
+
+    # Execute an `:unscheduled` `Future`. Immediately sets the state to
+    # `:pending` and passes the block to a new thread/thread pool for eventual
+    # execution. Does nothing if the `Future` is in any state other than
+    # `:unscheduled`.
+    #
+    # @return [Future] a reference to `self`
+    #
+    # @example Instance and execute in separate steps
+    #   future = Garcon::Future.new{ sleep(1); 42 }
+    #   future.state #=> :unscheduled
+    #   future.execute
+    #   future.state #=> :pending
+    #
+    # @example Instance and execute in one line
+    #   future = Garcon::Future.new{ sleep(1); 42 }.execute
+    #   future.state #=> :pending
+    def execute
+      if compare_and_set_state(:pending, :unscheduled)
+        @executor.post(@args){ work }
+        self
+      end
+    end
+
+    # Create a new `Future` object with the given block, execute it, and return
+    # the `:pending` object.
+    #
+    # @example
+    #   future = Garcon::Future.execute{ sleep(1); 42 }
+    #   future.state #=> :pending
+    #
+    # @yield the asynchronous operation to perform.
+    #
+    # @!macro executor_and_deref_options.
+    #
+    # @option opts [object, Array] :args
+    #   Zero or more arguments to be passed the task block on execution.
+    #
+    # @raise [ArgumentError] if no block is given.
+    #
+    # @return [Future]
+    #   The newly created `Future` in the `:pending` state.
+    #
+    def self.execute(opts = {}, &block)
+      Future.new(opts, &block).execute
+    end
+
+    protected :set, :fail, :complete
+
+    private #        P R O P R I E T À   P R I V A T A   Vietato L'accesso
+
+    # @!visibility private
+    def work
+      success, val, reason = SafeTaskExecutor.new(@task).execute(*@args)
+      complete(success, val, reason)
+    end
+  end
+end

data/lib/garcon/task/immediate_executor.rb

@@ -0,0 +1,84 @@
+# 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 'event'
+require_relative 'executor'
+
+module Garcon
+
+  # An executor service which runs all operations on the current thread,
+  # blocking as necessary. Operations are performed in the order they are
+  # received and no two operations can be performed simultaneously.
+  #
+  # This executor service exists mainly for testing an debugging. When used
+  # it immediately runs every `#post` operation on the current thread, blocking
+  # that thread until the operation is complete. This can be very beneficial
+  # during testing because it makes all operations deterministic.
+  #
+  # @note Intended for use primarily in testing and debugging.
+  class ImmediateExecutor
+    include SerialExecutor
+
+    # Creates a new executor
+    def initialize
+      @stopped = Garcon::Event.new
+    end
+
+    # @!macro executor_method_post
+    def post(*args, &task)
+      raise ArgumentError, 'no block given' unless block_given?
+      return false unless running?
+      task.call(*args)
+      true
+    end
+
+    # @!macro executor_method_left_shift
+    def <<(task)
+      post(&task)
+      self
+    end
+
+    # @!macro executor_method_running_question
+    def running?
+      ! shutdown?
+    end
+
+    # @!macro executor_method_shuttingdown_question
+    def shuttingdown?
+      false
+    end
+
+    # @!macro executor_method_shutdown_question
+    def shutdown?
+      @stopped.set?
+    end
+
+    # @!macro executor_method_shutdown
+    def shutdown
+      @stopped.set
+      true
+    end
+    alias_method :kill, :shutdown
+
+    # @!macro executor_method_wait_for_termination
+    def wait_for_termination(timeout = nil)
+      @stopped.wait(timeout)
+    end
+  end
+end

data/lib/garcon/task/ivar.rb

@@ -0,0 +1,171 @@
+# 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 '../exceptions'
+require_relative 'obligation'
+require_relative 'observable'
+
+module Garcon
+
+  # An `IVar` is like a future that you can assign. As a future is a value that
+  # is being computed that you can wait on, an `IVar` is a value that is waiting
+  # to be assigned, that you can wait on. `IVars` are single assignment and
+  # deterministic.
+  #
+  # Then, express futures as an asynchronous computation that assigns an `IVar`.
+  # The `IVar` becomes the primitive on which [futures](Future) and
+  # [dataflow](Dataflow) are built.
+  #
+  # An `IVar` is a single-element container that is normally created empty, and
+  # can only be set once. The I in `IVar` stands for immutable. Reading an
+  # `IVar` normally blocks until it is set. It is safe to set and read an `IVar`
+  # from different threads.
+  #
+  # If you want to have some parallel task set the value in an `IVar`, you want
+  # a `Future`. If you want to create a graph of parallel tasks all executed
+  # when the values they depend on are ready you want `dataflow`. `IVar` is
+  # generally a low-level primitive.
+  #
+  # @example Create, set and get an `IVar`
+  #   ivar = Garcon::IVar.new
+  #   ivar.set 14
+  #   ivar.get #=> 14
+  #   ivar.set 2 # would now be an error
+  #
+  class IVar
+    include Obligation
+    include Observable
+
+    # @!visibility private
+    NO_VALUE = Object.new
+
+    # Create a new `IVar` in the `:pending` state with the (optional) initial
+    # value.
+    #
+    # @param [Object] value
+    #   The initial value.
+    #
+    # @param [Hash] opts the options to create a message with.
+    #
+    # @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)
+    #   Cll the given `Proc` passing the internal value and returning the value
+    #   returned from the proc.
+    #
+    def initialize(value = NO_VALUE, opts = {})
+      init_obligation
+      self.observers = CopyOnWriteObserverSet.new
+      set_deref_options(opts)
+
+      if value == NO_VALUE
+        @state = :pending
+      else
+        set(value)
+      end
+    end
+
+    # Add an observer on this object that will receive notification on update.
+    #
+    # Upon completion the `IVar` will notify all observers in a thread-safe way.
+    # The `func` method of the observer will be called with three arguments: the
+    # `Time` at which the `Future` completed the asynchronous operation, the
+    # final `value` (or `nil` on rejection), and the final `reason` (or `nil` on
+    # fulfillment).
+    #
+    # @param [Object] observer
+    #   The object that will be notified of changes.
+    #
+    # @param [Symbol] func
+    #   Symbol naming the method to call when the `Observable` has changes`
+    #
+    def add_observer(bsrver = nil, func = :update, &block)
+      if observer && block
+        raise ArgumentError, 'cannot provide both an observer and a block'
+      end
+      direct_notification = false
+
+      if block
+        observer = block
+        func     = :call
+      end
+
+      mutex.synchronize do
+        if event.set?
+          direct_notification = true
+        else
+          observers.add_observer(observer, func)
+        end
+      end
+
+      observer.send(func, Time.now, self.value, reason) if direct_notification
+      observer
+    end
+
+    # Set the `IVar` to a value and wake or notify all threads waiting on it.
+    #
+    # @param [Object] value
+    #   The value to store in the `IVar`.
+    #
+    # @raise [Garcon::MultipleAssignmentError]
+    #   If the `IVar` has already been set or otherwise completed.
+    #
+    # @return [IVar] self
+    #
+    def set(value)
+      complete(true, value, nil)
+    end
+
+    # Set the `IVar` to failed due to some error and wake or notify all threads
+    # waiting on it.
+    #
+    # @param [Object] reason
+    #   For the failure.
+    #
+    # @raise [Garcon::MultipleAssignmentError]
+    #   If the `IVar` has already been set or otherwise completed.
+    #
+    # @return [IVar] self
+    #
+    def fail(reason = StandardError.new)
+      complete(false, nil, reason)
+    end
+
+    # @!visibility private
+    def complete(success, value, reason)
+      mutex.synchronize do
+        if [:fulfilled, :rejected].include? @state
+          raise MultipleAssignmentError, 'multiple assignment'
+        end
+        set_state(success, value, reason)
+        event.set
+      end
+
+      time = Time.now
+      observers.notify_and_delete_observers{ [time, self.value, reason] }
+      self
+    end
+  end
+end

data/lib/garcon/task/lazy_reference.rb

@@ -0,0 +1,74 @@
+# 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
+
+  # Lazy evaluation of a block yielding an immutable result. Useful for
+  # expensive operations that may never be needed. `LazyReference` is a simpler,
+  # blocking version of `Delay` and has an API similar to `AtomicReference`.
+  # The first time `#value` is called the caller will block until the
+  # block given at construction is executed. Once the result has been
+  # computed the value will be immutably set. Any exceptions thrown during
+  # computation will be suppressed.
+  #
+  class LazyReference
+
+    # Creates a new unfulfilled object.
+    #
+    # @yield the delayed operation to perform
+    #
+    # @param [Object] default
+    #   The default value for the object when the block raises an exception.
+    #
+    # @raise [ArgumentError] if no block is given
+    #
+    def initialize(default = nil, &block)
+      raise ArgumentError, 'no block given' unless block_given?
+      @default   = default
+      @task      = block
+      @mutex     = Mutex.new
+      @value     = nil
+      @fulfilled = false
+    end
+
+    # The calculated value of the object or the default value if one was given
+    # at construction. This first time this method is called it will block
+    # indefinitely while the block is processed. Subsequent calls will not
+    # block.
+    #
+    # @return [Object] the calculated value
+    #
+    def value
+      return @value if @fulfilled
+
+      @mutex.synchronize do
+        unless @fulfilled
+          begin
+            @value = @task.call
+          rescue
+            @value = @default
+          ensure
+            @fulfilled = true
+          end
+        end
+        return @value
+      end
+    end
+  end
+end

data/lib/garcon/task/monotonic_time.rb

@@ -0,0 +1,69 @@
+# 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
+
+  # Clock that cannot be set and represents monotonic time since
+  # some unspecified starting point.
+  # @!visibility private
+  GLOBAL_MONOTONIC_CLOCK = Class.new {
+
+    if defined?(Process::CLOCK_MONOTONIC)
+      # @!visibility private
+      def get_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    else
+
+      require 'thread'
+
+      # @!visibility private
+      def initialize
+        @mutex      = Mutex.new
+        @last_time  = Time.now.to_f
+      end
+
+      # @!visibility private
+      def get_time
+        @mutex.synchronize do
+          now = Time.now.to_f
+          if @last_time < now
+            @last_time = now
+          else # clock has moved back in time
+            @last_time +=  0.000_001
+          end
+        end
+      end
+    end
+  }.new
+  private_constant :GLOBAL_MONOTONIC_CLOCK
+
+  # @!macro [attach] monotonic_get_time
+  #
+  #   Returns the current time a tracked by the application monotonic clock.
+  #
+  #   @return [Float] The current monotonic time when `since` not given else
+  #     the elapsed monotonic time between `since` and the current time
+  #
+  #   @!macro monotonic_clock_warning
+  def monotonic_time
+    GLOBAL_MONOTONIC_CLOCK.get_time
+  end
+  module_function :monotonic_time
+end