procrastinator 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86ce767f3807bc5184e0d658392cbf45b03ab68465a5161c8ffd9434157bd007
-  data.tar.gz: 65b3b517a6bdd6150b34ee0e8419834f581abbe1ced3d1ae5aef50613a452c94
+  metadata.gz: 49bfb07d03e59388e8deefc6fa6eaea6342cf973943f3ce7ccbaa3835095e768
+  data.tar.gz: 498838544ce3371270b8a71f076820811b9a8c51b6b8227725be5ab4c59f8dac
 SHA512:
-  metadata.gz: e00357dccd1ac7bdbc2ce72fdaada932f3155b155c88c4af8ccd7674f1db196cd186b0f96a3c1b99f2751cf30652f77fabcfab733e091539e3748b90fe04c0ac
-  data.tar.gz: ee3425d98d5eca4d321e36b37428e50300cad78db202b34ef4150058c3a2a42fd0452f76015e51f3d5830c8e289f823e3d1e94aa086edcd694fb5d412558bdee
+  metadata.gz: e779c44fbd3edab3d32f387d20563a7c2a7d00acb270e567370692a78b0520bf11aa9fd9ce65cb205894ffd7a7f18e09839a4ca72571e9b0e5b2cf814d3a0470
+  data.tar.gz: c7235fec5d0db4dbf2d201e55e36d719750ea2a3875eca9ede878d054c55e1abd627319a686b082a402d7c62745831f2bee180f87a85b78c0c0c74ab1285bf57

data/.rubocop.yml

@@ -4,7 +4,7 @@ AllCops:
   Exclude:
     - 'bin/*'
 
-  TargetRubyVersion: 3.0
+  TargetRubyVersion: 3.3
 
 Layout/LineLength:
   Exclude:
@@ -14,6 +14,10 @@ Layout/LineLength:
 Layout/FirstArrayElementIndentation:
   IndentationWidth: 6
 
+# setting to 6 to match RubyMine autoformat
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented_relative_to_receiver
+  IndentationWidth: 6
 
 # rspec blocks are huge by design
 Metrics/BlockLength:
@@ -23,3 +27,30 @@ Metrics/BlockLength:
 Metrics/ModuleLength:
   Exclude:
     - 'spec/**/*.rb'
+
+# Disabling because it's marginally better, if at all, and not worth rewriting all step descripts right now
+RSpec/ExampleWording:
+  Enabled: false
+
+# My style is often to use multiple smaller expectations in a row instead of one giant one
+RSpec/MultipleExpectations:
+  Enabled: false
+
+# My style is often to abuse contexts for logical grouping
+RSpec/ContextWording:
+  Enabled: false
+
+# TODO: re-enable when FakeFS is removed
+RSpec/AnyInstance:
+  Enabled: false
+
+# Not convinced described_class is better. Makes everything harder to track mentally.
+RSpec/DescribedClass:
+  Enabled: false
+
+# TODO: re-enable and replace generic doubles with verifying ones
+RSpec/VerifiedDoubles:
+  Enabled: false
+
+RSpec/MultipleMemoizedHelpers:
+  Max: 7

data/.ruby-version

@@ -1 +1 @@
-ruby-3.1.4
+ruby-3.4.5

data/Gemfile

@@ -5,10 +5,13 @@ source 'https://rubygems.org'
 group :development do
    gem 'bundler', '~> 2.3'
    gem 'fakefs', '~> 1.8'
+   gem 'mutex_m', '~> 0.3' # for 'debase' debugger
    gem 'rake', '~> 13.0'
    gem 'rspec', '~> 3.12'
-   gem 'rubocop', '~> 1.52'
-   gem 'rubocop-performance', '~> 1.18'
+   gem 'rubocop', '~> 1.79'
+   gem 'rubocop-performance', '~> 1.25'
+   gem 'rubocop-rake', '~> 0.7'
+   gem 'rubocop-rspec', '~> 3.6'
    gem 'simplecov', '~> 0.22.0'
    gem 'timecop', '~> 0.9'
    gem 'yard', '~> 0.9'

