stud 0.0.21 → 0.0.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 085ea35fd8932fd05459cfac97723d37f1d876c8
-  data.tar.gz: 63f9bd5fa6a0f601cc226973b9a88c615ecdeacf
+  metadata.gz: a6052e9a657a08c734e6ca7326edc7e86e402305
+  data.tar.gz: 9c681e29d45145e0df76800b6821d198c3003c57
 SHA512:
-  metadata.gz: d64c0a9a164945bb663b59ba800bdbc94da61ffc8cd5703b4440b74d26bc298b30706735fafc469a8513307015c5dc0623a8dca71c9076cc3ae64ae2b2c4666e
-  data.tar.gz: ef490bdc0feb1520ad1fad2af1d725c90bc7abb342001b885b4d8cee4953c00880a3edd4ef360d94ecfe82bead3220735690c7deddfd49d9b28c75268c00e0ba
+  metadata.gz: 3ac208ff1766b0f2827e8239e4739d344bbedff9dd6f9e6d84d4ffba3fd3314e7db6dffda9bea63ee3f61499d1dc1865058837762adb9ad29e9bcdbfb42878f9
+  data.tar.gz: 07308bf3b065d429e16802786e4f571321cb31735b784d207619410b63b8d58c0d41ff6d5ee83f327fe602605b74eeb27bcd4aead1cb9d3ab7b9e286f5463fdf

data/lib/stud/interval.rb

@@ -1,5 +1,8 @@
-require "stud/task"
+require "thread"
+
 module Stud
+  STUD_STOP_REQUESTED = :stud_stop_requested
+
   # This implementation tries to keep clock more accurately.
   # Prior implementations still permitted skew, where as this one
   # will attempt to correct for skew.
@@ -9,30 +12,99 @@ module Stud
   def self.interval(time, opts = {}, &block)
     start = Time.now
     while true
-      break if Task.interrupted?
       if opts[:sleep_then_run]
         start = sleep_for_interval(time, start)
+        break if stop?
         block.call
       else
         block.call
         start = sleep_for_interval(time, start)
+        break if stop?
       end
     end # loop forever
   end # def interval
 
+  def interval(time, opts = {}, &block)
+    Stud.interval(time, opts, &block)
+  end # def interval
+
+  # stop! instructs interval to stop and exit its execution loop before going to
+  # sleep between block executions.
+  # NOW the tricky part is: this is typically an operation that will be called
+  # from another thread than the thread running the interval loop in which case
+  # the target parameter must be set to the Thread object which is running the
+  # interval loop.
+  # Note that the stop logic is compatible with Stud::Task so if interval is run
+  # inside a Stud::Task, calling Stud::Task#stop! will stop the interval the same
+  # way as calling stop! on the interval itself.
+  # @param target [Thread] the target thread to stop, defaut to Thread.current
+  def self.stop!(target = Thread.current)
+    # setting/getting threalocal var is thread safe in JRuby
+    target[STUD_STOP_REQUESTED] = true
+    target.wakeup
+    nil
+  end
+
+  # stop? returns true if stop! has been called
+  # @param target [Thread] the target thread to check for stop, defaut to Thread.current
+  # @return [Boolean] true if the stop! has been called
+  def self.stop?(target = Thread.current)
+    # setting/getting threalocal var is thread safe in JRuby
+    target[STUD_STOP_REQUESTED]
+  end
+
+  class << Stud
+    # also support Stud.interrupted? for backward compatibility.
+    alias_method :interrupted?, :stop?
+  end
+
+  # stoppable_sleep will try to sleep for the given duration seconds (which may be any number,
+  # including a Float with fractional seconds). an optional stop_condition_block can be supplied
+  # to verify for sleep interruption if the block returns a truthy value. if not block is supplied
+  # it will check for the Stud.stop? condition. this check will be performed at 1s interval
+  # by default or you can supply a different stop_condition_interval.
+  #
+  # note that to achieve this, stoppable_sleep will actually perform a series of incremental sleeps
+  # but will try accurately spend the requested duration period in the overall stoppable_sleep method call.
+  # in other words this means that the duration supplied will be accurate for the time spent in
+  # the stoppable_sleep method not the actual total time spent in the underlying multiple sleep calls.
+  #
+  # @param duration [Numeric] sleep time in (fractional) seconds
+  # @param stop_condition_interval [Numeric] optional interval in (fractional) seconds to perform the sleep interruption verification, default is 1s
+  # @param stop_condition_block [Proc] optional sleep interruption code block that must evaluate to a truthy value, default is to use Stud.stop?
+  # @return [Numeric] the actual duration in (fractional) seconds spent in stoppable_sleep
+  def self.stoppable_sleep(duration, stop_condition_interval = 1.0, &stop_condition_block)
+    sleep_start = Time.now
+
+    # default to using Stud.stop? as the condition block
+    stop_condition_block ||= lambda { stop? }
+
+    while (remaining_duration = (duration - (Time.now - sleep_start))) >= stop_condition_interval
+      # sleep X if there is more than X remaining to sleep in relation to the loop start time
+      sleep(stop_condition_interval)
+
+      return(Time.now - sleep_start) if stop_condition_block.call
+    end
+
+    # here we know we have less than 1s reminding to sleep,
+    sleep(remaining_duration) if remaining_duration > 0.0
+
+    Time.now - sleep_start
+  end
+
+  private
+
   def self.sleep_for_interval(time, start)
     duration = Time.now - start
