clean_thread 1.0.0

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in clean_thread.gemspec
+gemspec

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Infonium Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/NEWS.rdoc

@@ -0,0 +1,29 @@
+= Release Notes
+
+== 1.0.0 - 2011-06-28 - Dwayne Litzenberger
+
+- First public release
+
+== 0.5 - 2011-04-04 - Dwayne Litzenberger
+
+- Set the Java thread name (when running under JRuby). This makes debugging
+  with jconsole/JMX easier.
+
+== 0.4 - 2011-02-26 - Dwayne Litzenberger
+
+- Fix bug where ThreadFinish was raised when a thread invoked its own
+  CleanThread#finish method with :nowait=>true.
+
+== 0.3 - 2011-02-24 - Dwayne Litzenberger
+
+- Fix bug where CleanThread#alive? would raise an exception if the thread was
+  not yet started.
+
+== 0.2 - 2010-10-21 - Dwayne Litzenberger
+
+- Removed references to HospitalPortal::Database, use ActiveRecord::Base instead.
+- Add display_exception() method, which outputs exceptions to $stderr by default.
+
+== 0.1 - 2010-02-10 - John Duff
+
+- Removed dependency on HospitalPortal::Database and Java

data/README.rdoc

@@ -0,0 +1,72 @@
+= clean_thread - Support for background threads.
+
+CleanThread helps you create background threads that will exit cleanly upon
+request.
+
+You may either subclass this class and override its main() method, or pass
+a block to CleanThread.new.
+
+Code invoked by CleanThread should check periodically whether the
+thread needs to exit, either by invoking the check_finishing method (which
+raises ThreadFinish if the finish method has been called), or by manually
+checking the result of the finishing? method and exiting if it returns true.
+
+In addition to providing the #finish and #check_finishing methods,
+CleanThread takes care of the following:
+
+- Dumping a backtrace to stderr if there is an exception
+- Setting the Java thread name (if running under JRuby)
+- Releasing ActiveRecord connections (if ActiveRecord is loaded)
+
+= Installation
+
+  gem install clean_thread
+
+= Example Usage
+
+== Overriding CleanThread#main
+
+  require 'clean_thread'
+
+  class MyThread < CleanThread
+    def main
+      loop do
+        check_finishing
+        # ... do some steps
+        check_finishing
+        # ... do some more steps
+        check_finishing
+        # ... do yet more steps
+      end
+    end
+  end
+
+  t = MyThread.new
+  t.start
+  # ...
+  t.finish
+
+== Passing a block to new
+
+  require 'clean_thread'
+
+  t = CleanThread.new do
+    loop do
+      CleanThread.check_finishing
+      # ... do some steps
+      CleanThread.check_finishing
+      # ... do some more steps
+      CleanThread.check_finishing
+      # ... do yet more steps
+    end
+  end
+
+  t.start   # Start the thread
+  # ...
+  t.finish  # Stop the thread
+
+= License
+
+Copyright © 2009-2011 Infonium Inc.
+
+License: See the MIT-LICENSE file.

data/Rakefile

@@ -0,0 +1,7 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |t|
+  t.pattern = 'test/**/*_test.rb'
+end

data/clean_thread.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "clean_thread/version"
+
+Gem::Specification.new do |s|
+  s.name        = "clean_thread"
+  s.version     = CleanThread::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Dwayne Litzenberger"]
+  s.email       = ["dlitz@patientway.com"]
+  s.homepage    = "https://github.com/dlitz/clean_thread"
+  s.summary     = %q{Support for threads that exit cleanly}
+  s.description = <<EOF
+HospitalPortal::CleanThread provides support for developing threads that exit cleanly.
+
+Reliable J2EE deployment requires that all threads started by an application
+are able to exit cleanly upon request.
+EOF
+
+  s.rubyforge_project = "clean_thread"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/lib/clean_thread.rb

