concurrent-ruby 0.4.1 → 0.5.0.pre.1

data/lib/concurrent/atomic.rb

@@ -0,0 +1,125 @@
+module Concurrent
+
+  # @!visibility private
+  module MutexAtomicFixnum # :nodoc:
+
+    # @!visibility private
+    def allocate_storage(init) # :nodoc:
+      @value = init
+      @mutex = Mutex.new
+    end
+
+    def value
+      @mutex.synchronize do
+        @value
+      end
+    end
+
+    def value=(value)
+      raise ArgumentError.new('value must be a Fixnum') unless value.is_a?(Fixnum)
+      @mutex.synchronize do
+        @value = value
+      end
+    end
+
+    def increment
+      @mutex.synchronize do
+        @value += 1
+      end
+    end
+
+    def decrement
+      @mutex.synchronize do
+        @value -= 1
+      end
+    end
+
+    # @!visibility private
+    def compare_and_set(expect, update) # :nodoc:
+      @mutex.synchronize do
+        if @value == expect
+          @value = update
+          true
+        else
+          false
+        end
+      end
+    end
+  end
+
+  # @!visibility private
+  module JavaAtomicFixnum # :nodoc:
+
+    # @!visibility private
+    def allocate_storage(init) # :nodoc:
+      @atomic = java.util.concurrent.atomic.AtomicLong.new(init)
+    end
+
+    def value
+      @atomic.get
+    end
+
+    def value=(value)
+      raise ArgumentError.new('value must be a Fixnum') unless value.is_a?(Fixnum)
+      @atomic.set(value)
+    end
+
+    def increment
+      @atomic.increment_and_get
+    end
+
+    def decrement
+      @atomic.decrement_and_get
+    end
+
+    # @!visibility private
+    def compare_and_set(expect, update) # :nodoc:
+      @atomic.compare_and_set(expect, update)
+    end
+  end
+
+  # A numeric value that can be updated atomically. Reads and writes to an atomic
+  # fixnum and thread-safe and guaranteed to succeed. Reads and writes may block
+  # briefly but no explicit locking is required.
+  #
+  # @!method value()
+  #   Retrieves the current +Fixnum+ value
+  #   @return [Fixnum] the current value
+  #
+  # @!method value=(value)
+  #   Explicitly sets the value
+  #   @param [Fixnum] value the new value to be set
+  #   @return [Fixnum] the current value
+  #   @raise [ArgumentError] if the new value is not a +Fixnum+
+  #
+  # @!method increment()
+  #   Increases the current value by 1
+  #   @return [Fixnum] the current value after incrementation
+  #
+  # @!method decrement()
+  #   Decreases the current value by 1
+  #   @return [Fixnum] the current value after decrementation
+  #
+  # @since 0.5.0
+  # @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/atomic/AtomicLong.html java.util.concurrent.atomic.AtomicLong
+  class AtomicFixnum
+
+    # Creates a new +AtomicFixnum+ with the given initial value.
+    #
+    # @param [Fixnum] init the initial value
+    # @raise [ArgumentError] if the initial value is not a +Fixnum+
+    def initialize(init = 0)
+      raise ArgumentError.new('initial value must be a Fixnum') unless init.is_a?(Fixnum)
+      allocate_storage(init)
+    end
+
+    if defined? java.util
+      include JavaAtomicFixnum
+    else
+      include MutexAtomicFixnum
+    end
+
+    alias_method :up, :increment
+    alias_method :down, :decrement
+  end
+end

data/lib/concurrent/channel.rb

@@ -3,9 +3,44 @@ require 'concurrent/stoppable'
 
 module Concurrent
 
+  # +Channel+ is a functional programming variation of +Actor+, based very loosely on the
+  # *MailboxProcessor* agent in F#. +Actor+ is used to create objects that receive messages
+  # from other threads then processes those messages based on the behavior of the class.
+  # +Channel+ creates objects that receive messages and processe them using the block
+  # given at construction. +Channel+ is implemented as a subclass of +Actor+ and supports
+  # all message-passing methods of that class. +Channel+ also supports pools with a shared
+  # mailbox.
+  #
+  # @example Basic usage
+  #   channel = Concurrent::Channel.new do |msg|
+  #     sleep(1)
+  #     puts "#{msg}\n"
+  #   end
+  #   
+  #   channel.run! => #<Thread:0x007fa123d95fc8 sleep>
+  #   
+  #   channel.post("Hello, World!") => 1
+  #   # wait...
+  #   => Hello, World!
+  #   
+  #   future = channel.post? "Don't Panic." => #<Concurrent::IVar:0x007fa123d6d9d8 @state=:pending...
+  #   future.pending? => true
+  #   # wait...
+  #   => "Don't Panic."
+  #   future.fulfilled? => true
+  #   
+  #   channel.stop => true  
+  #   
+  # @see http://blogs.msdn.com/b/dsyme/archive/2010/02/15/async-and-parallel-design-patterns-in-f-part-3-agents.aspx Async and Parallel Design Patterns in F#: Agents
+  # @see http://msdn.microsoft.com/en-us/library/ee370357.aspx Control.MailboxProcessor<'Msg> Class (F#)
   class Channel < Actor
     include Stoppable
 
+    # Initialize a new object with a block operation to be performed in response
+    # to every received message.
+    #
+    # @yield [message] Removes the next message from the queue and processes it
+    # @yieldparam [Array] msg The next message post to the channel
     def initialize(&block)
       raise ArgumentError.new('no block given') unless block_given?
       super()
@@ -21,7 +56,7 @@ module Concurrent
 
     private
 