-    # Sleep only if the duration was less than the time interval
+
+    # sleep only if the duration was less than the time interval
     if duration < time
-      sleep(time - duration)
+      stoppable_sleep(time - duration)
       start += time
     else
-      # Duration exceeded interval time, reset the clock and do not sleep.
+      # duration exceeded interval time, reset the clock and do not sleep.
       start = Time.now
     end
   end
 
-  def interval(time, opts = {}, &block)
-    return Stud.interval(time, opts, &block)
-  end # def interval
 end # module Stud

data/lib/stud/task.rb

@@ -1,7 +1,19 @@
 require "thread"
+require "stud/interval"
 
 module Stud
+
+  # A Task spawns a thread to execute the given block. execution completion and result retrieval is
+  # done using the Task#wait method. A Task is run once and the thread exists upon block completion.
+  # A task and its underlying thread are not reusable.
+  #
+  # Task does not provide a mean to force-interrupt a running task, it only provides the #stop!
+  # method to signal the task for a stop request. The task or code block can use the #stop? method
+  # to check for a stop request. Note that the #stop! and #stop? methods are thread safe.
   class Task
+    # provide access to the underlying thread if ever needed.
+    attr_reader :thread
+
     def initialize(*args, &block)
       # A queue to receive the result of the block
       # TODO(sissel): Don't use a queue, just store it in an instance variable.
@@ -17,6 +29,10 @@ module Stud
       end # thread
     end # def initialize
 
+    # wait waits for the task thread to complete and return the block return value
+    # if the block raises an exception, this exception is propagated in this
+    # wait method.
+    # @return [Object, Exception] block return value
     def wait
       @thread.join
       reason, result = @queue.pop
@@ -29,12 +45,20 @@ module Stud
       end
     end # def wait
 
+    # stop! requests the task to stop. the Thread#wakeup method is also
+    # called so that a sleeping task is waked up and has a chance to verify
+    # the stop request using the #stop? method. also see Stud.stop!
     def stop!
-      Thread.current[:stud_task_interrupted] = true
+      Stud.stop!(@thread)
     end
 
-    def self.interrupted?
-      Thread.current[:stud_task_interrupted]
+    # stop? returns true if this task stop! has been called
+    # See Stud.stop?
+    # @return [Boolean] true if the stop! has been called
+    def stop?
+      Stud.stop?(@thread)
     end
+    alias_method :interrupted?, :stop?
+
   end # class Task
 end # module Stud

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stud
 version: !ruby/object:Gem::Version
-  version: 0.0.21
+  version: 0.0.22
 platform: ruby
 authors:
 - Jordan Sissel
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-08-04 00:00:00.000000000 Z
+date: 2015-09-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -77,8 +77,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 2.4.6
 signing_key: 
 specification_version: 4
 summary: stud - common code techniques
 test_files: []
+has_rdoc: