FabulousScheduler.Core 5.1.0

Core (FabulousScheduler.Core)

FabulousScheduler.Core holds the pieces both subsystems share. There is no scheduling logic in here, only the contracts (IJob, IJobScheduler, IJobOk, IJobFail) and the JobResult<TOk, TFail> type.

If you want the big picture first, read General concepts.

📖 Contents

• IJob
• IJobScheduler
• IJobOk / IJobFail
• JobResult<TOk, TFail>

IJob <a id="ijob" />

FabulousScheduler.Core.Interfaces.IJob is the identity every job carries. It also implements IDisposable and IAsyncDisposable.

Each subsystem has its own interface on top of IJob:

• IRecurringJob adds Category, State, SleepDuration, TotalRun, TotalFail and ExecuteAsync(). See Recurring.md.
• IQueueJob adds State, TotalRun, Attempts, ExecuteAsync() and ResetState(). See QueueBased.md.

IJobScheduler <a id="ijobscheduler" />

FabulousScheduler.Core.Interfaces.IJobScheduler is the smallest scheduler contract. It implements IDisposable.

public interface IJobScheduler : IDisposable
{
    void RunScheduler();   // start the scheduler
}

IRecurringJobScheduler and IQueueJobScheduler both extend it and add a JobResultEvent (with a JobResultEventHandler delegate) that fires after every run, using the job and result types of their subsystem.

IJobOk / IJobFail <a id="results" />

These are the two markers a result can hold. Each one exposes the job ID and nothing else. The real payload (a message, a reason, the original exception) lives on the concrete types that each subsystem ships.

public interface IJobOk   { Guid ID { get; } }
public interface IJobFail { Guid ID { get; } }

Both JobFail types are plain result objects. When a job fails, you read the reason, the message and (if there was one) the original exception off the object. You never throw it.

JobResult<TOk, TFail> <a id="jobresult" />

FabulousScheduler.Core.Types.JobResult<TOk, TFail> (where TOk : IJobOk, where TFail : IJobFail) is a tiny either/or value. It carries a success value or a failure value, one of the two, and it does not use exceptions to signal which.

Creating a result

You rarely call a constructor. A JobOk or a JobFail converts into a result on its own:

JobResult<JobOk, JobFail> ok   = new JobOk(id);                  // becomes a success
JobResult<JobOk, JobFail> fail = new JobFail(reason, id, "msg"); // becomes a failure

Inspecting

Consuming

// A side effect per branch
result.Do(
    success: ok   => Console.WriteLine("{0} succeeded", ok.JobID),
    failure: fail => Console.WriteLine("{0} failed: {1}", fail.JobID, fail.Message)
);

// Map to a value
string msg = result.Match(
    success: ok   => $"{ok.JobID} succeeded",
    failure: fail => $"{fail.JobID} failed: {fail.Message}"
);

// Async
int code = await result.MatchAsync(
    success: async ok   => { await Task.Yield(); return 0; },
    failure: async fail => { await Task.Yield(); return 1; }
);

One thing to watch: every JobResult is a class, so it allocates. With a lot of jobs per second that adds up. There are numbers for it in Benchmarks.