Scheduler
Table of Contents
1. Summary
The scheduler runs jobs on cron schedules. It has three domain types. A job definition is configuration: a name, a cron expression, an action type with its payload, an active flag, and an optional tenant and party. A firing is the record of one execution of a job: the job it belongs to, the instant it was triggered, its start and end times, its status, and its error. An action is the operation a firing performs; the scheduler registers one handler per action type and selects the handler by the action type the job declares.
The scheduler has minute granularity: a cron expression resolves to whole minutes and the loop fires a job at the minute it names, so the shortest interval between two firings is one minute. An action runs either a database statement or a message delivery. The scheduler does not wait for the work a message starts, and it does not retry an action that fails.
Read the pages below in the order given. The first is an end-to-end example, the next five describe one type each in the order of the path, and the last section is the boundary with the workflow cluster.
2. Reading order
2.1. The end-to-end example
A first schedule. Read it first. It registers one job, shows the firing that job produces, and shows the message its action publishes. It introduces the terms the other pages use, and it depends on no other component. A reader who needs only the structure of the scheduler can stop after it.
2.2. The types, in the order of the path
The job definition. Read it second, because it is the configuration the rest of the path reads. It defines the fields, the natural key, the write path with its precondition, the versions a write creates, and how a change reaches the loop.
The cron expression. Read it third: it defines the field that decides when a job runs. It covers the five fields, the value forms, the validation at the API boundary, and the condition that makes a job due.
The scheduler loop. Read it fourth. It describes the sleep until the next due instant, the in-memory job set and its re-arm on a change event, and the rule that a firing does not block the loop.
The firing. Read it fifth. It describes the record written before the action runs, the three states a firing moves through, and the two read operations over the record.
Job actions. Read it sixth. It describes the three action types, the handler registry, and whether a firing waits for a reply.
2.3. The boundary with the workflow cluster
Scheduling and workflows. Read it last. It defines the start message a firing publishes and the three obligations the scheduler has at that boundary. The job starts a run; it does not execute it, and the run belongs to the workflow cluster.
2.4. Components that use the scheduler
The pages in this section are not about the scheduler. Each describes a component that uses it, and each assumes the pages above.
Report definition and schedule. Reporting's use of the scheduler: one job per report definition, the schedule held outside the definition, and the firing that triggers a report instance. Read it after the pages above, because the division of ownership needs the job, the firing and the action to be already defined.
Report Processing. Read it when the question is what a scheduled run consists of rather than when it starts. The cluster defines the phases of a report run and what each phase may assume of the one before it.
Workflows. Read it alongside the previous page. It owns the engine that executes what a firing started: the step protocol, the states a run and a step occupy, and the failure handling. This cluster starts a run, that one executes it, and the two meet at the start message a firing publishes.
3. What this cluster does not cover
Calendars, Holidays and Events owns calendar reference data: business days, holidays and market events. The scheduler does not read it. A cron expression defines wall-clock instants, so a firing is due at a stated minute and not on a business day, and a recurrence that must follow the business calendar cannot be expressed as a cron expression.
Compute job lifecycle owns the grid's jobs: batches, workunits, results and hosts. The word job has two distinct meanings here. A scheduled job is a definition that fires; a compute job is a unit of work submitted to the grid.
The workflow cluster owns the contents of a run, and this cluster owns only the point at which a run may be started. The division is why either cluster can be read without the other.
4. See also
- Knowledge — the index this structure note hangs from.
- Zettelkasten — what a structure note is, and why its order is authored rather than computed.