Scheduler (cron jobs)

The scheduler module runs in-process actions on a recurring schedule written as a CRON-like expression. You register one or more jobs with a JobManager, start it, and each job's delegate runs on its own thread whenever the current minute matches its expression. Use it for lightweight periodic work inside a long-running process, such as cleanup, polling or cache refresh.

This module is a minimal minute-resolution timer that lives in the core package. For queued, retried or persisted background work, use the separate BackgroundJobs package instead.

How it works

Timer. JobManager owns a System.Timers.Timer with a fixed 30-second interval. On each tick it compares the current minute (DateTime.Now.Minute) with the minute of the last run. If the minute has changed, it records the new run time and calls Execute(DateTime.Now) on every registered JobRunner, in the order they were added. The last-run time is initialized when the JobManager is constructed, so the minute in which you create the manager never triggers jobs. All times are local (DateTime.Now).

Matching. Each JobRunner holds a CronScheduler built from its expression. Execute checks CronScheduler.IsTime(dateTime); if the time does not match, nothing happens.

Threading. When the time matches, the runner starts a new Thread for the delegate, unless the previous run of the same job is still in the Running or WaitSleepJoin state, in which case the run is skipped. Runs of the same job never overlap; different jobs run concurrently. Calls to Execute are serialized with a lock per runner. The job threads are ordinary foreground threads and nothing catches exceptions thrown by the delegate: an unhandled exception in a job terminates the process. Wrap the body of each job in try/catch.

Stopping. Stop() stops the timer, so no new runs start. Jobs already running are not interrupted. JobManager does not implement IDisposable.

CRON syntax

CronScheduler supports five fields, in this order. There is no seconds field and no year field.

Fields are found by pattern matching, not by splitting on spaces. The expression is scanned with CronSchedulerValidations.ValidationRegex, and each successive match becomes the next field. Any character that is not part of a match acts as a separator. Fields that are missing at the end default to *, so 10 is the same as 10 * * * * and * */3 is the same as * */3 * * *. Matches after the fifth are ignored.

Each field can use exactly one of these forms:

All conditions are combined with AND: a time matches only if the minute, hour, day of month, month and day of week all match. This differs from standard cron, where a restricted day of month and a restricted day of week are combined with OR.

Behaviors to be aware of:

• Steps are divisibility tests, not offsets from the start. */5 in the day-of-month field yields 5, 10, 15, 20, 25, 30 (not 1, 6, 11, ...). 1-10/3 in the minute field yields 3, 6, 9 (not 1, 4, 7, 10). */2 in the month field yields 2, 4, ..., 12.
• Not supported: names (MON, JAN), ?, L, W, #, 7 for Sunday, steps on a single value (5/10), lists that contain ranges (1-5,10), and macros such as @daily.
• Unsupported tokens are not rejected. They are skipped or split into extra matches, which shifts the remaining fields. For example, 0 0 * * MON has only four matches, so the day of week becomes * and the job runs every day at midnight. 1-5,10 * * * * yields six matches (1-5, 10, *, ...), so 10 becomes the hour.
• Values outside a field's range are accepted but never match (for example, minute 70).
• IsValid returns true if the expression contains at least one match, so it only rejects strings with no digits and no * at all.

Getting started

using System;
using System.Threading;
using CrispyWaffle.Scheduler;

var counter = 0;

var jobManager = new JobManager();
jobManager.AddJob("* * * * *", () => Interlocked.Increment(ref counter));
jobManager.Start();

Thread.Sleep(TimeSpan.FromMinutes(2));

jobManager.Stop();
Console.WriteLine(counter); // typically 1 or 2, depending on when the manager was created

Reference

JobManager

public class JobManager : IJobManager — holds a list of jobs and triggers them from a 30-second timer, at most once per minute.

IJobManager

public interface IJobManager — contract for a component that schedules and runs jobs.

IJobRunner

public interface IJobRunner — contract for a single scheduled job.

JobRunner

public class JobRunner : IJobRunner — runs one ThreadStart delegate on a new thread when a CronScheduler matches.

You normally create these through JobManager.AddJob. Create one directly to drive a schedule from your own timer.

IScheduler

public interface IScheduler — contract for an object that parses a schedule expression and tests dates against it.

CronScheduler

public class CronScheduler : IScheduler — parses a five-field expression (see CRON syntax) into sets of matching values.

CronSchedulerValidations

public static class CronSchedulerValidations — the regular expressions used to tokenize and classify CRON fields.

All are public static readonly Regex, compiled, with a 5-second match timeout.

When classifying a field, CronScheduler tests DividedRegex, then RangeRegex, then WildRegex, then ListRegex, and uses the first that matches.

Examples

Several jobs with error handling

using System;
using CrispyWaffle.Log;
using CrispyWaffle.Scheduler;

var jobManager = new JobManager();

jobManager.AddJob("*/5", () =>
{
    try
    {
        PurgeExpiredSessions();
    }
    catch (Exception ex)
    {
        LogConsumer.Handle(ex);
    }
});

jobManager.AddJob("0 3 * * 0", () =>
{
    try
    {
        RebuildSearchIndex(); // 03:00 every Sunday
    }
    catch (Exception ex)
    {
        LogConsumer.Handle(ex);
    }
});

jobManager.Start();

Inspecting a schedule

using System;
using CrispyWaffle.Scheduler;

var scheduler = new CronScheduler("* 10-15 * * *");

Console.WriteLine(string.Join(",", scheduler.Hours)); // 10,11,12,13,14,15

var weekend = new CronScheduler("* * * * 0,6");
Console.WriteLine(weekend.IsTime(new DateTime(2020, 9, 5, 12, 0, 0))); // True (Saturday)

Driving a runner from your own clock

using System;
using CrispyWaffle.Scheduler;

IJobRunner runner = new JobRunner("0 * * * *", () => Console.WriteLine("top of the hour"));

runner.Execute(new DateTime(2024, 1, 1, 10, 0, 0)); // starts the job
runner.Execute(new DateTime(2024, 1, 1, 10, 1, 0)); // does nothing

See also

• BackgroundJobs
• Logging