procrastinator 1.0.0.pre.rc4 → 1.0.1

data/lib/procrastinator/task_store/file_transaction.rb

@@ -3,74 +3,72 @@
 require 'pathname'
 
 module Procrastinator
-   module TaskStore
-      # The general idea is that there may be two threads that need to do these actions on the same file:
-      #    thread A:   read
-      #    thread B:   read
-      #    thread A/B: write
-      #    thread A/B: write
-      #
-      # When this sequence happens, the second file write is based on old information and loses the info from
-      # the prior write. Using a global mutex per file path prevents this case.
-      #
-      # This situation can also occur with multi processing, so file locking is also used for solitary access.
-      # File locking is only advisory in some systems, though, so it may only work against other applications
-      # that request a lock.
-      #
-      # @author Robin Miller
-      class FileTransaction
-         # Holds the mutual exclusion locks for file paths by name
-         @file_mutex = {}
+   # The general idea is that there may be two threads that need to do these actions on the same file:
+   #    thread A:   read
+   #    thread B:   read
+   #    thread A/B: write
+   #    thread A/B: write
+   #
+   # When this sequence happens, the second file write is based on old information and loses the info from
+   # the prior write. Using a global mutex per file path prevents this case.
+   #
+   # This situation can also occur with multi processing, so file locking is also used for solitary access.
+   # File locking is only advisory in some systems, though, so it may only work against other applications
+   # that request a lock.
+   #
+   # @author Robin Miller
+   class FileTransaction
+      # Holds the mutual exclusion locks for file paths by name
+      @file_mutex = {}
 
-         class << self
-            attr_reader :file_mutex
-         end
+      class << self
+         attr_reader :file_mutex
+      end
 
-         def initialize(path)
-            @path = ensure_path(path)
-         end
+      def initialize(path)
+         @path = ensure_path(path)
+      end
 
-         # Alias for transact(writable: false)
-         def read(&block)
-            transact(writable: false, &block)
-         end
+      # Alias for transact(writable: false)
+      def read(&block)
+         transact(writable: false, &block)
+      end
 
-         # Alias for transact(writable: true)
-         def write(&block)
-            transact(writable: true, &block)
-         end
+      # Alias for transact(writable: true)
+      def write(&block)
+         transact(writable: true, &block)
+      end
 
-         # Completes the given block as an atomic transaction locked using a global mutex table.
-         # The block is provided the current file contents.
-         # The block's result is written to the file.
-         def transact(writable: false)
-            semaphore = FileTransaction.file_mutex[@path.to_s] ||= Mutex.new
+      # Completes the given block as an atomic transaction locked using a global mutex table.
+      # The block is provided the current file contents.
+      # The block's result is written to the file.
+      def transact(writable: false)
+         semaphore = FileTransaction.file_mutex[@path.to_s] ||= Mutex.new
 
-            semaphore.synchronize do
-               @path.open(writable ? 'r+' : 'r') do |file|
-                  file.flock(File::LOCK_EX)
+         semaphore.synchronize do
+            @path.open(writable ? 'r+' : 'r') do |file|
+               file.flock(File::LOCK_EX)
 
-                  yield_result = yield(file.read)
-                  if writable
-                     file.rewind
-                     file.write yield_result
-                     file.truncate(file.pos)
-                  end
-                  yield_result
+               yield_result = yield(file.read)
+               if writable
+                  file.rewind
+                  file.write yield_result
+                  file.truncate(file.pos)
                end
+               yield_result
             end
          end
+      end
 
-         private
+      private
 
-         def ensure_path(path)
-            path = Pathname.new path
-            unless path.exist?
-               path.dirname.mkpath
-               FileUtils.touch path
-            end
-            path
+      def ensure_path(path)
+         path = Pathname.new path
+         unless path.exist?
+            path.dirname.mkpath
+            FileUtils.touch path
          end
+         path
       end
    end
 end

data/lib/procrastinator/task_store/simple_comma_store.rb

@@ -4,25 +4,33 @@ require 'csv'
 require 'pathname'
 
 module Procrastinator
+   # Task storage strategies.
+   #
+   # All task stores must implement the API #read, #create, #update, #delete.
    module TaskStore
       # Simple Task I/O adapter that writes task information (ie. TaskMetaData attributes) to a CSV file.
       #
-      # SimpleCommaStore is not designed for efficiency or large loads (10,000+ tasks).
-      #
-      # For critical production environments, it is strongly recommended to use a more robust storage mechanism like a
-      # proper database.
+      # SimpleCommaStore is not designed for efficiency or large loads (10,000+ tasks). For critical production
+      # environments, it is strongly recommended to use a more robust storage mechanism like a proper database.
       #
       # @author Robin Miller
       class SimpleCommaStore
-         # ordered
+         # Ordered list of CSV column headers
          HEADERS = [:id, :queue, :run_at, :initial_run_at, :expire_at,
                     :attempts, :last_fail_at, :last_error, :data].freeze
 
-         EXT          = 'csv'
-         DEFAULT_FILE = Pathname.new("procrastinator-tasks.#{ EXT }").freeze
-
+         # Columns that store time information
          TIME_FIELDS = [:run_at, :initial_run_at, :expire_at, :last_fail_at].freeze
 
+         # CSV file extension
+         EXT = 'csv'
+
+         # Default filename
+         DEFAULT_FILE = Pathname.new("procrastinator-tasks.#{ EXT }").freeze
+
+         # CSV Converter lambda
+         #
+         # @see CSV
          READ_CONVERTER = proc do |value, field_info|
             if field_info.header == :data
                value
@@ -53,6 +61,10 @@ module Procrastinator
             freeze
          end
 
+         # Parses the CSV file for data matching the given filter, or all if no filter provided.
+         #
+         # @param filter [Hash] Specified attributes to match.
+         # @return [Array<Hash>]
          def read(filter = {})
             CSVFileTransaction.new(@path).read do |existing_data|
                existing_data.select do |row|
@@ -69,7 +81,7 @@ module Procrastinator
          # @param run_at [Time, nil] time to run the task at
          # @param initial_run_at [Time, nil] first time to run the task at. Defaults to run_at.
          # @param expire_at [Time, nil] time to expire the task
-         def create(queue:, run_at:, expire_at:, data: '', initial_run_at: nil)
+         def create(queue:, run_at:, expire_at: nil, data: '', initial_run_at: nil)
             CSVFileTransaction.new(@path).write do |tasks|
                max_id = tasks.collect { |task| task[:id] }.max || 0
 
@@ -87,6 +99,10 @@ module Procrastinator
             end
          end
 
+         # Updates an existing task in the CSV file.
+         #
+         # @param id [Integer] task ID number
+         # @param data [Hash] new data to save
          def update(id, data)
             CSVFileTransaction.new(@path).write do |tasks|
                task_data = tasks.find do |task|
@@ -99,12 +115,19 @@ module Procrastinator
             end
          end
 
+         # Removes an existing task from the CSV file.
+         #
+         # @param id [Integer] task ID number
          def delete(id)
             CSVFileTransaction.new(@path).write do |existing_data|
                generate(existing_data.reject { |task| task[:id] == id })
             end
          end
 
+         # Generates a CSV string from the given data.
+         #
+         # @param data [Array] list of data to convert into CSV
+         # @return [String] Generated CSV string
          def generate(data)
             lines = data.collect do |d|
                TIME_FIELDS.each do |field|
@@ -120,6 +143,7 @@ module Procrastinator
 
          # Adds CSV parsing to the file reading
          class CSVFileTransaction < FileTransaction
+            # (see FileTransaction#transact)
             def transact(writable: nil)
                super(writable: writable) do |file_str|
                   yield(parse(file_str))

data/lib/procrastinator/test/mocks.rb

@@ -1,6 +1,13 @@
 # frozen_string_literal: true
 
 module Procrastinator
+   # Reusable Test classes for mocking out object queues.
+   #
+   #    require 'procrastinator/test/mocks'
+   #
+   #    Procrastinator.setup do |config|
+   #       config.define_queue :test_queue, Procrastinator::Test::Mock
+   #    end
    module Test
       # Testing mock Task class
       #
@@ -16,10 +23,12 @@ module Procrastinator
       class MockTask
          attr_accessor :container, :logger, :scheduler
 
+         # Records that the mock task was run.
          def run
             @run = true
          end
 
+         # @return [Boolean] Whether the task was run
          def run?
             @run
          end

data/lib/procrastinator/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Procrastinator
-   VERSION = '1.0.0-rc4'
+   # Version number of this release
+   VERSION = '1.0.1'
 end

data/procrastinator.gemspec

@@ -33,4 +33,5 @@ Gem::Specification.new do |spec|
    spec.add_development_dependency 'rubocop-performance', '~> 1.10'
    spec.add_development_dependency 'simplecov', '~> 0.18.0'
    spec.add_development_dependency 'timecop', '~> 0.9'
+   spec.add_development_dependency 'yard', '~> 0.9'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: procrastinator
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.rc4
+  version: 1.0.1
 platform: ruby
 authors:
 - Robin Miller
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-09-17 00:00:00.000000000 Z
+date: 2022-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -122,6 +122,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: A flexible pure Ruby job queue. Tasks are reschedulable after failures.
 email:
 - robin@tenjin.ca
@@ -133,7 +147,6 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
-- ".travis.yml"
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
@@ -149,6 +162,7 @@ files:
 - lib/procrastinator/queue_worker.rb
 - lib/procrastinator/rake/daemon_tasks.rb
 - lib/procrastinator/rake/tasks.rb
+- lib/procrastinator/rspec/matchers.rb
 - lib/procrastinator/scheduler.rb
 - lib/procrastinator/task.rb
 - lib/procrastinator/task_meta_data.rb
@@ -173,9 +187,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '2.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.1.2
 signing_key: 

data/.travis.yml

@@ -1,4 +0,0 @@
-language: ruby
-rvm:
-  - 2.2.1
-before_install: gem install bundler -v 1.11.2