data/README.md

@@ -53,15 +53,15 @@ scheduler.defer(:birthday, run_at: Time.now + 3600, data: {user_id: 5})
         - [CSV Task Store](#csv-task-store)
         - [Shared Task Stores](#shared-task-stores)
     + [Task Container](#task-container)
+    + [Process Priority](#process-priority)
 * [Deferring Tasks](#deferring-tasks)
     + [Timing](#timing)
     + [Rescheduling Existing Tasks](#rescheduling-existing-tasks)
     + [Retries](#retries)
     + [Cancelling](#cancelling)
+* [Testing with Procrastinator](#testing-with-procrastinator)
+    + [RSpec Matchers](#rspec-matchers)
 * [Running Tasks](#running-tasks)
-    + [In Testing](#in-testing)
-        - [RSpec Matchers](#rspec-matchers)
-    + [In Production](#in-production)
 * [Similar Tools](#similar-tools)
     + [Linux etc: Cron and At](#linux-etc--cron-and-at)
     + [Gem: Resque](#gem--resque)
@@ -140,12 +140,12 @@ Task Handlers have attributes that are set after the Handler is created. The att
 the tasks from referencing unknown variables at whatever time they are run - if they're missing, you'll get
 a `MalformedTaskError`.
 
-| Attribute  | Required | Description | 
-|------------|----------|-------------|
-|`:container`| Yes   | Container declared in `#setup` from the currently running instance |
-|`:logger`   | Yes   | Logger object for the Queue |
-|`:scheduler`| Yes   | A scheduler object that you can use to schedule new tasks (eg. with `#defer`)|
-|`:data`     | No       | Data provided to `#defer`. Calls to `#defer` will error if they do not provide data when expected and vice-versa. |
+| Attribute    | Required | Description                                                                                                       | 
+|--------------|----------|-------------------------------------------------------------------------------------------------------------------|
+| `:container` | Yes      | Container declared in `#setup` from the currently running instance                                                |
+| `:logger`    | Yes      | Logger object for the Queue                                                                                       |
+| `:scheduler` | Yes      | A scheduler object that you can use to schedule new tasks (eg. with `#defer`)                                     |
+| `:data`      | No       | Data provided to `#defer`. Calls to `#defer` will error if they do not provide data when expected and vice-versa. |
 
 ### Errors & Logging
 
@@ -184,10 +184,10 @@ end
 
 Some events are always logged by default:
 
-|event               |level  |
-|--------------------|-------|
-|Task completed      | INFO  |
-|Task cailure        | ERROR |
+| event          | level |
+|----------------|-------|
+| Task completed | INFO  |
+| Task cailure   | ERROR |
 
 ## Configuration
 
@@ -220,12 +220,12 @@ config.define_queue :greeting, SendWelcomeEmail, store: 'procrastinator.csv', ti
 
 Description of keyword options:
 
-| Option           | Description   |
-|------------------| ------------- |
-| `:store`         | Storage IO object for tasks. See [Task Store](#task-store)     |
-| `:timeout`       | Max duration (seconds) before tasks are failed for taking too long  |
+| Option           | Description                                                                         |
+|------------------|-------------------------------------------------------------------------------------|
+| `:store`         | Storage IO object for tasks. See [Task Store](#task-store)                          |
+| `:timeout`       | Max duration (seconds) before tasks are failed for taking too long                  |
 | `:max_attempts`  | Once a task has been attempted `max_attempts` times, it will be permanently failed. |
-| `:update_period` | Delay (seconds) between reloads of all tasks from the task store  |
+| `:update_period` | Delay (seconds) between reloads of all tasks from the task store                    |
 
 ### Task Store
 
@@ -275,8 +275,8 @@ _Warning_: Task stores shared between queues **must** be thread-safe if using th
 These are the data fields for each individual scheduled task. When using the built-in task store, these are the field
 names. If you have a database, use this to inform your table schema.
 
-|  Hash Key         | Type     | Description                                                             |
-|-------------------|----------| ------------------------------------------------------------------------|
+| Hash Key          | Type     | Description                                                             |
+|-------------------|----------|-------------------------------------------------------------------------|
 | `:id`             | integer  | Unique identifier for this exact task                                   |
 | `:queue`          | symbol   | Name of the queue the task is inside                                    | 
 | `:run_at`         | datetime | Time to attempt running the task next. Updated for retries¹             |
@@ -285,7 +285,7 @@ names. If you have a database, use this to inform your table schema.
 | `:attempts`       | integer  | Number of times the task has tried to run                               |
 | `:last_fail_at`   | datetime | Time of the most recent failure                                         |
 | `:last_error`     | string   | Error message + backtrace of the most recent failure. May be very long. |
-| `:data`           | JSON     | Data to be provided to the task handler, serialized² to JSON.            |
+| `:data`           | JSON     | Data to be provided to the task handler, serialized² to JSON.           |
 
 ¹ `nil` indicates that it is permanently failed and will never run, either due to expiry or too many attempts.
 
@@ -350,6 +350,23 @@ class LunchTask
 end
 ```
 
+### Process Priority
+
+The whole Procrastinator process may be made less urgent by providing an `adjust_priority` value (aka nice level
+adjustment).
+
+If not provided, Procrastinator will assume a priority adjustment of 1.
+
+```ruby
+Procrastinator.setup do |config|
+   config.adjust_priority 10 # higher numbers are less urgent. This increases the default priority by 10
+
+   # .. other setup stuff ...
+end
+```
+
+If you want a negative priority nice value, then use system tools like `renice` at your own discretion.
+
 ## Deferring Tasks
 
 To add tasks to a queue, call `#defer` on the scheduler returned by `Procrastinator.setup`:
@@ -532,7 +549,8 @@ end
 ```
 
 > **Note:** There can be a distinction between process full title (`/proc/*/cmdline`) vs the shorter name
-> (`/proc/*/comm`). Some tools like `ps`  and `top` display the process title, while others like `pstree` show the process name.
+> (`/proc/*/comm`). Some tools like `ps`  and `top` display the process title, while others like `pstree` show the
+> process name.
 >
 > Procrastinator uses Ruby's `Process.setproctitle`, which only affects the title.
 

data/RELEASE_NOTES.md

@@ -1,6 +1,36 @@
 # Release Notes
 
-## 2.0.0 (2023-06-17)
+## [Unreleased]
+
+### Major Changes
+
+* none
+
+### Minor Changes
+
+* none
+
+### Bugfixes
+
+* none
+
+## [2.1.0] (2025-08-16)
+
+### Major Changes
+
+* none
+
+### Minor Changes
+
+* Added process priority nice value handling
+* Improved MultiIO implementation to avoid clobbering class methods
+* Updated minimum ruby to 3.3
+
+### Bugfixes
+
+* Compatible with Ruby 3.4.5
+
+## [2.0.0] (2023-06-17)
 
 ### Major Changes
 
@@ -14,7 +44,7 @@
 
 * none
 
-## 1.2.0 (2023-06-17)
+## [1.2.0] (2023-06-17)
 
 ### Major Changes
 
@@ -28,7 +58,7 @@
 
 * When logging is disabled, it points to `File::NULL` instead of a dead-end StringIO
 
-## 1.1.0 (2022-10-16)
+## [1.1.0] (2022-10-16)
 
 ### Major Changes
 
@@ -44,7 +74,7 @@
     * Fixed have_task handling of nested matchers like be_within
     * Improved have_task handling of string queue names vs symbols
 
-## 1.0.1 (2022-09-20)
+## [1.0.1] (2022-09-20)
 
 ### Major Changes
 
@@ -58,7 +88,7 @@
 
 * Fixed integration error in rescheduling tasks
 
-## 1.0.0 (2022-09-18)
+## [1.0.0] (2022-09-18)
 
 ### Major Changes
 

data/lib/procrastinator/config.rb

@@ -23,7 +23,9 @@ module Procrastinator
    # @!attribute [r] :log_shift_size
    #    @return [Integer] Filesize before rotating to a new logfile (see Ruby Logger for details)
    class Config
-      attr_reader :queues, :log_dir, :log_level, :log_shift_age, :log_shift_size, :container
+      attr_reader :queues, :log_dir, :log_level, :log_shift_age, :log_shift_size, :container, :priority
+
+      alias nice priority
 
       # Default directory to keep logs in.
       DEFAULT_LOG_DIRECTORY = Pathname.new('log').freeze
@@ -45,6 +47,9 @@ module Procrastinator
           msg].join("\t") << "\n"
       end
 
+      # Default priority 'nice' level.
+      DEFAULT_PRIORITY = 1
+
       def initialize
          @queues         = []
          @container      = nil
@@ -52,6 +57,7 @@ module Procrastinator
          @log_level      = Logger::INFO
          @log_shift_age  = DEFAULT_LOG_SHIFT_AGE
          @log_shift_size = DEFAULT_LOG_SHIFT_SIZE
+         @priority       = DEFAULT_PRIORITY
 
          with_store(csv: TaskStore::SimpleCommaStore::DEFAULT_FILE) do
             if block_given?
@@ -109,7 +115,9 @@ module Procrastinator
 
             properties[:store] = interpret_store(properties[:store]) if properties.key? :store
 
-            @queues << Queue.new(**{name: name, task_class: task_class, store: @default_store}.merge(properties))
+            args = {name: name, task_class: task_class, store: @default_store}.merge(properties)
+
+            @queues << Queue.new(**args)
          end
 
          # Sets details of logging behaviour
@@ -124,6 +132,19 @@ module Procrastinator
             @log_shift_age  = shift_age
             @log_shift_size = shift_size
          end
+
+         # Sets the desired process 'nice' priority value adjustment. This value is added to whatever runtime priority
+         # Procrastinator starts with.
+         #
+         # Higher numbers are more nice to other processes (lower priority); think of it as the position in line.
+         # You can be more nice, but never less nice.
+         #
+         # @param new_priority [Number] the new priority.
+         def adjust_priority(new_priority)
+            @priority = new_priority
+         end
+
+         alias adjust_nice adjust_priority
       end
 
       include DSL

data/lib/procrastinator/logged_task.rb

@@ -19,7 +19,7 @@ module Procrastinator
       alias task __getobj__
 
       def initialize(task, logger: Logger.new(StringIO.new))
-         super task
+         super(task)
          @logger = logger || raise(ArgumentError, 'Logger cannot be nil')
       end
 

data/lib/procrastinator/queue.rb

@@ -94,7 +94,9 @@ module Procrastinator
             raise AmbiguousTaskFilterError, "too many (#{ tasks.size }) tasks match #{ identifier }. Found: #{ tasks }"
          end
 
-         TaskMetaData.new(**tasks.first.merge(queue: self))
+         args = tasks.first.merge(queue: self)
+
+         TaskMetaData.new(**args)
       end
 
       # Creates a task on the queue, saved using the Task Store strategy.

data/lib/procrastinator/scheduler.rb

@@ -34,7 +34,7 @@ module Procrastinator
 
       # Alters an existing task to run at a new time, expire at a new time, or both.
       #
-      # Call #to on the result and pass in the new :run_at and/or :expire_at.
+      # Call UpdateProxy#to on the result and pass in the new :run_at and/or :expire_at.
       #
       # Example:
       #
@@ -92,6 +92,11 @@ module Procrastinator
             @identifier = identifier.merge(queue: queue.name.to_sym)
          end
 
+         # Updates the task found by the identifier to run at and/or expire at the new provided time.
+         #
+         # @raise [NoSuchTaskError] when no task matches the identifier.
+         # @raise [AmbiguousTaskFilterError] when many tasks match the identifier, meaning you need to be more specific.
+         # @see Scheduler#reschedule
          def to(run_at: nil, expire_at: nil)
             task = @queue.fetch_task(@identifier)
 
@@ -227,12 +232,14 @@ module Procrastinator
                @streams = stream
             end
 
-            (IO.methods << :path << :sync=).uniq.each do |method_name|
-               define_method(method_name) do |*args|
-                  able_streams(method_name).collect do |stream|
-                     stream.send(method_name, *args)
-                  end.last # forces consistent return result type for callers (but may lose some info)
-               end
+            def method_missing(method_name, *args)
+               able_streams(method_name).collect do |stream|
+                  stream.send(method_name, *args)
+               end.last # forces consistent return result type for callers (but may lose some info)
+            end
+
+            def respond_to_missing?(method_name, include_private)
+               @streams.any? { |stream| stream.respond_to?(method_name, include_private) }
             end
 
             private
@@ -314,6 +321,7 @@ module Procrastinator
 
             manage_pid pid_path
             rename_process pid_path
+            update_priority
          rescue StandardError => e
             @logger&.fatal ([e.message] + e.backtrace).join("\n")
             raise e
@@ -368,6 +376,16 @@ module Procrastinator
             Process.setproctitle name
          end
 
+         def update_priority
+            new_priority     = @config.priority
+            current_priority = Process.getpriority(Process::PRIO_PROCESS, 0)
+
+            raise ArgumentError, 'Process priority cannot be negative. Use system tools if you need a reduced nice value.' if new_priority.negative?
+
+            # second arg "integer" arg of zero means self
+            Process.setpriority(Process::PRIO_PROCESS, 0, current_priority + new_priority)
+         end
+
          include ThreadedWorking
       end
 

data/lib/procrastinator/task_store/simple_comma_store.rb

@@ -142,7 +142,7 @@ module Procrastinator
          class CSVFileTransaction < FileTransaction
             # (see FileTransaction#transact)
             def transact(writable: nil)
-               super(writable: writable) do |file_str|
+               super do |file_str|
                   yield(parse(file_str))
                end
             end

data/lib/procrastinator/test/mocks.rb

@@ -34,6 +34,50 @@ module Procrastinator
          end
       end
 
+      # Testing mock Task class that requires a data packet
+      class MockTaskWithData
+         attr_accessor :container, :logger, :scheduler, :data
+
+         # Records that the mock task was run.
+         def run
+            @run = true
+         end
+
+         # @return [Boolean] Whether the task was run
+         def run?
+            @run
+         end
+      end
+
+      # Testing mock Thread class
+      class MockThread
+         attr_reader :status
+
+         def initialize(name: nil, status: nil)
+            @name   = name
+            @status = status
+         end
+
+         def join(_timeout)
+         end
+
+         def kill
+         end
+
+         def alive?
+            true
+         end
+
+         def thread_variable_get(var_name)
+            case var_name
+            when :name
+               @name
+            else
+               raise 'test error: undefined thread var'
+            end
+         end
+      end
+
       # Data-accepting MockTask
       #
       # @see MockTask

data/lib/procrastinator/version.rb

@@ -2,5 +2,5 @@
 
 module Procrastinator
    # Version number of this release
-   VERSION = '2.0.0'
+   VERSION = '2.1.0'
 end

data/procrastinator.gemspec

@@ -23,5 +23,8 @@ Gem::Specification.new do |spec|
    spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
    spec.require_paths = ['lib']
 
-   spec.required_ruby_version = '>= 3.0'
+   spec.required_ruby_version = '>= 3.3'
+
+   # TODO: remove when CSV persister is split to separate gem; used to be part of STDLIB but now is separate
+   spec.add_dependency 'csv', '>= 3.3'
 end

metadata

@@ -1,15 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: procrastinator
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Robin Miller
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-06-17 00:00:00.000000000 Z
-dependencies: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.3'
 description: A flexible pure Ruby job queue. Tasks are reschedulable after failures.
 email:
 - robin@tenjin.ca
@@ -50,7 +63,6 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -58,15 +70,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.26
-signing_key: 
+rubygems_version: 3.6.9
 specification_version: 4
 summary: For apps to put off work until later
 test_files: []