thread_tools 0.26 → 0.27

data/README.rdoc

@@ -6,7 +6,7 @@
 
 A collection of utilities that I often use for threaded code.
 
-== FEATURES/PROBLEMS:
+== FEATURES:
 
 * Thread pool
 * Mongrel patch (thread pool)
@@ -40,6 +40,19 @@ A collection of utilities that I often use for threaded code.
  server = Mongrel::HttpServer.new(host, port)
  server.run(10).join
 
+* An annoying mutex
+ require 'thread_tools/debugmutex'
+ mtxA = ThreadTools::DebugMutex.new
+ mtxB = ThreadTools::DebugMutex.new
+ begin
+   mtxA.lock
+   mtxB.lock
+   mtxA.unlock # <= kboom!!!
+ rescue
+   # Warning, the next line unlocks all mutex acquired by this thread
+   ThreadTools::DebugMutex.unlock_all(Thread.current)
+ end
+
 == REQUIREMENTS:
 
 * Mongrel patch requires mongrel (duh)

data/lib/thread_tools/debugmutex.rb

@@ -1,15 +1,29 @@
-# Author: Daniel Tralamazza
-# Date: 29 Sep 2009
-#
-# Mutex
+# = Synopsis
+# An annoying mutex for debugging
 #
+# = Description
 # This class will make things slower, expect more contentions than normal, so
-# don't use to protect small blocks or tight loops
-#
+# <b>do not</b> use it to protect small blocks or tight loops.
 # I derived this mutex because I needed to check contention levels, trace
-# ownership changes and catch simple lock inversions
+# ownership changes and catch simple lock inversions.
+#
+# Tip:: Use .inspect method to get a small report.
 #
-# Use .inspect method to get a small report
+# = Usage
+#    mtxA = ThreadTools::DebugMutex.new
+#    mtxB = ThreadTools::DebugMutex.new
+#    begin
+#      mtxA.lock
+#      mtxB.lock
+#      mtxA.unlock # <= kboom!!!
+#    rescue
+#      ThreadTools::DebugMutex.unlock_all(Thread.current)
+#    end
+#
+#
+# Author::   Daniel Tralamazza
+# License:: {MIT # License.}[http://www.opensource.org/licenses/mit-license.php]
+
 
 require 'thread'
 
@@ -20,8 +34,11 @@ module ThreadTools
     end
 
     class DebugMutex < Mutex
+        # number of out of order unlocks
         attr_reader :out_of_order_locks
+        # number of contentions
         attr_reader :contentions
+        # owner thread, nil if unlocked
         attr_reader :owner
 
         def initialize
@@ -85,7 +102,7 @@ module ThreadTools
             "Owner #{@owner}, Contentions #{@contentions}, Out of order acquisitions #{@out_of_order_locks}"
         end
 
-        # just for fun
+        # *thread* thread object
         def self.unlock_all(thread)
             thread[:locks].reverse_each do |l|
                 l.unlock

data/lib/thread_tools/mongrel_pool.rb

@@ -1,10 +1,21 @@
-# Author: Daniel Tralamazza
-# Date: 28 Sep 2009
+# = Synopsis
+# Quick and dirty patch to mongrel
 #
+# = Description
 # This code patches mongrel to use a thread pool instead of creating a new thread
-# for every request. It also traps SIGTERM to close all connections
-# Changed method run to accept an extra parameter to set thread pool size
+# for every request. It also traps SIGTERM to close all connections.
+# I also changed the run method to accept an extra parameter to set thread pool size.
 #
+# = Usage
+# Just add <tt>require 'thread_tools/mongrel_patch'</tt> after the mongrel require
+#    require 'mongrel'
+#    require 'thread_tools/mongrel_pool'
+#    
+#    server = Mongrel::HttpServer.new(host, port)
+#    server.run(10).join
+#
+# Author:: Daniel Tralamazza
+# License:: {MIT # License.}[http://www.opensource.org/licenses/mit-license.php]
 
 
 require File.expand_path(File.dirname(__FILE__)+'/threadpool')

