concurrent-ruby 0.8.0.pre1 → 0.8.0.pre2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 92bfafa2b9e5e7a3b60cbf6dd6f785a8f515ae64
-  data.tar.gz: 14ca027a5eadd0daa3d10fac49860418bb9cb7bc
+  metadata.gz: f7918a0f32c1369463e3045101a1a3b1629d501a
+  data.tar.gz: c97009756916b18836a277c4d62df2f57c02b797
 SHA512:
-  metadata.gz: 7fae6fa7ae3849e3d68578eb782e13f1dd2e149260c8ef9a5dc8bef72891af0cce9e82abb697cfe72819a1e1c1385936138b63b73f59dd71fba2c9b1bc47bcb8
-  data.tar.gz: 66264191f55ab2064cb527a32c84da91550e47681f0e67856535e72b3cb23875d308b8770ec74adfa921800f9c0ae79d14b2f7f7481e545e648dd98eda9ea36a
+  metadata.gz: 48a95b84f0d4f4545e0e962031d74e608ac922d7f99177fb98186ba3d6a4bc86e7f49033dae64afccdbb3c7a4730544826f91a362300548eb0519d145150fbbd
+  data.tar.gz: 4624b6a91696efe3d365091171f6e03c9de2a764d8d1791892d0ae43293a05e08d740536914f9ef57b3e10f7f8ba1ee766f1e0bda322f24e53a2565038d47af0

data/CHANGELOG.md

@@ -1,5 +1,6 @@
 ### Next Release v0.7.2 (TBD)
 
+* New `Semaphore` class based on [java.util.concurrent.Semaphore](http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Semaphore.html)
 * New `Promise.all?` and `Promise.any?` class methods
 * Renamed `:overflow_policy` on thread pools to `:fallback_policy`
 * Thread pools still accept the `:overflow_policy` option but display a warning

data/README.md

@@ -37,7 +37,7 @@
 
 ### Supported Ruby versions
 
-MRI 1.9.3, 2.0, 2.1, JRuby (1.9 mode), and Rubinius 2.x are supported.
+MRI 1.9.3, 2.0, 2.1, 2.2, JRuby (1.9 mode), and Rubinius 2.x are supported.
 This gem should be fully compatible with any interpreter that is compliant with Ruby 1.9.3 or newer.
 
 ## Features & Documentation
@@ -52,19 +52,19 @@ This library contains a variety of concurrency abstractions at high and low leve
 
 ### High-level, general-purpose asynchronous concurrency abstractions
 
-* [Actor](./doc/actor/main.md): Implements the Actor Model, where concurrent actors exchange messages. 
-* [Agent](./doc/agent.md): A single atomic value that represents an identity.
-* [Async](./doc/async.md): A mixin module that provides simple asynchronous behavior to any standard class/object or object.
-* [Future](./doc/future.md): An asynchronous operation that produces a value.
-  * [Dataflow](./doc/dataflow.md): Built on Futures, Dataflow allows you to create a task that will be scheduled when all of its data dependencies are available.
-* [Promise](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Promise.html): Similar to Futures, with more features. 
-* [ScheduledTask](./doc/scheduled_task.md): Like a Future scheduled for a specific future time. 
+* [Actor](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Actor.html): Implements the Actor Model, where concurrent actors exchange messages.
+* [Agent](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Agent.html): A single atomic value that represents an identity.
+* [Async](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Async.html): A mixin module that provides simple asynchronous behavior to any standard class/object or object.
+* [Future](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Future.html): An asynchronous operation that produces a value.
+  * [Dataflow](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Dataflow.html): Built on Futures, Dataflow allows you to create a task that will be scheduled when all of its data dependencies are available.
+* [Promise](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Promise.html): Similar to Futures, with more features.
+* [ScheduledTask](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ScheduledTask.html): Like a Future scheduled for a specific future time.
 * [TimerTask](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/TimerTask.html): A Thread that periodically wakes up to perform work at regular intervals. 
 * [Channel](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Channel.html): Communicating Sequential Processes (CSP). 
 
 ### Java-inspired ThreadPools and other executors
 
-* See [ThreadPool](./doc/thread_pools.md) overview, which also contains a list of other Executors available.
+* See [ThreadPool](http://ruby-concurrency.github.io/concurrent-ruby/file.thread_pools.html) overview, which also contains a list of other Executors available.
 
 ### Thread-safe Observers
 
@@ -73,6 +73,7 @@ This library contains a variety of concurrency abstractions at high and low leve
 * [CopyOnWriteObserverSet](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/CopyOnWriteObserverSet.html)
 
 ### Thread synchronization classes and algorithms
+
 Lower-level abstractions mainly used as building blocks. 
 
 * [condition](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Condition.html)
@@ -80,10 +81,12 @@ Lower-level abstractions mainly used as building blocks.
 * [cyclic barrier](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/CyclicBarrier.html)
 * [event](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Event.html)
 * [exchanger](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Exchanger.html)
+* [semaphore](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Semaphore.html)
 * [timeout](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent.html#timeout-class_method)
 * [timer](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent.html#timer-class_method)
 
 ### Thread-safe variables
+
 Lower-level abstractions mainly used as building blocks. 
 
 * [AtomicBoolean](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/AtomicBoolean.html)
@@ -92,7 +95,7 @@ Lower-level abstractions mainly used as building blocks.
 * [I-Structures](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/IVar.html) (IVar)
 * [M-Structures](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/MVar.html) (MVar)
 * [thread-local variables](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ThreadLocalVar.html)
-* [software transactional memory](./doc/tvar.md) (TVar)
+* [software transactional memory](http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/TVar.html) (TVar)
 
 ## Usage
 
@@ -153,7 +156,7 @@ To minimize installation errors the C extensions are available in the `concurren
 gem. The extension gem lists `concurrent-ruby` as a dependency so it is not necessary to install both.
 Simply install the extension gen:
 
-```shell
+```ruby
 gem install concurrent-ruby-ext
 ```
 
@@ -167,13 +170,45 @@ and run `bundle install` from your shell.
 
 In code it is only necessary to
 
-```shell
+```ruby
 require 'concurrent'
 ```
 
 The `concurrent-ruby` gem will automatically detect the presence of the `concurrent-ruby-ext` gem
 and load the appropriate C extensions.
 
+#### Note For gem developers
+
+No gems should depend on `concurrent-ruby-ext`. Doing so will force C extensions on your users.
+The best practice is to depend on `concurrent-ruby` and let users to decide if they want C extensions.
+
+### Building
+
+All published versions of this gem (core, extension, and several platform-specific packages) are compiled,
+packaged, tested, and published using an open, [automated process](https://github.com/ruby-concurrency/rake-compiler-dev-box).
+This process can also be used to create pre-compiled binaries of the extension gem for virtally
+any platform. *Documentation is forthcoming...*
+
+```
+*MRI only*
+rake build:native       # Build concurrent-ruby-ext-<version>-<platform>.gem into the pkg directory
+rake compile:extension  # Compile extension
+
+*JRuby only*
+rake build              # Build JRuby-specific core gem (alias for `build:core`)
+rake build:core         # Build concurrent-ruby-<version>-java.gem into the pkg directory
+
+*All except JRuby*
+rake build              # Build core and extension gems
+rake build:core         # Build concurrent-ruby-<version>.gem into the pkg directory
+rake build:ext          # Build concurrent-ruby-ext-<version>.gem into the pkg directory
+
+*All*
+rake clean              # Remove any temporary products
+rake clobber            # Remove any generated file
+rake compile            # Compile all the extensions
+```
+
 ## Maintainers
 
 * [Jerry D'Antonio](https://github.com/jdantonio)

data/lib/concurrent/atomic/semaphore.rb

@@ -0,0 +1,232 @@
+require 'concurrent/atomic/condition'
+
+module Concurrent
+  class MutexSemaphore
+    # @!macro [attach] semaphore_method_initialize
+    #
+    #   Create a new `Semaphore` 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
+        fail ArgumentError, 'count must be an non-negative integer'
+      end
+      @mutex = Mutex.new
+      @condition = Condition.new
+      @free = count
+    end
+
+    # @!macro [attach] semaphore_method_acquire
+    #
+    #   Acquires the given number of permits from this semaphore,
+    #     blocking until all are available.
+    #
+    #   @param [Fixnum] permits Number of permits to acquire
+    #
+    #   @raise [ArgumentError] if `permits` is not an integer or is less than
+    #     one
+    #
+    #   @return [Nil]
+    def acquire(permits = 1)
+      unless permits.is_a?(Fixnum) && permits > 0
+        fail ArgumentError, 'permits must be an integer greater than zero'
+      end
+      @mutex.synchronize do
+        try_acquire_timed(permits, nil)
+        nil
+      end
+    end
+
+    # @!macro [attach] semaphore_method_available_permits
+    #
+    #   Returns the current number of permits available in this semaphore.
+    #
+    #   @return [Integer]
+    def available_permits
+      @mutex.synchronize { @free }
+    end
+
+    # @!macro [attach] semaphore_method_drain_permits
+    #
+    #   Acquires and returns all permits that are immediately available.
+    #
+    #   @return [Integer]
+    def drain_permits
+      @mutex.synchronize do
+        @free.tap { |_| @free = 0 }
+      end
+    end
+
+    # @!macro [attach] semaphore_method_try_acquire
+    #
+    #   Acquires the given number of permits from this semaphore,
+    #     only if all are available at the time of invocation or within
+    #     `timeout` interval
+    #
+    #   @param [Fixnum] permits the number of permits to acquire
+    #
+    #   @param [Fixnum] timeout the number of seconds to wait for the counter
+    #     or `nil` to return immediately
+    #
+    #   @raise [ArgumentError] if `permits` is not an integer or is less than
+    #     one
+    #
+    #   @return [Boolean] `false` if no permits are available, `true` when
+    #     acquired a permit
+    def try_acquire(permits = 1, timeout = nil)
+      unless permits.is_a?(Fixnum) && permits > 0
+        fail ArgumentError, 'permits must be an integer greater than zero'
+      end
+      @mutex.synchronize do
+        if timeout.nil?
+          try_acquire_now(permits)
+        else
+          try_acquire_timed(permits, timeout)
+        end
+      end
+    end
+
+    # @!macro [attach] semaphore_method_release
+    #
+    #   Releases the given number of permits, returning them to the semaphore.
+    #
+    #   @param [Fixnum] permits Number of permits to return to the semaphore.
+    #
+    #   @raise [ArgumentError] if `permits` is not a number or is less than one
+    #
+    #   @return [Nil]
+    def release(permits = 1)
+      unless permits.is_a?(Fixnum) && permits > 0
+        fail ArgumentError, 'permits must be an integer greater than zero'
+      end
+      @mutex.synchronize do
+        @free += permits
+        permits.times { @condition.signal }
+      end
+      nil
+    end
+
+    # @!macro [attach] semaphore_method_reduce_permits
+    # 
+    #   @api private
+    #
+    #   Shrinks the number of available permits by the indicated reduction.
+    #
+    #   @param [Fixnum] reduction Number of permits to remove.
+    #
+    #   @raise [ArgumentError] if `reduction` is not an integer or is negative
+    #
+    #   @raise [ArgumentError] if `@free` - `@reduction` is less than zero
+    #
+    #   @return [Nil]
+    def reduce_permits(reduction)
+      unless reduction.is_a?(Fixnum) && reduction >= 0
+        fail ArgumentError, 'reduction must be an non-negative integer'
+      end
+      @mutex.synchronize { @free -= reduction }
+      nil 
+    end
+
+    private
+
+    def try_acquire_now(permits)
+      if @free >= permits
+        @free -= permits
+        true
+      else
+        false
+      end
+    end
+
+    def try_acquire_timed(permits, timeout)
+      remaining = Condition::Result.new(timeout)
+      while !try_acquire_now(permits) && remaining.can_wait?
+        @condition.signal
+        remaining = @condition.wait(@mutex, remaining.remaining_time)
+      end
+      remaining.can_wait? ? true : false
+    end
+  end
+
+  if RUBY_PLATFORM == 'java'
+
+    # @!macro semaphore
+    #     
+    #   A counting semaphore. Conceptually, a semaphore maintains a set of permits. Each {#acquire} blocks if necessary
+    #   until a permit is available, and then takes it. Each {#release} adds a permit,
+    #   potentially releasing a blocking acquirer.
+    #   However, no actual permit objects are used; the Semaphore just keeps a count of the number available and
+    #   acts accordingly.
+    class JavaSemaphore
+      # @!macro semaphore_method_initialize
+      def initialize(count)
+        unless count.is_a?(Fixnum) && count >= 0
+          fail(ArgumentError,
+               'count must be in integer greater than or equal zero')
+        end
+        @semaphore = java.util.concurrent.Semaphore.new(count)
+      end
+
+      # @!macro semaphore_method_acquire
+      def acquire(permits = 1)
+        unless permits.is_a?(Fixnum) && permits > 0
+          fail ArgumentError, 'permits must be an integer greater than zero'
+        end
+        @semaphore.acquire(permits)
+      end
+
+      # @!macro semaphore_method_available_permits
+      def available_permits
+        @semaphore.availablePermits
+      end
+
+      # @!macro semaphore_method_drain_permits
+      def drain_permits
+        @semaphore.drainPermits
+      end
+
+      # @!macro semaphore_method_try_acquire
+      def try_acquire(permits = 1, timeout = nil)
+        unless permits.is_a?(Fixnum) && permits > 0
+          fail ArgumentError, 'permits must be an integer greater than zero'
+        end
+        if timeout.nil?
+          @semaphore.tryAcquire(permits)
+        else
+          @semaphore.tryAcquire(permits,
+                                 timeout,
+                                 java.util.concurrent.TimeUnit::SECONDS)
+        end
+      end
+
+      # @!macro semaphore_method_release
+      def release(permits = 1)
+        unless permits.is_a?(Fixnum) && permits > 0
+          fail ArgumentError, 'permits must be an integer greater than zero'
+        end
+        @semaphore.release(permits)
+        true
+      end
+
+      # @!macro semaphore_method_reduce_permits
+      def reduce_permits(reduction)
+        unless reduction.is_a?(Fixnum) && reduction >= 0
+          fail ArgumentError, 'reduction must be an non-negative integer'
+        end
+        @semaphore.reducePermits(reduction)
+      end
+    end
+
+    # @!macro semaphore
+    class Semaphore < JavaSemaphore
+    end
+
+  else
+
+    # @!macro semaphore
+    class Semaphore < MutexSemaphore
+    end
+  end
+end

data/lib/concurrent/atomics.rb

@@ -8,3 +8,5 @@ require 'concurrent/atomic/cyclic_barrier'
 require 'concurrent/atomic/count_down_latch'
 require 'concurrent/atomic/event'
 require 'concurrent/atomic/synchronization'
+require 'concurrent/atomic/semaphore'
+require 'concurrent/atomic/thread_local_var'

data/lib/concurrent/executor/thread_pool_executor.rb

@@ -49,8 +49,6 @@ module Concurrent
     #   * `:discard`: Discard the task and return false.
     #   * `:caller_runs`: Execute the task on the calling thread.
     #
-    #   {include:file:doc/thread_pools.md}
-    #
     #   @note When running on the JVM (JRuby) this class will inherit from `JavaThreadPoolExecutor`.
     #     On all other platforms it will inherit from `RubyThreadPoolExecutor`.
     #

data/lib/concurrent/executor/timer_set.rb

@@ -55,10 +55,10 @@ module Concurrent
           @queue.push(Task.new(time, args, task))
           @timer_executor.post(&method(:process_tasks))
         end
-
-        true
       end
 
+      @condition.signal
+      true
     end
 
     # For a timer, #kill is like an orderly shutdown, except we need to manually
@@ -129,8 +129,20 @@ module Concurrent
         interval = task.time - Time.now.to_f
 
         if interval <= 0
+          # We need to remove the task from the queue before passing
+          # it to the executor, to avoid race conditions where we pass
+          # the peek'ed task to the executor and then pop a different
+          # one that's been added in the meantime.
+          #
+          # Note that there's no race condition between the peek and
+          # this pop - this pop could retrieve a different task from
+          # the peek, but that task would be due to fire now anyway
+          # (because @queue is a priority queue, and this thread is
+          # the only reader, so whatever timer is at the head of the
+          # queue now must have the same pop time, or a closer one, as
+          # when we peeked).
+          task = mutex.synchronize { @queue.pop }
           @task_executor.post(*task.args, &task.op)
-          mutex.synchronize { @queue.pop }
         else
           mutex.synchronize do
             @condition.wait(mutex, [interval, 60].min)

data/lib/concurrent/version.rb

@@ -1,4 +1,3 @@
 module Concurrent
-  VERSION = '0.8.0.pre1'
-  EXT_VERSION = '0.1.0.pre1'
+  VERSION = '0.8.0.pre2'
 end

data/lib/extension_helper.rb

@@ -1,5 +1,5 @@
 module Concurrent
-  
+
   @@c_ext_loaded ||= false
   @@java_ext_loaded ||= false
 
@@ -8,25 +8,30 @@ module Concurrent
     defined?(RUBY_ENGINE) && RUBY_ENGINE == 'ruby'
   end
 
+  # @!visibility private
+  def self.jruby?
+    RUBY_PLATFORM == 'java'
+  end
+
   if allow_c_extensions? && !@@c_ext_loaded
     begin
-      require 'concurrent_ruby_ext'
+      require 'concurrent/extension'
       @@c_ext_loaded = true
     rescue LoadError
       # may be a Windows cross-compiled native gem
       begin
-        require "#{RUBY_VERSION[0..2]}/concurrent_ruby_ext"
+        require "#{RUBY_VERSION[0..2]}/concurrent/extension"
         @@c_ext_loaded = true
       rescue LoadError
         warn 'Performance on MRI may be improved with the concurrent-ruby-ext gem. Please see http://concurrent-ruby.com'
       end
     end
-  elsif RUBY_PLATFORM == 'java' && !@@java_ext_loaded
+  elsif jruby? && !@@java_ext_loaded
     begin
       require 'concurrent_ruby_ext'
       @@java_ext_loaded = true
     rescue LoadError
-      #warn 'Attempted to load Java extensions on unsupported platform. Continuing with pure-Ruby.'
+      warn 'Attempted to load Java extensions on unsupported platform. Continuing with pure-Ruby.'
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: concurrent-ruby
 version: !ruby/object:Gem::Version
-  version: 0.8.0.pre1
+  version: 0.8.0.pre2
 platform: ruby
 authors:
 - Jerry D'Antonio
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-12-15 00:00:00.000000000 Z
+date: 2015-01-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ref
@@ -87,6 +87,7 @@ files:
 - lib/concurrent/atomic/count_down_latch.rb
 - lib/concurrent/atomic/cyclic_barrier.rb
 - lib/concurrent/atomic/event.rb
+- lib/concurrent/atomic/semaphore.rb
 - lib/concurrent/atomic/synchronization.rb
 - lib/concurrent/atomic/thread_local_var.rb
 - lib/concurrent/atomic_reference/concurrent_update_error.rb