thread_executor 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d5bde7f16838ab701a01d2ba70657239959a54a0
+  data.tar.gz: 2e809fb597ad664d6db40dd4d4eb9b4a4c83a857
+SHA512:
+  metadata.gz: 809c32bc10a3e9eef3fa86bcf714ecfdb5b3222e262f4e14b07835e7107267ff0f5fb2aca372cb6892cbdca8e7bdd67e94e95a007dc4050d6f1083f0edcb90c3
+  data.tar.gz: 99c0696e26e27722809e10c09c1d438006d4c3a9ad93da0ddf2153473dd38e453e1f6713e2717f4d8e1ac6d687fe3c2db4b68c87796756588199f6c35e7949f1

data/Changelog

@@ -0,0 +1,8 @@
+2015-04-21 Sam Baskinger <basking2@yahoo.com>
+  * Extracting executor into independent package.
+
+2015-03-18 Sam Baskinger <basking2@yahoo.com>
+  * Adding concurrency with thread pool implementation.
+
+Copyright 2014, 2015 Sam Baskinger <basking2@yahoo.com>
+

data/README.md

@@ -0,0 +1,3 @@
+# thread_executor
+Ruby 2 thread executor library.
+ 

data/lib/thread_executor.rb

@@ -0,0 +1,40 @@
+# Copyright (c) 2015, Sam Baskinger <basking2@yahoo.com>
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+# * Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+# 
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# 
+# * Neither the name of thread_executor nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require 'thread_executor/future'
+require 'thread_executor/promise'
+require 'thread_executor/executor'
+require 'thread_executor/processor'
+
+# A future/promise thread executor library.
+#
+# Start by checking out Executor.
+#
+module ThreadExecutor
+end
+

data/lib/thread_executor/executor.rb

@@ -0,0 +1,107 @@
+# Copyright (c) 2015, Sam Baskinger <basking2@yahoo.com>
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+# * Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+# 
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# 
+# * Neither the name of thread_executor nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+#
+module ThreadExecutor
+
+# A threaded executor.
+#
+# Procs can be given to this executor and are
+# executed according to the availability of threads.
+#
+# = Use
+#
+#     # Make an executor.
+#     executor = ThreadExecutor::Executor.new 10
+#
+#     begin
+#
+#       # Dispatch 100 jobs across the 10 threads.
+#       futures = 100.times.map { executor.call { do_long_running_work } }
+#
+#       # Collect the results.
+#       results = futures.map { |future| future.value }
+#
+#     ensure
+#       # Clean up the threads.
+#       executor.finish
+#     end
+#
+class Executor
+
+  # Build a new executor with +size+ Processor objects.
+  # The default size is 2.
+  #
+  # Each Processor contains a work queue and a running ruby Thread
+  # which will process the elements in the work queue.
+  #
+  # This Executor will insert elements into the work queue.
+  # 
+  # Use of the Executor is not thread safe. If more than one thread
+  # submit work to Processor objects through this Executor, the
+  # Executor must be protected by a lock of some sort.
+  def initialize size=2
+    @processors = []
+
+    size.times do
+      @processors << Processor.new
+    end
+  end
+
+  # Enqueues the block in a processor queue with the fewest tasks.
+  # 
+  # Returns a future for the result.
+  def call(&t)
+    min_processor = @processors[0]
+    min_size = min_processor.size
+    @processors.each do |p|
+      min_size2 = p.size
+      if min_size > min_size2
+        min_processor = p
+        min_size = min_size2
+      end
+    end
+
+    # Forward the user's block to the processor.
+    min_processor.call &t
+  end
+
+  # Sum of all queue depths.
+  def size
+    @processors.reduce(0) {|x,y| x + y.size}
+  end
+
+  # Shutdown and join all worker threads.
+  def finish
+    @processors.each do |p|
+      p.finish
+    end
+  end
+end
+
+end # module Sake

data/lib/thread_executor/future.rb

@@ -0,0 +1,51 @@
+# Copyright (c) 2015, Sam Baskinger <basking2@yahoo.com>
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+# * Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+# 
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# 
+# * Neither the name of thread_executor nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+module ThreadExecutor
+
+# Proxies access to a Future object.
+#
+# This protects the user from doing the "wrong thing"
+# with a Promise.
+class Future
+  def initialize(promise)
+    @promise = promise
+  end
+
+  # Block until a value is ready.
+  #
+  # If an Exception was raised instead of producing a value
+  # it is rethrown.
+  #
+  # This call is proxied to Promise#value.
+  def value
+    @promise.value
+  end
+end
+
+end # module ThreadExecutor

