> For the complete documentation index, see [llms.txt](https://docs.joobq.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.joobq.io/guides/scheduler.md).

# 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.

```crystal
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.

```crystal
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.

```crystal
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:

```crystal
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!


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.joobq.io/guides/scheduler.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.