timemachine 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e7ac7abf883d644a39c82488c2b68d3101ca88be93def55b73936bb63763088
-  data.tar.gz: 109ad5b6a6332a35749b30b49f73c0275afdbcae6e8e57e7da97baf612f6cafa
+  metadata.gz: 412ae253c1cf57715d748a498fe09daf146813c9ec7e9592ca6eccfd6e905b8c
+  data.tar.gz: 767286f421b3706e1ae7e9ad7c69c5c26ddf2808494e03f67bf7d1beba29523c
 SHA512:
-  metadata.gz: d7da01766f279c03906c5727d8891c02cb50bf38707e37d277fc3d6929453fc0f51f1504c0954ac513ebc9d91ee1fc80b710e0918ef02450a35e319239ba99ac
-  data.tar.gz: c29e266dfdc9b98736b76ff784921a8abc6000b733f0aca397ba2cfbc5e8066e71766d6dd020c77129a7df9e6692b6744e8d7b9d4b8b3f2bd5822ad72a13e583
+  metadata.gz: 521d3ec7fd877e8b42532fc371044b7bc6d5bcf45ffd5905be5a708d00579973be49e57937af99a2e85208b8d448839bea76b07a12475713c33d480184b472fc
+  data.tar.gz: dc7e27cc48e54c8d4a3ded22d3e4a5e11da96183389f2864bdb71e028340555d9deb52c9bd4aa2461c2e81c1ef5c790c382977a23859f6a5c139e2995e77bdaf

data/lib/executor.rb

@@ -1,7 +1,15 @@
 # frozen_string_literal: true
 
 module TimeMachine
+  #
+  # Executors contains executor interface and implementations.
+  # An executor is where a timed-up task is actually executed,
+  # thus decoupled with the scheduler.
+  #
   module Executors
+    #
+    # The base class (interface) for a executor.
+    #
     class Executor
       def execute(&block)
         raise NotImplementedError

data/lib/thread_executor.rb

@@ -4,6 +4,11 @@ require 'executor'
 
 module TimeMachine
   module Executors
+    #
+    # ThreadExecutor is currently the only implementation of Executor.
+    # It executes the task in a background thread, so slow tasks will not
+    # block the scheduler.
+    #
     class ThreadExecutor < Executor
       def execute(&block)
         Thread.new(&block)

data/lib/timemachine.rb

@@ -2,18 +2,48 @@
 
 require 'thread_executor'
 
+#
+# Namespace TimeMachine contains all the magics of this gem.
+#
 module TimeMachine
+
+  #
+  # The internal struct to store a task.
+  #
   TimedTask = Struct.new(:handle, :timeup, :block)
+
+  #
+  # The struct to store the result of a task.
+  #
   TaskResult = Struct.new(:handle, :status, :record_result, :result)
 
+  #
+  # `DuplicateHandleError` is thrown when the handle (name) for a new task collides with a existing one.
+  #
   class DuplicateHandleError < RuntimeError; end
 
+  #
+  # The core of this gem, which is responsible for scheduling tasks.
+  #
   class TimeMachine
+    # Default timeout of the scheduler, used when the scheduler is idle.
     SCHEDULER_DEFAULT_TIMEOUT = 3
+
+    # Length of the handle generated by `TimeMachine`.
     RANDOM_HANDLE_LENGTH = 16
+
     private_constant :SCHEDULER_DEFAULT_TIMEOUT
 
     public
+    #
+    # Create a new `TimeMachine`.
+    #
+    # @param [Executors::Executor] executor The task executor to be used. Defaults to a `Executors::ThreadExecutor`.
+    # @param [Boolean] more_timely Use a lock in scheduler. This avoids a border case that a task is submitted while
+    #   the scheduler is scheduling, thus not asleep. If `more_timely` is set to `false` in such case, the task
+    #   submission will not effectively preempt the scheduler, and will have to wait one more round before it is scheduled,
+    #   and therefore may cause a slight delay.
+    #
     def initialize(executor= Executors::ThreadExecutor.new, more_timely=false)
       @running = false
       @timeout_queue = []
@@ -28,6 +58,18 @@ module TimeMachine
       @user_mut = Mutex.new
     end
 