data/lib/thread_executor/processor.rb

@@ -0,0 +1,103 @@
+# Copyright (c) 2015, Sam Baskinger <basking2@yahoo.com>
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+# * Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+# 
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# 
+# * Neither the name of thread_executor nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require 'thread'
+
+module ThreadExecutor
+
+# A processor is a Queue feeding a Thread.
+class Processor
+
+  # Create Processor.
+  #
+  # This will create a new Queue and start a new ruby Thread.
+  #
+  # The created thread will block until work is inserted n the Queue
+  # using #call.
+  #
+  # To avoid leaking active threads you must call #finish to stop
+  # processing and join the Thread behind this object.
+  # Once this object is finished it may not be used again. It
+  # should be discarded.
+  #
+  # Typically the user should never create or use this class, but 
+  # use an Executor, though there is nothing wrong in using this
+  # directly..
+  def initialize
+    @q = Queue.new
+    @t = Thread.new do
+      while true do
+        promise, task = @q.deq
+
+        # This is how we shut down the thread cleanly.
+        break if promise.nil? && task.nil?
+
+        begin
+          promise.value = task.call
+        rescue Exception => e
+          promise.exception = e
+        end
+      end
+    end
+  end
+
+  # Signal that the worker thread should exit.
+  #
+  # More precisely, this enqueues a stop request
+  # into the work queue, which, when encountered,
+  # causes the worker thread to cleanly exit and 
+  # take no more work.
+  def shutdown
+    @q.enq [nil, nil]
+  end
+
+  # Adds a task, creates a Promise and returns a Future.
+  def call(&t)
+    p = Promise.new
+    @q.enq [ p, t ]
+    p.future
+  end
+
+  # Return the size of the work queue.
+  def size
+    @q.size
+  end
+
+  # Call #shutdown and join the thread.
+  # 
+  # This will block until the thread is joined.
+  #
+  # When this returns this object is unusable and should
+  # be discarded.
+  def finish
+    shutdown
+    @t.join
+  end
+end
+
+end # module ThreadExecutor

data/lib/thread_executor/promise.rb

@@ -0,0 +1,89 @@
+# Copyright (c) 2015, Sam Baskinger <basking2@yahoo.com>
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 
+# * Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+# 
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# 
+# * Neither the name of thread_executor nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require 'thread_executor/future'
+
+module ThreadExecutor
+
+# A Promise is a container for a value that a Processor will compute.
+#
+# It contains locking objects to ensure that the value is communicated
+# safely from the Processor 's Thread to user's Thread.
+#
+# A user typically never touches this object directly but 
+# examines the Future.
+class Promise
+  attr_reader :value, :exception, :future
+
+  def initialize()
+    @value     = nil
+    @exception = nil
+    @ready     = false
+    @lock      = Mutex.new
+    @cond      = ConditionVariable.new
+    @no_result = true
+    @future    = Future.new(self)
+  end
+
+  # Wait until this Promise is fulfilled and return the value
+  # If an exception was raised, it is reraised here.
+  def value
+    @lock.synchronize do
+
+      while ! @ready do
+        @cond.wait @lock
+      end
+
+      raise @exception if @exception
+
+      @value
+    end
+  end
+
+  def ready?
+    @ready
+  end
+
+  def value= v
+    @lock.synchronize do
+      @value = v
+      @ready = true
+      @cond.signal
+    end
+  end
+
+  def exception= e
+    @lock.synchronize do
+      @exception = e
+      @ready = true
+      @cond.signal
+    end
+  end
+end
+
+end # module ThreadExecutor

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: thread_executor
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- Sam Baskinger
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-04-22 00:00:00.000000000 Z
+dependencies: []
+description: |2
+    Thread executor library.
+email: basking2@yahoo.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+- Changelog
+files:
+- Changelog
+- README.md
+- lib/thread_executor.rb
+- lib/thread_executor/executor.rb
+- lib/thread_executor/future.rb
+- lib/thread_executor/processor.rb
+- lib/thread_executor/promise.rb
+homepage: https://github.com/basking2/thread_executor/
+licenses:
+- BSD
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Thread executor library.
+test_files: []