Scheduler

The Scheduler class in JoobQ is responsible for managing job scheduling. It allows you to schedule jobs to run at specific intervals, delay jobs, and run jobs based on cron patterns. The scheduler ensures that jobs are executed at the right time and provides mechanisms for both recurring and delayed job execution.

Key Features

Delaying a Job

The Scheduler allows you to delay a job for a specified period of time. This is useful when you need to postpone a task's execution until a later time.

scheduler = JoobQ.scheduler
job = ExampleJob.new(x: 1)
scheduler.delay(job, for: 2.minutes)

In the example above, the job will be added to the store with a delay of 2 minutes, meaning it will only be executed after the specified delay.

Scheduling a Recurring Job

To run a job at regular intervals, you can use the every method. This allows you to define recurring tasks that are automatically executed at a given frequency.

scheduler = JoobQ.scheduler
scheduler.every(5.minutes, ExampleJob, x: 1)

In this example, the ExampleJob will be executed every 5 minutes.

Scheduling a Cron Job

If you need to schedule a job based on a cron pattern, the Scheduler provides the cron method. Cron jobs are useful for tasks that need to run at specific times, such as nightly data processing or hourly reporting.

scheduler = JoobQ.scheduler
scheduler.cron("*/5 * * * *") do
  ExampleJob.new(x: 1).perform
end

This example will execute ExampleJob every 5 minutes, as specified by the cron pattern.

Scheduler Workflow

1. Initialization

The Scheduler is initialized as a singleton instance through the instance method. This ensures there is only one active scheduler managing all scheduled jobs.

2. Delaying Jobs

The delay method is used to add jobs to the store with a specified delay. The job is not executed until the delay period has passed, providing precise control over job timing.

3. Scheduling Recurring Jobs

The every method is used to schedule recurring jobs. A job instance is created and stored in the jobs hash along with its interval. The scheduler runs a loop that waits for the specified interval and then executes the job.

4. Scheduling Cron Jobs

The cron method is used to create jobs based on cron patterns. The cron parser is used to determine the next execution time, and the job is then executed accordingly.

5. Job Execution

Jobs are executed by calling their perform method. For recurring jobs, the scheduler runs the job at regular intervals. For cron jobs, it follows the specified cron schedule to determine when the job should be run.

Example Usage

Here is a complete example of how to use the Scheduler class in JoobQ:

require "joobq"

# Define a job
struct ExampleJob
  include JoobQ::Job
  property x : Int32

  def initialize(@x : Int32)
  end

  def perform
    puts "Performing job with x = #{x}"
  end
end

# Get the scheduler instance
scheduler = JoobQ.scheduler

# Delay a job
job = ExampleJob.new(x: 1)
scheduler.delay(job, for: 2.minutes)

# Schedule a recurring job
scheduler.every(5.minutes, ExampleJob, x: 1)

# Schedule a cron job
scheduler.cron("*/5 * * * *") do
  ExampleJob.new(x: 1).perform
end

In this example, the scheduler delays a job by 2 minutes, schedules a recurring job every 5 minutes, and schedules a cron job to run every 5 minutes.

Best Practices for Using the Scheduler

• Use Recurring Jobs for Regular Maintenance: Use the every method for tasks that need to be performed at regular intervals, such as clearing old cache or generating regular reports.

• Use Cron Jobs for Specific Scheduling Needs: When a job needs to run at a specific time of day, use cron scheduling to define the exact timing.

• Monitor Job Execution: Make use of the metrics available in JoobQ to monitor job performance and ensure that scheduled jobs are running as expected.

• Handle Exceptions Gracefully: When defining the perform method, ensure that exceptions are properly handled to avoid failed jobs from crashing the scheduler.

---

The Scheduler class in JoobQ provides powerful tools for managing the timing and recurrence of your jobs. Whether you need simple delays, recurring intervals, or precise cron scheduling, the scheduler makes it easy to ensure your tasks run exactly when you need them to. Ready to dive deeper? Let's explore other advanced features of JoobQ to make the most of your job processing needs!