-    def act(*message)
+    def act(*message) # :nodoc:
       return @task.call(*message)
     end
   end

data/lib/concurrent/condition.rb

@@ -0,0 +1,67 @@
+module Concurrent
+
+  # Condition is a better implementation of standard Ruby ConditionVariable.
+  # The biggest difference is the wait return value: Condition#wait returns
+  # Condition::Result which make possible to know if waiting thread has been woken up
+  # by an another thread (using #signal or #broadcast) or due to timeout.
+  #
+  # Every #wait must be guarded by a locked Mutex or a ThreadError will be risen.
+  # Although it's not mandatory, it's recommended to call also #signal and #broadcast within
+  # the same mutex
+  class Condition
+
+    class Result
+      def initialize(remaining_time)
+        @remaining_time = remaining_time
+      end
+
+      attr_reader :remaining_time
+
+      # @return [Boolean] true if current thread has been waken up by a #signal or a #broadcast call, otherwise false
+      def woken_up?
+        @remaining_time.nil? || @remaining_time > 0
+      end
+
+      # @return [Boolean] true if current thread has been waken up due to a timeout, otherwise false
+      def timed_out?
+        @remaining_time != nil && @remaining_time <= 0
+      end
+
+      alias_method :can_wait?, :woken_up?
+
+    end
+
+    def initialize
+      @condition = ConditionVariable.new
+    end
+
+    # @param [Mutex] mutex the locked mutex guarding the wait
+    # @param [Object] timeout nil means no timeout
+    # @return [Result]
+    def wait(mutex, timeout = nil)
+      start_time = Time.now.to_f
+      @condition.wait(mutex, timeout)
+
+      if timeout.nil?
+        Result.new(nil)
+      else
+        Result.new(start_time + timeout - Time.now.to_f)
+      end
+    end
+
+    # Wakes up a waiting thread
+    # @return [true]
+    def signal
+      @condition.signal
+      true
+    end
+
+    # Wakes up all waiting threads
+    # @return [true]
+    def broadcast
+      @condition.broadcast
+      true
+    end
+
+  end
+end

data/lib/concurrent/copy_on_notify_observer_set.rb

@@ -0,0 +1,80 @@
+module Concurrent
+
+  # A thread safe observer set implemented using copy-on-read approach:
+  # observers are added and removed from a thread safe collection; every time
+  # a notification is required the internal data structure is copied to
+  # prevent concurrency issues
+  class CopyOnNotifyObserverSet
+
+    def initialize
+      @mutex = Mutex.new
+      @observers = {}
+    end
+
+    # Adds an observer to this set
+    # @param [Object] observer the observer to add
+    # @param [Symbol] func the function to call on the observer during notification. Default is :update
+    # @return [Symbol] the added function
+    def add_observer(observer, func=:update)
+      @mutex.synchronize { @observers[observer] = func }
+    end
+
+    # @param [Object] observer the observer to remove
+    # @return [Object] the deleted observer
+    def delete_observer(observer)
+      @mutex.synchronize { @observers.delete(observer) }
+      observer
+    end
+
+    # Deletes all observers
+    # @return [CopyOnWriteObserverSet] self
+    def delete_observers
+      @mutex.synchronize { @observers.clear }
+      self
+    end
+
+    # @return [Integer] the observers count
+    def count_observers
+      @mutex.synchronize { @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)
+      observers = @mutex.synchronize { @observers.dup }
+      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)
+      observers = duplicate_and_clear_observers
+      notify_to(observers, *args, &block)
+
+      self
+    end
+
+    private
+
+    def duplicate_and_clear_observers
+      @mutex.synchronize do
+        observers = @observers.dup
+        @observers.clear
+        observers
+      end
+    end
+
+    def notify_to(observers, *args)
+      raise ArgumentError.new('cannot give arguments and a block') if block_given? && ! args.empty?
+      observers.each do |observer, function|
+        args = yield if block_given?
+        observer.send(function, *args)
+      end
+    end
+  end
+end

data/lib/concurrent/copy_on_write_observer_set.rb

@@ -0,0 +1,94 @@
+module Concurrent
+
+  # 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
+    # @param [Object] observer the observer to add
+    # @param [Symbol] func the function to call on the observer during notification. Default is :update
+    # @return [Symbol] the added function
+    def add_observer(observer, func=:update)
+      @mutex.synchronize do
+        new_observers = @observers.dup
+        new_observers[observer] = func
+        @observers = new_observers
+      end
+      func
+    end
+
+    # @param [Object] observer the observer to remove
+    # @return [Object] the deleted observer
+    def delete_observer(observer)
+      @mutex.synchronize do
+        new_observers = @observers.dup
+        new_observers.delete(observer)
+        @observers = new_observers
+      end
+      observer
+    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
+
+    def notify_to(observers, *args)
+      raise ArgumentError.new('cannot give arguments and a block') if block_given? && ! args.empty?
+      observers.each do |observer, function|
+        args = yield if block_given?
+        observer.send(function, *args)
+      end
+    end
+
+    def observers
+      @mutex.synchronize { @observers }
+    end
+
+    def observers=(new_set)
+      @mutex.synchronize { @observers = new_set}
+    end
+
+    def clear_observers_and_return_old
+      @mutex.synchronize do
+        old_observers = @observers
+        @observers = {}
+        old_observers
+      end
+    end
+  end
+end

data/lib/concurrent/count_down_latch.rb

@@ -0,0 +1,60 @@
+module Concurrent
+
+  # 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 CountDownLatch
+
+    # 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)
+      unless count.is_a?(Fixnum) && count >= 0
+        raise ArgumentError.new('count must be in integer 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
+end