+    #
+    # Execute the given block at the given timeup.
+    #
+    # @param [Time] timeup The time to invoke the given block
+    # @param [String] name A custom name (handle) for the task. If `nil`, one will be generated. If specified,
+    #   should not be duplicate with an existing one.
+    # @param [Boolean] record_result Whether to save the result after completion.
+    # @param [Proc] &block The block to execute.
+    #
+    # @return [String] A handle to the task, either the name passed in (if given) or generated by `TimeMachine`.
+    #   Can be used to cancel the task or query task status and result (if `record_result` is set).
+    #
     def at(timeup, name: nil, record_result: false, &block)
       handle = name || _generate_handle
 
@@ -44,16 +86,46 @@ module TimeMachine
       handle
     end
 
+    #
+    # Execute the given block after given timeout.
+    #
+    # @param [Float] timeout Timeout in seconds.
+    # @param [String] name A custom name (handle) for the task. If `nil`, one will be generated. If specified,
+    #   should not be duplicate with an existing one.
+    # @param [Boolean] record_result Whether to save the result after completion.
+    # @param [Proc] &block The block to execute.
+    #
+    # @return [String] A handle to the task, either the name passed in (if given) or generated by `TimeMachine`.
+    #   Can be used to cancel the task or query task status and result (if `record_result` is set).
+    #
     def after(timeout, name: nil, record_result: false, &block)
       at(Time.now + timeout, name: name, record_result: record_result, &block)
     end
 
+    #
+    # Get the result of a given block.
+    #
+    #
+    # @param [String] handle The handle to the task, typically returned by previous `at` and `after` calls.
+    #
+    # @return [TaskResult] The result of the given task. If not found, or the task is finished with `record_result`
+    #   unset, returns `nil`.
+    #
     def get_result(handle)
       @user_mut.synchronize do
         @result_queue[handle]
       end
     end
 
+    #
+    # Get the result of a given block, and delete it from `TimeMachine`'s internal storage if it is finished or cancelled.
+    # *Remember to call this, or the results will pile up and eat your memory!*
+    #
+    # @param [String] handle The handle to the task, typically returned by previous `at` and `after` calls.
+    #
+    # @return [TaskResult] The result of the given task. If not found, or the task is finished with `record_result`
+    #   unset, returns `nil`. If the task is finished or cancelled, it will be deleted from `TimeMachine` storage as well.
+    #
     def pop_result(handle)
       @user_mut.synchronize do
         res = @result_queue[handle]
@@ -65,6 +137,13 @@ module TimeMachine
       end
     end
 
+    #
+    # Cancel a previously submitted task.
+    # Be sure to cancel it in time if you mean to cancel it.
+    # *If the task has already been scheduled or executed, cancel may not take effect.*
+    #
+    # @param [String] handle The handle to the task, typically returned by previous `at` and `after` calls.
+    #
     def cancel(handle)
       @user_mut.synchronize do
         @cancel_queue << handle
@@ -72,6 +151,9 @@ module TimeMachine
       _bg_wakeup
     end
 
+    #
+    # Start the `TimeMachine`. This will create a background scheduler thread.
+    #
     def start()
       @user_mut.synchronize do
         return if @running
@@ -80,6 +162,9 @@ module TimeMachine
       end
     end
 
+    #
+    # Stop the `TimeMachine`. All tasks due after this call will be cancelled.
+    #
     def stop()
       @user_mut.synchronize do
         return unless @running
@@ -100,7 +185,7 @@ module TimeMachine
 
     def _bg_wakeup
       @scheduler_mut&.lock
-      @scheduler_thread.run
+      @scheduler_thread&.run
       @scheduler_mut&.unlock
     end
 
@@ -135,10 +220,11 @@ module TimeMachine
         @scheduler_mut&.lock        
       end
       @scheduler_mut&.unlock
+      @scheduler_thread = nil
     end
 
     def _bg_enqueueTask(task)
-      return if @result_queue[task.handle].status != :UNSCHEDULED
+      return if @result_queue[task.handle]&.status != :UNSCHEDULED
 
       @result_queue[task.handle].status = :PENDING
       @timeout_queue.insert(@timeout_queue.index do |t|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: timemachine
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - LTW