data/lib/thread_tools/semaphore.rb

@@ -1,9 +1,16 @@
-# Author: Daniel Tralamazza
-# Date: 
+# = Synopsis
+# Stupid simple semaphore
 #
-# Semaphore
+# = Description
+# ...
 #
-
+# = Usage
+#   sem = ThreadTools::Semaphore.new(1)
+#   sem.acquire
+#   sem.release
+#
+# Author:: Daniel Tralamazza
+# License:: {MIT # License.}[http://www.opensource.org/licenses/mit-license.php]
 
 require 'thread'
 

data/lib/thread_tools/threadpool.rb

@@ -1,17 +1,22 @@
-# Author: Daniel Tralamazza
-# Date: 25 Sep 2009
+# = Synopsis
+# A bounded thread pool
 #
-# ThreadPool
+# = Description
+# This threadpool pre allocates _N_ threads to serve .spawn calls.
+# By default workers are not killed if an exception is thrown, you can
+# change this behavior by setting +kill_worker_on_exception+.
 #
-# Usage:
+# = Usage
+#   tpool = ThreadTools::ThreadPool.new(3)
+#   12.times do |i|</tt>
+#     tpool.spawn(i, "hi") {|ti, ts|
+#       puts "#{Thread.current} (#{ti}) says #{ts}\n"
+#     }
+#   end
+#   tpool.shutdown
 #
-# tpool = ThreadTools::ThreadPool.new(3)
-# 12.times do |i|
-#   tpool.spawn(i, "hi") {|ti, ts|
-#     puts "#{Thread.current} (#{ti}) says #{ts}\n"
-#   }
-# end
-# tpool.shutdown
+# Author:: Daniel Tralamazza
+# License:: {MIT # License.}[http://www.opensource.org/licenses/mit-license.php]
 
 
 require 'thread'
@@ -28,7 +33,7 @@ module ThreadTools
         # if set to true a new worker is created if the pool is empty
         attr_accessor :create_on_spawn
 
-        # _size should be at least 1
+        # *_size* should be at least 1, *_thr_group* (optional) thread group
         def initialize(_size, _thr_group = nil)
             @kill_worker_on_exception = false
             @size = 0
@@ -91,7 +96,7 @@ module ThreadTools
             thr
         end
 
-        def shutdown
+        def shutdown(_sync = true)
             thr = nil
             while !@pool.empty? do
                 @pool_mtx.synchronize do
@@ -100,7 +105,9 @@ module ThreadTools
                 thr[:jobs].clear    # clear any pending job
                 thr[:jobs] << nil   # queue a nil job
                 thr[:sem].release
-                thr.join            # wait here for the thread to die
+                if (_sync)
+                    thr.join        # wait here for the thread to die
+                end
             end
         end
     end

data/test/test_debugmutex.rb

@@ -1,3 +1,8 @@
+# Author:: Daniel Tralamazza
+# Date:: 29 Sep 2009
+#
+
+
 require 'test/unit'
 require File.expand_path(File.dirname(__FILE__)+'/../lib/thread_tools/debugmutex')
 

data/test/test_semaphore.rb

@@ -18,7 +18,7 @@ class SemaphoreTest < Test::Unit::TestCase
         sem.release
         sleep 0.1
         # release should unblock acquire
-        assert_equal(ok, true)
+        assert(ok)
         # semaphore count has to be 0
         assert_equal(sem.count, 0)
     end

data/thread_tools.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
     s.name = %q{thread_tools}
-    s.version = '0.26'
+    s.version = '0.27'
     s.summary = %q{Utilities for threaded apps}
     s.platform = Gem::Platform::RUBY
     s.email = %q{daniel@tralamazza.com}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: thread_tools
 version: !ruby/object:Gem::Version 
-  version: "0.26"
+  version: "0.27"
 platform: ruby
 authors: 
 - Daniel Tralamazza