@@ -0,0 +1,134 @@
+require 'thread'
+
+class CleanThread
+
+  class ThreadFinish < Exception
+    # NB: Most exceptions should inherit from StandardError, but this is deliberate.
+  end
+
+  # If the current thread was invoked by CleanThread, invoke
+  # CleanThread#check_finishing.
+  def self.check_finishing
+    ct = Thread.current[:clean_thread]
+    return nil if ct.nil?
+    ct.check_finishing
+  end
+
+  # If the current thread was invoked by CleanThread, return the result of
+  # CleanThread#finishing?.  Otherwise, return nil.
+  def self.finishing?
+    ct = Thread.current[:clean_thread]
+    return nil if ct.nil?
+    return ct.finishing?
+  end
+
+  # Initialize a new CleanThread object.
+  #
+  # If a block is given, that block will be executed in a new thread when the
+  # start method is called.  If no block is given, the main method will be used.
+  #
+  # The block is passed the CleanThread instance it belongs to, plus any
+  # arguments passed to the new method.
+  def initialize(*args, &block)
+    @_cleanthread_mutex = Mutex.new
+    @_cleanthread_stopping = false  # locked by _cleanthread_mutex
+    @_cleanthread_thread = nil  # locked by _cleanthread_mutex.  Once set, it is not changed.
+    @_cleanthread_proc = block
+    @_cleanthread_args = args
+  end
+
+  # Start the thread.
+  def start
+    @_cleanthread_mutex.synchronize {
+      if @_cleanthread_thread.nil?
+        @_cleanthread_thread = Thread.new do
+          begin
+            # Set the Java thread name (for debugging)
+            Java::java.lang.Thread.current_thread.name = "#{self.class.name}-#{self.object_id}" if defined?(Java)
+
+            # Set the CleanThread instance (for use with the CleanThread.check_finishing
+            # and CleanThread.finishing? class methods
+            Thread.current[:clean_thread] = self
+
+            if @_cleanthread_proc.nil?
+              main(*@_cleanthread_args)
+            else
+              @_cleanthread_proc.call(self, *@_cleanthread_args)
+            end
+          rescue ThreadFinish
+            # Do nothing - exit cleanly
+          rescue Exception, ScriptError, SystemStackError, SyntaxError, StandardError => exc
+            # NOTE: rescue Exception should be enough here, but JRuby seems to miss some exceptions if you do that.
+            #
+            # Output backtrace, since otherwise we won't see anything until the main thread joins this thread.
+            display_exception(exc)
+            raise
+          ensure
+            # This is needed.  Otherwise, the database connections aren't returned to the pool and things break.
+            ActiveRecord::Base.connection_handler.clear_active_connections! if defined? ActiveRecord::Base
+          end
+        end
+      else
+        raise TypeError.new("Thread already started")
+      end
+    }
+    return nil
+  end
+
+  # Ask the thread to finish, and wait for the thread to stop.
+  #
+  # If the :nowait option is true, then just ask the thread to finish without
+  # waiting for it to stop.
+  #
+  # When a thread invokes its own finish method, ThreadFinish is raised,
+  # unless :nowait is true.
+  def finish(options={})
+    @_cleanthread_mutex.synchronize {
+      raise RuntimeError.new("not started") if @_cleanthread_thread.nil?
+      @_cleanthread_stopping = true
+    }
+    unless options[:nowait]
+      raise ThreadFinish if @_cleanthread_thread == ::Thread.current
+      @_cleanthread_thread.join
+    end
+    return nil
+  end
+
+  # Return true if the thread is alive.
+  def alive?
+    @_cleanthread_thread && @_cleanthread_thread.alive?
+  end
+
+  # Wait for the thread to stop.
+  def join
+    return @_cleanthread_thread.join
+  end
+
+  # Return true if the finish method has been called.
+  def finishing?
+    @_cleanthread_mutex.synchronize { return @_cleanthread_stopping }
+  end
+
+  # Exit the thread if the finish method has been called.
+  #
+  # Functionally equivalent to:
+  #  raise ThreadFinish if finishing?
+  def check_finishing
+    raise ThreadFinish if finishing?
+    return nil
+  end
+
+  protected
+  # Override this method if you want this thread to do something.
+  def main(cleanthread)
+    # default is to do nothing
+  end
+
+  # Override this method if you want the stacktrace output to happen differently
+  def display_exception(exception)
+    lines = []
+    lines << "#{exception.class.name}: #{exception.message}\n"
+    lines += exception.backtrace.map{|line| "\tfrom #{line}"}
+    $stderr.puts lines.join("\n")
+  end
+end

data/lib/clean_thread/version.rb

@@ -0,0 +1,3 @@
+class CleanThread # reopen
+  VERSION = "1.0.0"
+end

data/test/test_helper.rb

@@ -0,0 +1,3 @@
+require 'rubygems'
+require 'test/unit'
+$LOAD_PATH.unshift(File.dirname(__FILE__) + "/../lib")

data/test/unit/cleanthread_test.rb

@@ -0,0 +1,50 @@
+require File.expand_path "../../test_helper", __FILE__
+
+require 'clean_thread'
+
+class CleanThreadTest < Test::Unit::TestCase
+  def test_allow_multple_finish
+    t = CleanThread.new do |t|
+      loop do
+        t.check_finishing
+      end
+    end
+    t.start
+    t.finish
+    assert_nothing_raised do
+      t.finish
+    end
+  end
+
+  def test_allow_multple_finish_with_first_nowait
+    t = CleanThread.new do |t|
+      loop do
+        t.check_finishing
+      end
+    end
+    t.start
+    t.finish(:nowait=>true)
+    sleep 0.1 while t.alive?
+    assert_nothing_raised do
+      t.finish
+    end
+  end
+
+  def test_alive_should_not_raise_error_if_thread_not_yet_started
+    t = CleanThread.new { }
+    assert_nothing_raised do
+      assert !t.alive?
+    end
+  end
+
+  def test_finish_nowait_should_not_raise_exception
+    success = false
+    t = CleanThread.new do |t|
+      t.finish(:nowait=>true)
+      success = true
+    end
+    t.start
+    t.join
+    assert success, "finish(:nowait=>true) should not raise an exception when invoked from within a CleanThread"
+  end
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification 
+name: clean_thread
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: 
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Dwayne Litzenberger
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-06-28 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: |
+  HospitalPortal::CleanThread provides support for developing threads that exit cleanly.
+  
+  Reliable J2EE deployment requires that all threads started by an application
+  are able to exit cleanly upon request.
+
+email: 
+- dlitz@patientway.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- MIT-LICENSE
+- NEWS.rdoc
+- README.rdoc
+- Rakefile
+- clean_thread.gemspec
+- lib/clean_thread.rb
+- lib/clean_thread/version.rb
+- test/test_helper.rb
+- test/unit/cleanthread_test.rb
+has_rdoc: true
+homepage: https://github.com/dlitz/clean_thread
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: clean_thread
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Support for threads that exit cleanly
+test_files: 
+- test/test_helper.rb
+- test/unit/cleanthread_test.rb