JaredKuolt-robustthread 0.5 → 0.5.1

data/README.rdoc

@@ -0,0 +1,74 @@
+Author:: Jared Kuolt (mailto:me@superjared.com)
+Copyright:: Copyright (c) 2009 Jared Kuolt
+License:: MIT License
+
+= RobustThread
+
+This module allows for the creation of a thread that will not simply die when
+the process dies. Instead, it joins all RobustThreads in Ruby's exit handler.
+
+== Installation
+
+  sudo gem install robustthread
+
+== Usage
+
+  rt = RobustThread.new(:args => args, :label => "do_something with x and y") do |x, y|
+    do_something(x, y)
+  end
+
+Options:
+* +args+: arguments passed to the thread
+* +label+: an identifier (used primarily in logs for debugging, defaults to
+  +thread.inspect+)
+
+=== Easy Looping
+
+You can loop a task in a thread to cleanly exit:
+
+  RobustThread.loop(:seconds => 3) do
+    do_something
+  end
+
+Options are the same as RobustThread#new, with the addition of +seconds+, the
+interval at which the Thread will sleep.
+
+=== Exception Handling
+
+Since Threads usually eat exceptions, RobustThread allows for a simple global
+exception handler:
+
+  RobustThread.exception_handler do |exception|
+    # Handle your exceptions here
+  end
+
+If no handler is assigned, the exception traceback will be piped into the
+logger as an error message.
+
+=== Callbacks
+
+RobustThread currently supports 5 callbacks. The following 4 are called per
+RobustThread.
+
+  RobustThread.add_callback(:before_init){ puts "Before init!" }
+  RobustThread.add_callback(:before_yield){ puts "Before yield!" }
+  RobustThread.add_callback(:after_yield){ puts "After yield!" }
+  RobustThread.add_callback(:after_join){ puts "After join!" }
+
+The +before_exit+ callback is called after all threads are re-joined.
+
+  RobustThread.add_callback(:before_exit){ puts "Before exit!" }
+
+=== Etc...
+
+If necessary, you can access the actual thread from the RobustThread
+object via its +thread+ attribute.
+
+  rt.thread
+  => #<Thread:0x7fa1ea57ff88 run>
+
+By default, RobustThread uses a Logger that defaults itself to STDOUT. You
+can change this by assigning the +logger+ class attribute to a different 
+Logger object:
+
+  RobustThread.logger = Logger.new(STDERR)

data/lib/robustthread.rb

@@ -1,6 +1,9 @@
 # Author:: Jared Kuolt (mailto:me@superjared.com)
 # Copyright:: Copyright (c) 2009 Jared Kuolt
 # License:: MIT License
+#
+# See README.rdoc[link:files/README_rdoc.html] for usage
+#
 require 'logger'
 require 'timeout'
 
@@ -35,7 +38,7 @@ class RobustThread
   ## Class methods and attributes
   class << self
     attr_accessor :logger, :say_goodnight, :exit_handler_initialized, :callbacks
-    VALID_CALLBACKS = [:before_init, :before_yield, :after_yield, :after_join]
+    VALID_CALLBACKS = [:before_init, :before_yield, :after_yield, :after_join, :before_exit]
 
     # Logger object (see README)
     def logger
@@ -115,10 +118,11 @@ class RobustThread
         self.say_goodnight = true
         begin
           self.group.each do |rt|
-            log "waiting on #{rt.label.inspect}"
+            log "waiting on #{rt.label.inspect}" if rt.thread.alive?
             rt.thread.join
             rt.class.send :do_after_join
           end
+          self.send :do_before_exit
           log "exited cleanly"
         rescue Interrupt
           log "prematurely killed by interrupt!", :error

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: JaredKuolt-robustthread
 version: !ruby/object:Gem::Version 
-  version: "0.5"
+  version: 0.5.1
 platform: ruby
 authors: 
 - Jared Kuolt
@@ -19,10 +19,11 @@ executables: []
 
 extensions: []
 
-extra_rdoc_files: []
-
+extra_rdoc_files: 
+- README.rdoc
 files: 
 - lib/robustthread.rb
+- README.rdoc
 has_rdoc: true
 homepage: http://github.com/JaredKuolt/robustthread/tree/master
 post_install_message: