lib/rocket_job/plugins/cron.rb in rocketjob-3.4.3 vs lib/rocket_job/plugins/cron.rb in rocketjob-3.5.0

@@ -1,132 +1,10 @@
 require 'active_support/concern'
 
 module RocketJob
   module Plugins
-    # Automatically schedules the job to start based on the supplied `cron_schedule`.
-    # Once started the job will automatically restart on completion and will only run again
-    # according to the `cron_schedule`.
-    # Failed jobs are aborted so that they cannot be restarted since a new instance has already
-    # been enqueued.
-    #
-    # Include RocketJob::Plugins::Singleton to prevent multiple copies of the job from running at
-    # the same time.
-    #
-    # Unlike cron, if a job is already running, another one is not queued when the cron
-    # schedule needs another started, but rather on completion of the current job. This prevents
-    # multiple instances of the same job from running at the same time. The next instance of the
-    # job is only scheduled on completion of the current job instance.
-    #
-    # For example if the job takes 10 minutes to complete, and is scheduled to run every 5 minutes,
-    # it will only be run every 10 minutes.
-    #
-    # Their is no centralized scheduler or need to start schedulers anywhere, since the jobs
-    # can be picked up by any Rocket Job worker. Once processing is complete a new instance is then
-    # automatically scheduled based on the `cron_schedule`.
-    #
-    # A job is only queued to run at the specified `cron_schedule`, it will only run if there are workers
-    # available to run. For example if workers are busy working on higher priority jobs, then the job
-    # will only run once those jobs have completed, or their priority lowered. Additionally, while the
-    # job is queued no additional instances will be enqueued, even if the next cron interval has been reached.
-    #
-    # Notes:
-    # - The job will not be restarted if:
-    #   - A validation fails after cloning this job.
-    #   - The job has expired.
-    # - Any time the `cron_schedule` is changed, the `run_at` is automatically set before saving the changes.
-    #   - However, if the `run_at` is explicitly set then it will not be overridden.
-    # - `cron_schedule` is not a required field so that the same job class
-    #   - can be scheduled to run at regular intervals,
-    #   - and run on an ad-hoc basis with custom values.
-    # - On job failure
-    #   - a new future instance is created immediately.
-    #   - the current instance is marked as failed and its cron schedule is set to nil.
-    #     - Prevents the failed instance from creating a new future instance when it completes.
-    #
-    # Example, schedule the job to run at regular intervals:
-    #
-    # class MyCronJob < RocketJob::Job
-    #   include RocketJob::Plugins::Cron
-    #
-    #   # Set the default cron_schedule
-    #   self.cron_schedule = "* 1 * * * UTC"
-    #
-    #   def perform
-    #     puts "DONE"
-    #   end
-    # end
-    #
-    # # Queue the job for processing using the default cron_schedule specified above.
-    # MyCronJob.create!
-    #
-    #
-    # Example, a job that can run at regular intervals, and can be run for ad-hoc reporting etc.:
-    #
-    # class ReportJob < RocketJob::Job
-    #   # Do not set a default cron_schedule so that the job can also be used for ad-hoc work.
-    #   include RocketJob::Plugins::Cron
-    #
-    #   field :start_date, type: Date
-    #   field :end_date,   type: Date
-    #
-    #   def perform
-    #     # Uses `scheduled_at` to take into account any possible delays.
-    #     self.start_at ||= scheduled_at.beginning_of_week.to_date
-    #     self.end_at   ||= scheduled_at.end_of_week.to_date
-    #
-    #     puts "Running report, starting at #{start_date}, ending at #{end_date}"
-    #   end
-    # end
-    #
-    # # Queue the job for processing using a cron_schedule.
-    # # On completion the job will create a new instance to run at a future date.
-    # ReportJob.create!(cron_schedule: '* 1 * * * America/New_York')
-    #
-    # # Queue the job for processing outside of the above cron schedule.
-    # # On completion the job will _not_ create a new instance to run at a future date.
-    # job = ReportJob.create!(start_date: 30.days.ago, end_date: 10.days.ago)
-    #
-    #
-    # To prevent multiple instances of the job from running at the same time, add the singleton plug-in:
-    #   include RocketJob::Plugins::Singleton
-    #
-    # Example: Only allow one instance of this job to be active at the same time (running, queued, scheduled, or failed):
-    #
-    # class MyCronJob < RocketJob::Job
-    #   # Add `cron_schedule`
-    #   include RocketJob::Plugins::Cron
-    #   # Prevents mutiple instances from being queued or run at the same time
-    #   include RocketJob::Plugins::Singleton
-    #
-    #   # Set the default cron_schedule
-    #   self.cron_schedule = "* 1 * * * UTC"
-    #
-    #   def perform
-    #     puts "DONE"
-    #   end
-    # end
-    #
-    # Note: The cron_schedule field is formatted as follows:
-    #
-    #     *    *    *    *    *    *
-    #     ┬    ┬    ┬    ┬    ┬    ┬
-    #     │    │    │    │    │    │
-    #     │    │    │    │    │    └ Optional: Timezone, for example: 'America/New_York', 'UTC'
-    #     │    │    │    │    └───── day_of_week (0-7) (0 or 7 is Sun, or use 3-letter names)
-    #     │    │    │    └────────── month (1-12, or use 3-letter names)
-    #     │    │    └─────────────── day_of_month (1-31)
-    #     │    └──────────────────── hour (0-23)
-    #     └───────────────────────── minute (0-59)
-    #
-    # * When specifying day of week, both day 0 and day 7 is Sunday.
-    # * Ranges & Lists of numbers are allowed.
-    # * Ranges or lists of names are not allowed.
-    # * Ranges can include 'steps', so `1-9/2` is the same as `1,3,5,7,9`.
-    # * Months or days of the week can be specified by name.
-    # * Use the first three letters of the particular day or month (case doesn't matter).
-    # * The timezone is recommended to prevent any issues with possible default timezone
-    #   differences across servers, or environments.
+    # Schedule jobs to run at set intervals.
     module Cron
       extend ActiveSupport::Concern
 
       included do
         include Restart
@@ -174,10 +52,16 @@
       #   since that would be the intended time for which this job is running.
       def scheduled_at
         run_at || created_at
       end
 
+      # Make this job run now, regardless of the cron schedule.
+      # Upon completion the job will automatically reschedule itself.
+      def run_now!
+        update_attributes(run_at: nil) if cron_schedule
+      end
+
       # Returns [Time] the next time this job will be scheduled to run at.
       #
       # Parameters
       #   time: [Time]
       #     The next time as of this time.
@@ -190,9 +74,8 @@
 
       def rocket_job_set_run_at
         return unless cron_schedule
         self.run_at = rocket_job_cron_next_time if cron_schedule_changed? && !run_at_changed?
       end
-
     end
   end
 end