Interface IDriverDelegate

Namespace: Quartz.Impl.AdoJobStore

Assembly: Quartz.dll

This is the base interface for all driver delegate classes.

public interface IDriverDelegate

Remarks

This interface is very similar to the IJobStore interface except each method has an additional ConnectionAndTransactionHolder parameter.

Unless a database driver has some extremely-DB-specific requirements, any IDriverDelegate implementation classes should extend the StdAdoDelegate class.

Properties

FiltersAcquisitionExecutionGroups

Whether SelectTriggersToAcquire(ConnectionAndTransactionHolder, TriggerAcquisitionCriteria, CancellationToken) already keeps the rows outside ServedExecutionGroups — or inside RefusedExecutionGroups — out of what it returns.

bool FiltersAcquisitionExecutionGroups { get; }

Property Value

bool

Remarks

The same contract as FiltersAcquisitionJobTypeExclusions, for the same reason: a delegate that ignores the routing would have the node run a group the deployment gave to other nodes. So the ADO store keeps a backstop — it drops a candidate the node does not serve, ordinally on ExecutionGroup, before reading it back — and this says the backstop has nothing left to do.

false by default, because a delegate written before routing existed cannot have honoured it. StdAdoDelegate answers true, and so does every dialect Quartz ships. A delegate of somebody's own that replaces the acquisition statement without the clause must answer false.

FiltersAcquisitionJobTypeExclusions

Whether SelectTriggersToAcquire(ConnectionAndTransactionHolder, TriggerAcquisitionCriteria, CancellationToken) already keeps ExcludedJobTypeNames out of the rows it returns.

bool FiltersAcquisitionJobTypeExclusions { get; }

Property Value

bool

Remarks

Every other property of TriggerAcquisitionCriteria may be ignored by a delegate with no worse consequence than a wider result than asked for. This one is different: ignoring it means the node runs job types the deployment excluded. So the ADO store keeps a backstop — it drops an excluded candidate ordinally on JobTypeName before reading the trigger back — and this property is how a delegate says the backstop has nothing left to do.

It defaults to false, because a delegate written before the exclusions existed cannot have honoured them. StdAdoDelegate answers true: its acquisition statement carries the NOT IN clause, and every dialect Quartz ships builds its statement from that one. A delegate of somebody's own that replaces the acquisition statement without the clause — or overrides StdAdoDelegate.GetSelectNextTriggerToAcquireSql to drop it — must answer false, or the exclusions stop being enforced anywhere.

SupportsFireOnAcquire

Whether the store may fire a trigger in the transaction that acquires it through this delegate's round members, in place of its single-trigger ones.

bool SupportsFireOnAcquire { get; }

Property Value

bool

Remarks

A default interface member answering false, so a delegate written against an earlier 4.x has every one of its members called as before. Its round is still one transaction, but each trigger is claimed and reserved, its header and job read, and its fire written as an update of that reservation, through the single-trigger members, exactly as acquiring and then firing it did. StdAdoDelegate answers true for the delegates Quartz ships and false for a subclass; a subclass whose overrides the round members cover may answer true.

Methods

ApplyTriggerFired(ConnectionAndTransactionHolder, TriggerFiredUpdate, CancellationToken)

Apply every row change one trigger fire makes.

ValueTask ApplyTriggerFired(ConnectionAndTransactionHolder conn, TriggerFiredUpdate update, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
update TriggerFiredUpdate: The changes the fire makes.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

Remarks

The fire path has read everything it decides on before it writes anything, so what is left is a run of writes with no read between them: the fired-trigger row, the misfire original fire time where one was recorded, the sibling triggers of a job that disallows concurrent execution, the trigger's own row, and its schedule in whichever type table holds it. They go out as one DbBatch where the provider supports batching, and one command at a time where it does not.

All of it is one transaction either way, and a batch executes its commands in sequence, so the order the writes were issued in is the order they still happen in.

ApplyTriggersFired(ConnectionAndTransactionHolder, IReadOnlyList<TriggerFiredUpdate>, CancellationToken)

Apply every row change the fires of one acquisition round make.

ValueTask ApplyTriggersFired(ConnectionAndTransactionHolder conn, IReadOnlyList<TriggerFiredUpdate> updates, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
updates IReadOnlyList<TriggerFiredUpdate>: The changes each fire makes, in the order the round fired them.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

Remarks

The plural of ApplyTriggerFired(ConnectionAndTransactionHolder, TriggerFiredUpdate, CancellationToken), for an acquisition that fires what is due in the same transaction (#3864): the round decides every fire before it writes any, so the writes of all of them can go together. StdAdoDelegate sends them as one DbBatch where the provider can batch. The writes of one fire keep their order, and the fires keep the order given. Called only for a delegate that answers SupportsFireOnAcquire with true.

A default interface member, so a delegate written against an earlier 4.x keeps working: the default is ApplyTriggerFired(ConnectionAndTransactionHolder, TriggerFiredUpdate, CancellationToken) for each update, in order, and tells the store which update failed, so that it rolls back that fire alone. An override cannot tell it — the exception that carries the position is internal — so a failure out of an override makes the store roll the round back and run it again one trigger at a time, through ApplyTriggerFired(ConnectionAndTransactionHolder, TriggerFiredUpdate, CancellationToken), which finds the fire that failed.

CalendarExists(ConnectionAndTransactionHolder, string, CancellationToken)

Check whether or not a calendar exists.

ValueTask<bool> CalendarExists(ConnectionAndTransactionHolder conn, string calendarName, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
calendarName string: The name of the calendar.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<bool>: true if the trigger exists, false otherwise.

CalendarIsReferenced(ConnectionAndTransactionHolder, string, CancellationToken)

Check whether or not a calendar is referenced by any triggers.

ValueTask<bool> CalendarIsReferenced(ConnectionAndTransactionHolder conn, string calendarName, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
calendarName string: The name of the calendar.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<bool>: true if any triggers reference the calendar, false otherwise

ClearData(ConnectionAndTransactionHolder, CancellationToken)

Clear (delete!) all scheduling data - all IJobs, ITriggers ICalendars.

ValueTask ClearData(ConnectionAndTransactionHolder conn, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The connection and transaction this delete runs in.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

ClearMisfireOriginalFireTime(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Clears the misfire original fire time for the given trigger.

ValueTask ClearMisfireOriginalFireTime(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder
triggerKey TriggerKey
cancellationToken CancellationToken

Returns

ValueTask

Remarks

The fire path clears it as one command of ApplyTriggerFired(ConnectionAndTransactionHolder, TriggerFiredUpdate, CancellationToken)'s batch rather than through this, so overriding this alone no longer changes what a fire clears.

ClearTriggerPauses(ConnectionAndTransactionHolder, IReadOnlyCollection<TriggerKey>, CancellationToken)

Forgets the pause recorded on the given triggers, which a resume does.

ValueTask ClearTriggerPauses(ConnectionAndTransactionHolder conn, IReadOnlyCollection<TriggerKey> triggerKeys, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
triggerKeys IReadOnlyCollection<TriggerKey>: The triggers resumed. An empty collection does nothing.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

Remarks

Called after the resume's own statements, which are unchanged, for the triggers they moved. A trigger with no record is left as it is. A default interface member; the default forgets nothing, having recorded nothing.

ClearTriggerRetryAttempt(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Puts a trigger's retry attempt back to zero, leaving everything else about the row alone.

ValueTask<int> ClearTriggerRetryAttempt(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
triggerKey TriggerKey: The trigger to clear.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: How many rows were updated.

Remarks

The other end of UpdateTriggerForRetry(ConnectionAndTransactionHolder, IOperableTrigger, StoredTriggerState, CancellationToken): the occurrence is done with, whether it succeeded or spent its attempts. Issued only when the attempt was actually non-zero, so an ordinary completion still costs no extra statement.

CountMisfiredTriggersInState(ConnectionAndTransactionHolder, StoredTriggerState, DateTimeOffset, CancellationToken)

Counts the triggers in the given state that missed their scheduled fire time.

ValueTask<int> CountMisfiredTriggersInState(ConnectionAndTransactionHolder conn, StoredTriggerState state, DateTimeOffset misfireTime, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
state StoredTriggerState: The trigger state to scan.
misfireTime DateTimeOffset: Triggers with no threshold of their own whose next fire time is at or before this are misfired: now less the store's MisfireThreshold. A trigger with a MISFIRE_THRESHOLD of its own is misfired once its next fire time is at or before now less that, now being the delegate's TimeProvider (#4070).
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>

CountTriggersForJob(ConnectionAndTransactionHolder, JobKey, CancellationToken)

Select the number of triggers associated with a given job.

ValueTask<int> CountTriggersForJob(ConnectionAndTransactionHolder conn, JobKey jobKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKey JobKey: The key identifying the job.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: the number of triggers for the given job

CreateSchema(ConnectionAndTransactionHolder, CancellationToken)

Creates whatever this delegate's schema is missing, and leaves everything that is already there exactly as it is.

ValueTask CreateSchema(ConnectionAndTransactionHolder conn, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

Remarks

Called at startup, before ValidateSchema(ConnectionAndTransactionHolder, CancellationToken), when CreateIfMissing is configured. Every statement it runs is guarded, so this is a no-op against a schema that already exists; nothing is altered and nothing is dropped, which is what makes it safe to leave on and what keeps a mis-typed table prefix from costing data.

It is not a migration. A schema that has every table but is missing a column a later release added is left exactly as it is; upgrading a schema is what database/migrations/ is for. For that reason the store will not call this at all against a schema 4.x did not create — creating the tables a 3.x schema is missing would leave one that starts and fires nothing — so a delegate's script only ever meets a database whose Quartz tables, if it has any, this version made.

A delegate that has no script for its database throws rather than pretending to have created anything, naming itself and the script to run by hand.

Exceptions

JobPersistenceException: A statement failed, or this delegate has no schema script.

DeleteBlobTrigger(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Delete the BLOB trigger data for a trigger.

ValueTask<int> DeleteBlobTrigger(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
triggerKey TriggerKey: The key identifying the trigger.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows deleted

DeleteCalendar(ConnectionAndTransactionHolder, string, CancellationToken)

Delete a calendar.

ValueTask<int> DeleteCalendar(ConnectionAndTransactionHolder conn, string calendarName, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
calendarName string: The name of the trigger.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows deleted.

DeleteFiredTrigger(ConnectionAndTransactionHolder, string, CancellationToken)

Delete a fired trigger.

ValueTask<int> DeleteFiredTrigger(ConnectionAndTransactionHolder conn, string entryId, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
entryId string: The fired trigger entry to delete.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows deleted.

DeleteFiredTriggers(ConnectionAndTransactionHolder, FiredTriggerQuery, CancellationToken)

Deletes the fired triggers the query selects. A query with no filter set deletes all of them.

ValueTask<int> DeleteFiredTriggers(ConnectionAndTransactionHolder conn, FiredTriggerQuery query, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
query FiredTriggerQuery: Which fired triggers to delete.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows deleted

DeleteFiredTriggers(ConnectionAndTransactionHolder, IReadOnlyCollection<string>, CancellationToken)

Delete several fired triggers by entry id, in as few round trips as the provider allows.

ValueTask DeleteFiredTriggers(ConnectionAndTransactionHolder conn, IReadOnlyCollection<string> entryIds, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
entryIds IReadOnlyCollection<string>: The fired trigger entries to delete. An empty collection does nothing.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

Remarks

The same statement as the single-entry overload, once per id, issued as one DbBatch where the provider supports batching. This is the shape cluster recovery needs when it is clearing a dead node's rows but holding some of them back: the whole-instance DeleteFiredTriggers(ConnectionAndTransactionHolder, FiredTriggerQuery, CancellationToken) would take the preserved rows with it. No row count comes back, for the reason UpdateTriggerStatesForJobsFromOtherState(ConnectionAndTransactionHolder, IReadOnlyCollection<JobKey>, StoredTriggerState, StoredTriggerState, CancellationToken) gives.

DeleteJobDetail(ConnectionAndTransactionHolder, JobKey, CancellationToken)

Delete the job detail record for the given job.

ValueTask<int> DeleteJobDetail(ConnectionAndTransactionHolder conn, JobKey jobKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKey JobKey: The key identifying the job.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: the number of rows deleted

DeletePausedJobGroup(ConnectionAndTransactionHolder, GroupMatcher<JobKey>, CancellationToken)

Deletes the paused job groups the matcher selects. A single group is GroupEquals(string).

ValueTask<int> DeletePausedJobGroup(ConnectionAndTransactionHolder conn, GroupMatcher<JobKey> matcher, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The database connection.
matcher GroupMatcher<JobKey>: Criteria for matching groups.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows deleted.

DeletePausedTriggerGroup(ConnectionAndTransactionHolder, GroupMatcher<TriggerKey>, CancellationToken)

Deletes the paused trigger groups the matcher selects. A single group is GroupEquals(string).

ValueTask<int> DeletePausedTriggerGroup(ConnectionAndTransactionHolder conn, GroupMatcher<TriggerKey> matcher, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The database connection.
matcher GroupMatcher<TriggerKey>: Criteria for matching groups.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>

DeleteSchedulerState(ConnectionAndTransactionHolder, string, CancellationToken)

Delete a scheduler-instance state record.

ValueTask<int> DeleteSchedulerState(ConnectionAndTransactionHolder conn, string instanceId, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
instanceId string: The instance id.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of deleted rows.

DeleteTrigger(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Delete the base trigger data for a trigger.

ValueTask<int> DeleteTrigger(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
triggerKey TriggerKey: The key identifying the trigger.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: the number of rows deleted

Initialize(DriverDelegateContext)

Initializes the driver delegate with the settings it works from.

void Initialize(DriverDelegateContext context)

Parameters

context DriverDelegateContext: The settings the store was configured with.

Remarks

Called once by the job store before the delegate is used. There is no default implementation: a delegate that does not read the context has no table prefix, provider or serializer, and would fail at its first statement rather than at startup.

InsertBlobTrigger(ConnectionAndTransactionHolder, IOperableTrigger, CancellationToken)

Insert the blob trigger data.

ValueTask<int> InsertBlobTrigger(ConnectionAndTransactionHolder conn, IOperableTrigger trigger, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
trigger IOperableTrigger: The trigger to insert
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows inserted

InsertCalendar(ConnectionAndTransactionHolder, string, ICalendar, CancellationToken)

Insert a new calendar.

ValueTask<int> InsertCalendar(ConnectionAndTransactionHolder conn, string calendarName, ICalendar calendar, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
calendarName string: The name for the new calendar.
calendar ICalendar: The calendar.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows inserted.

InsertFiredTrigger(ConnectionAndTransactionHolder, IOperableTrigger, StoredTriggerState, IJobDetail?, CancellationToken)

Insert a fired trigger.

ValueTask<int> InsertFiredTrigger(ConnectionAndTransactionHolder conn, IOperableTrigger trigger, StoredTriggerState state, IJobDetail? jobDetail, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
trigger IOperableTrigger: The trigger.
state StoredTriggerState: The state that the trigger should be stored in.
jobDetail IJobDetail: The job detail.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows inserted.

InsertFiredTriggers(ConnectionAndTransactionHolder, IReadOnlyList<IOperableTrigger>, StoredTriggerState, IJobDetail?, CancellationToken)

Inserts the fired-trigger rows of one acquisition round in as few round trips as the provider allows.

ValueTask InsertFiredTriggers(ConnectionAndTransactionHolder conn, IReadOnlyList<IOperableTrigger> triggers, StoredTriggerState state, IJobDetail? jobDetail, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
triggers IReadOnlyList<IOperableTrigger>: The triggers to record, in the order they were acquired.
state StoredTriggerState: The state that the triggers should be stored in.
jobDetail IJobDetail: The job detail, or null when no job is named yet.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

Remarks

The rows are all in the same state and belong to the same job detail, which is what an acquisition round produces: every row goes in as Acquired with no job named yet. The default implementation is the loop the store used to make itself, so a delegate that says nothing about batching keeps behaving exactly as it did.

InsertJobDetail(ConnectionAndTransactionHolder, IJobDetail, CancellationToken)

Insert the job detail record.

ValueTask<int> InsertJobDetail(ConnectionAndTransactionHolder conn, IJobDetail job, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
job IJobDetail: The job to insert.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: Number of rows inserted.

InsertJobGroupPauses(ConnectionAndTransactionHolder, IReadOnlyCollection<string>, PauseInfo, CancellationToken)

Records that each of the given job groups is paused, and why.

ValueTask InsertJobGroupPauses(ConnectionAndTransactionHolder conn, IReadOnlyCollection<string> groupNames, PauseInfo pause, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
groupNames IReadOnlyCollection<string>: The groups to pause. May be empty.
pause PauseInfo: What to record on each.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

Remarks

InsertPausedJobGroups(ConnectionAndTransactionHolder, IReadOnlyCollection<string>, CancellationToken) with the record. A default interface member; the default calls InsertPausedJobGroups(ConnectionAndTransactionHolder, IReadOnlyCollection<string>, CancellationToken).

InsertPausedJobGroup(ConnectionAndTransactionHolder, string, CancellationToken)

Records that a job group is paused.

ValueTask<int> InsertPausedJobGroup(ConnectionAndTransactionHolder conn, string groupName, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The database connection.
groupName string: Name of the group.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows inserted.

Remarks

The row is what makes the pause outlive the process and reach the other nodes of a cluster, and what a caller adding a job to the group later reads. The table's primary key rejects a duplicate, so callers check first — under the trigger-access lock, which is what keeps two nodes pausing the same group from racing.

InsertPausedJobGroups(ConnectionAndTransactionHolder, IReadOnlyCollection<string>, CancellationToken)

Writes a paused row for each of the given job groups, in as few round trips as the provider allows.

ValueTask InsertPausedJobGroups(ConnectionAndTransactionHolder conn, IReadOnlyCollection<string> groupNames, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The database connection.
groupNames IReadOnlyCollection<string>: The groups to pause. May be empty.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

Remarks

Every group is expected to have no row yet — the caller established that with SelectPausedJobGroups(ConnectionAndTransactionHolder, IReadOnlyCollection<string>, CancellationToken) under the same lock — so this is a plain insert per group rather than an upsert. The default implementation issues them one at a time.

InsertPausedTriggerGroup(ConnectionAndTransactionHolder, string, CancellationToken)

Inserts the paused trigger group.

ValueTask<int> InsertPausedTriggerGroup(ConnectionAndTransactionHolder conn, string groupName, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The conn.
groupName string: Name of the group.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>

InsertSchedulerState(ConnectionAndTransactionHolder, string, DateTimeOffset, TimeSpan, CancellationToken)

Insert a scheduler-instance state record.

ValueTask<int> InsertSchedulerState(ConnectionAndTransactionHolder conn, string instanceId, DateTimeOffset checkInTime, TimeSpan interval, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
instanceId string: The instance id.
checkInTime DateTimeOffset: The check in time.
interval TimeSpan: The interval.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of inserted rows.

InsertTrigger(ConnectionAndTransactionHolder, IOperableTrigger, StoredTriggerState, IJobDetail, CancellationToken)

Insert the base trigger data.

ValueTask<int> InsertTrigger(ConnectionAndTransactionHolder conn, IOperableTrigger trigger, StoredTriggerState state, IJobDetail jobDetail, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
trigger IOperableTrigger: The trigger to insert.
state StoredTriggerState: The state that the trigger should be stored in.
jobDetail IJobDetail: The job detail.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows inserted

InsertTriggerGroupPause(ConnectionAndTransactionHolder, string, PauseInfo, CancellationToken)

Records that a trigger group is paused, and why.

ValueTask<int> InsertTriggerGroupPause(ConnectionAndTransactionHolder conn, string groupName, PauseInfo pause, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
groupName string: Name of the group.
pause PauseInfo: What to record.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows inserted.

Remarks

InsertPausedTriggerGroup(ConnectionAndTransactionHolder, string, CancellationToken) with the record. A default interface member; the default calls InsertPausedTriggerGroup(ConnectionAndTransactionHolder, string, CancellationToken).

IsJobCurrentlyExecuting(ConnectionAndTransactionHolder, JobKey, CancellationToken)

Checks whether a job is currently being executed (has a fired trigger in EXECUTING state). Used to enforce DisallowConcurrentExecutionAttribute across cluster nodes.

ValueTask<bool> IsJobCurrentlyExecuting(ConnectionAndTransactionHolder conn, JobKey jobKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKey JobKey: The key identifying the job.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<bool>

IsJobGroupPaused(ConnectionAndTransactionHolder, string, CancellationToken)

Determines whether the specified job group is paused.

ValueTask<bool> IsJobGroupPaused(ConnectionAndTransactionHolder conn, string groupName, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The database connection.
groupName string: Name of the group.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<bool>: true if the job group is paused; otherwise, false.

IsTriggerCurrentlyExecuting(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Checks whether a trigger has a firing in EXECUTING state, on any node. Used by a trigger's OverlapPolicy across cluster nodes.

ValueTask<bool> IsTriggerCurrentlyExecuting(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
triggerKey TriggerKey: The key identifying the trigger.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<bool>

Remarks

A default interface member, so a delegate written against an earlier 4.x keeps compiling. The default reads the trigger's fired rows through SelectFiredTriggerRecords(ConnectionAndTransactionHolder, FiredTriggerQuery, CancellationToken); StdAdoDelegate counts them instead.

IsTriggerGroupPaused(ConnectionAndTransactionHolder, string, CancellationToken)

Determines whether the specified trigger group is paused.

ValueTask<bool> IsTriggerGroupPaused(ConnectionAndTransactionHolder conn, string groupName, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The conn.
groupName string: Name of the group.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<bool>: true if trigger group is paused; otherwise, false.

JobExists(ConnectionAndTransactionHolder, JobKey, CancellationToken)

Check whether or not the given job exists.

ValueTask<bool> JobExists(ConnectionAndTransactionHolder conn, JobKey jobKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKey JobKey: The key identifying the job.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<bool>: true if the job exists, false otherwise

PauseTriggerGroupStates(ConnectionAndTransactionHolder, GroupMatcher<TriggerKey>, StoredTriggerState, IReadOnlyCollection<StoredTriggerState>, PauseInfo, CancellationToken)

Moves every trigger of the matching groups that is in one of oldStates to newState, recording pause on each row it moves.

ValueTask<int> PauseTriggerGroupStates(ConnectionAndTransactionHolder conn, GroupMatcher<TriggerKey> matcher, StoredTriggerState newState, IReadOnlyCollection<StoredTriggerState> oldStates, PauseInfo pause, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
matcher GroupMatcher<TriggerKey>: The groups whose triggers to pause.
newState StoredTriggerState: The paused state to move them to.
oldStates IReadOnlyCollection<StoredTriggerState>: The states a trigger must be in to be moved. Must not be empty.
pause PauseInfo: What to record on each row moved.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows moved.

Remarks

The pause form of UpdateTriggerGroupStateFromOtherStates(ConnectionAndTransactionHolder, GroupMatcher<TriggerKey>, StoredTriggerState, IReadOnlyCollection<StoredTriggerState>, CancellationToken). A default interface member; the default moves the rows and records nothing.

PauseTriggerStates(ConnectionAndTransactionHolder, IReadOnlyCollection<TriggerKey>, StoredTriggerState, IReadOnlyCollection<StoredTriggerState>, PauseInfo, CancellationToken)

Moves the given triggers that are in one of oldStates to newState, recording pause on each row it moves.

ValueTask<int> PauseTriggerStates(ConnectionAndTransactionHolder conn, IReadOnlyCollection<TriggerKey> triggerKeys, StoredTriggerState newState, IReadOnlyCollection<StoredTriggerState> oldStates, PauseInfo pause, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
triggerKeys IReadOnlyCollection<TriggerKey>: The triggers to pause.
newState StoredTriggerState: The paused state to move them to.
oldStates IReadOnlyCollection<StoredTriggerState>: The states a trigger must be in to be moved. Must not be empty.
pause PauseInfo: What to record on each row moved.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows moved.

Remarks

The pause form of UpdateTriggerStatesFromOtherStates(ConnectionAndTransactionHolder, IReadOnlyCollection<TriggerKey>, StoredTriggerState, IReadOnlyCollection<StoredTriggerState>, CancellationToken), in one statement so a row is never paused without its record. A default interface member, so a delegate written against an earlier 4.x keeps compiling; the default moves the rows and records nothing.

ReleaseContinuation(ConnectionAndTransactionHolder, TriggerKey, StoredTriggerState, DateTimeOffset, CancellationToken)

Moves one awaiting trigger into the ordinary schedule, firing at fireTime, and clears the continuation columns: a released trigger is an ordinary one and waits for nothing.

ValueTask<int> ReleaseContinuation(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, StoredTriggerState newState, DateTimeOffset fireTime, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
triggerKey TriggerKey: The awaiting trigger to release.
newState StoredTriggerState: The state to release it into — the one a trigger stored at this moment would get: waiting, paused if its group is, blocked if its job disallows concurrent execution and is running.
fireTime DateTimeOffset: When the released trigger fires, as the store worked it out: the later of now and the trigger's start time, moved on to its calendar's next included instant when the calendar excludes that one. A continuation whose end time is behind that instant is discarded rather than released, so this is never past the trigger's end time.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: How many rows were updated.

Remarks

Only a row still in Awaiting is written, which is what makes settlement one-shot. A default interface member for the reason SelectAwaitingContinuations(ConnectionAndTransactionHolder, TriggerKey, CancellationToken) is one, but this default refuses: it is only ever reached for a continuation that member found, so a delegate that answers that one and not this one is half-implemented rather than merely old.

RepinTriggersFromDeadNode(ConnectionAndTransactionHolder, string, string, CancellationToken)

Releases all auto-claimed pins belonging to a dead node back to the given value (batch UPDATE). Explicit pins are left untouched. Used during ClusterRecover to implement sticky failover.

ValueTask<int> RepinTriggersFromDeadNode(ConnectionAndTransactionHolder conn, string oldPreferredNode, string newPreferredNode, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder
oldPreferredNode string
newPreferredNode string
cancellationToken CancellationToken

Returns

ValueTask<int>

ResetContinuationFireTime(ConnectionAndTransactionHolder, TriggerKey, DateTimeOffset, CancellationToken)

Gives a continuation that has just been reset out of the error state a fire time, and clears its continuation columns, the same way ReleaseContinuation(ConnectionAndTransactionHolder, TriggerKey, StoredTriggerState, DateTimeOffset, CancellationToken) does.

ValueTask<int> ResetContinuationFireTime(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, DateTimeOffset now, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
triggerKey TriggerKey: The trigger that was just reset.
now DateTimeOffset: The scheduler's reading of "now", which the fire time is floored at.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: How many rows were updated.

Remarks

Touches only a row that names a parent — in the error state, a continuation parked because its parent was deleted, since a released one names none — so an ordinary trigger's reset costs a statement that matches nothing. A default interface member that does nothing: a delegate with no continuation columns has no such row to fix.

SelectAwaitingContinuations(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

The triggers waiting, in Awaiting, for one trigger's firing — and the condition each of them waits on.

ValueTask<List<AwaitingContinuation>> SelectAwaitingContinuations(ConnectionAndTransactionHolder conn, TriggerKey parent, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
parent TriggerKey: The trigger whose firing the returned triggers are waiting for.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<AwaitingContinuation>>

Remarks

A default interface member, added in 4.2: a delegate written against an earlier 4.x reports nothing rather than failing every completion, which is the truth for it — a delegate that does not write the continuation columns never has a row to find. The default is the reason the other two members below can afford to refuse.

SelectCalendar(ConnectionAndTransactionHolder, string, CancellationToken)

Select a calendar.

ValueTask<ICalendar?> SelectCalendar(ConnectionAndTransactionHolder conn, string calendarName, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
calendarName string: The name of the calendar.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<ICalendar>: The Calendar.

SelectCalendarNames(ConnectionAndTransactionHolder, CalendarQuery, CancellationToken)

Selects one page of calendar names, ordered by name.

ValueTask<PagedResult<string>> SelectCalendarNames(ConnectionAndTransactionHolder conn, CalendarQuery query, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
query CalendarQuery: Which names to select and which page of them to return.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<PagedResult<string>>

SelectExecutionGroupsInFlight(ConnectionAndTransactionHolder, CancellationToken)

Counts what the cluster currently holds in flight for each (execution group, trigger group) pair, which is what a Cluster execution limit is counted against.

ValueTask<List<ExecutionGroupInFlight>> SelectExecutionGroupsInFlight(ConnectionAndTransactionHolder conn, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<ExecutionGroupInFlight>>: One entry per distinct pair with work in flight; empty when the cluster is idle.

Remarks

The answer is an aggregate over the fired-triggers table, whose rows already have exactly the lifetime a reservation needs: written when a trigger is acquired, updated when it fires, deleted when it completes or when cluster recovery cleans up after the node that owned it. So the count includes a peer's reservation that has not started yet, and a dead node's rows keep holding slots until recovery clears them — under-serving the quota rather than over-serving it, which is the safe direction.

Both group names are returned because the limits derive their key from the pair; see ExecutionGroupInFlight. Rows are bounded by the distinct pairs currently in flight, not by the size of the schedule.

SelectFireInstances(ConnectionAndTransactionHolder, FireInstanceQuery, CancellationToken)

Selects one page of fire instances, ordered by trigger group, then trigger name, then entry id.

ValueTask<PagedResult<FireInstance>> SelectFireInstances(ConnectionAndTransactionHolder conn, FireInstanceQuery query, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
query FireInstanceQuery: What to select and which page of it to return.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<PagedResult<FireInstance>>

Remarks

The listing reads the FIRED_TRIGGERS row only, and only the columns FireInstance projects — not the concurrency and recovery flags that SelectFiredTriggerRecords(ConnectionAndTransactionHolder, FiredTriggerQuery, CancellationToken) reads for the recovery passes. The entry id is part of the ordering because trigger group and name do not identify a row here: one trigger can have several firings at once.

SelectFiredTriggerInstanceNames(ConnectionAndTransactionHolder, CancellationToken)

Select the distinct instance names of all fired-trigger records.

ValueTask<List<string>> SelectFiredTriggerInstanceNames(ConnectionAndTransactionHolder conn, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The conn.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<string>>

Remarks

This is useful when trying to identify orphaned fired triggers (a fired trigger without a scheduler state record.)

SelectFiredTriggerRecords(ConnectionAndTransactionHolder, FiredTriggerQuery, CancellationToken)

Selects the states of the fired-trigger records the query selects. A query with no filter set selects all of them.

ValueTask<List<FiredTriggerRecord>> SelectFiredTriggerRecords(ConnectionAndTransactionHolder conn, FiredTriggerQuery query, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
query FiredTriggerQuery: Which fired triggers to select.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<FiredTriggerRecord>>: A list of FiredTriggerRecord objects.

Remarks

Not a listing — SelectFireInstances(ConnectionAndTransactionHolder, FireInstanceQuery, CancellationToken) is. This one is the whole set, every column, for the maintenance passes that have to see all of it.

SelectJobDetail(ConnectionAndTransactionHolder, JobKey, ITypeLoader, CancellationToken)

Select the JobDetail object for a given job name / group name.

ValueTask<IJobDetail?> SelectJobDetail(ConnectionAndTransactionHolder conn, JobKey jobKey, ITypeLoader typeLoader, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKey JobKey: The key identifying the job.
typeLoader ITypeLoader: The type loader.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<IJobDetail>: The populated JobDetail object

SelectJobDetails(ConnectionAndTransactionHolder, IReadOnlyCollection<JobKey>, ITypeLoader, CancellationToken)

Selects several jobs at once, chunking the keys into as few statements as the provider's parameter ceiling allows. Keys that have no row are simply absent from the result.

ValueTask<List<IJobDetail>> SelectJobDetails(ConnectionAndTransactionHolder conn, IReadOnlyCollection<JobKey> jobKeys, ITypeLoader typeLoader, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
jobKeys IReadOnlyCollection<JobKey>: The keys of the jobs to select.
typeLoader ITypeLoader: The type loader.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<IJobDetail>>

SelectJobForTrigger(ConnectionAndTransactionHolder, TriggerKey, ITypeLoader, bool, CancellationToken)

Select the job to which the trigger is associated.

ValueTask<IJobDetail?> SelectJobForTrigger(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, ITypeLoader typeLoader, bool loadJobType, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
triggerKey TriggerKey: The key identifying the trigger.
typeLoader ITypeLoader: The type loader.
loadJobType bool: Whether to resolve the job's type now, which throws when the class is not in this process. false gets a job detail whose JobType is the recorded name, resolved lazily by whoever comes to run it. It says nothing about the job's two attribute flags: ConcurrentExecutionDisallowed and PersistJobDataAfterExecution come from IS_NONCONCURRENT and IS_UPDATE_DATA either way, so a caller deciding whether a trigger is blocked does not need the class to decide it correctly.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<IJobDetail>

SelectJobGroupPause(ConnectionAndTransactionHolder, string, CancellationToken)

The pause recorded on a paused job group's row, or null when there is no row or it recorded nothing.

ValueTask<PauseInfo?> SelectJobGroupPause(ConnectionAndTransactionHolder conn, string groupName, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
groupName string: The job group to ask about.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<PauseInfo>

Remarks

A default interface member, whose default answers null.

SelectJobGroups(ConnectionAndTransactionHolder, JobGroupQuery, CancellationToken)

Selects one page of job groups, ordered by name.

ValueTask<PagedResult<JobGroup>> SelectJobGroups(ConnectionAndTransactionHolder conn, JobGroupQuery query, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
query JobGroupQuery: What to select and which page of it to return.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<PagedResult<JobGroup>>

Remarks

A query for paused groups only reads PAUSED_JOB_GRPS, so it reports a paused group that currently holds no jobs as well. That table has no counterpart to AllGroupsPaused: pause-all is a trigger operation and writes no marker row here.

SelectJobHeaders(ConnectionAndTransactionHolder, JobQuery, CancellationToken)

Selects one page of job listing entries, ordered by group and then name.

ValueTask<PagedResult<JobHeader>> SelectJobHeaders(ConnectionAndTransactionHolder conn, JobQuery query, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
query JobQuery: What to select and which page of it to return.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<PagedResult<JobHeader>>

Remarks

The listing does not read or deserialize JOB_DATA, and does not load the job type — the header carries the recorded type name as a string.

SelectJobKeysInGroup(ConnectionAndTransactionHolder, GroupMatcher<JobKey>, CancellationToken)

Select the keys of all the jobs a group matcher selects.

ValueTask<List<JobKey>> SelectJobKeysInGroup(ConnectionAndTransactionHolder conn, GroupMatcher<JobKey> matcher, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
matcher GroupMatcher<JobKey>: Criteria for matching groups.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<JobKey>>: The keys of the matching jobs.

Remarks

Not a listing — SelectJobHeaders(ConnectionAndTransactionHolder, JobQuery, CancellationToken) is. This one serves the mutation paths, which need every matching key in one go so that they can update them under the same lock, and which therefore must not be paged.

SelectMisfiredTriggersToRecover(ConnectionAndTransactionHolder, StoredTriggerState, DateTimeOffset, int, CancellationToken)

Selects the misfired triggers to recover as fully populated triggers, rather than as keys that the caller then has to read back one at a time. Same predicate and ordering as CountMisfiredTriggersInState(ConnectionAndTransactionHolder, StoredTriggerState, DateTimeOffset, CancellationToken).

ValueTask<MisfiredTriggerBatch> SelectMisfiredTriggersToRecover(ConnectionAndTransactionHolder conn, StoredTriggerState state, DateTimeOffset misfireTime, int count, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
state StoredTriggerState: The trigger state to scan (Waiting).
misfireTime DateTimeOffset: Triggers with no threshold of their own whose next fire time is at or before this are misfired: now less the store's MisfireThreshold. A trigger with a MISFIRE_THRESHOLD of its own is misfired once its next fire time is at or before now less that, now being the delegate's TimeProvider (#4070).
count int: Maximum number of triggers to return, or -1 for all of them.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<MisfiredTriggerBatch>

SelectPausedJobGroups(ConnectionAndTransactionHolder, IReadOnlyCollection<string>, CancellationToken)

Of the given job groups, which already have a paused row.

ValueTask<List<string>> SelectPausedJobGroups(ConnectionAndTransactionHolder conn, IReadOnlyCollection<string> groupNames, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The database connection.
groupNames IReadOnlyCollection<string>: The groups to ask about. May be empty.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<string>>: The subset of groupNames that is paused.

Remarks

The set form of IsJobGroupPaused(ConnectionAndTransactionHolder, string, CancellationToken), which is what pausing a matcher's worth of job groups actually asks: it needs the groups that do not have a row, so that it can write exactly those. The default implementation asks one group at a time, as that path used to.

SelectSchedulerNames(ConnectionAndTransactionHolder, CancellationToken)

Every scheduler name this database holds anything under, in no particular order.

ValueTask<List<string>> SelectSchedulerNames(ConnectionAndTransactionHolder conn, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<string>>: The distinct SCHED_NAME values in this database.

Remarks

The one member here that is not about the scheduler the delegate was initialized for: it answers which schedulers there are, which is what a dashboard pointed at a database needs before it can have a scheduler name to ask anything else with. A name is reported when the database holds a check-in row, a trigger or a job detail under it — no one of those alone is enough, since a scheduler that is not clustered writes no check-in row and one whose jobs are durable and unscheduled has no triggers.

The default implementation refuses rather than answering, because there is nothing here it could answer with: every other member of this interface is scoped to one scheduler's rows, so a delegate that does not implement this has no cross-scheduler statement to borrow. StdAdoDelegate implements it in dialect-neutral SQL, so a delegate derived from it — which is every delegate Quartz ships and every one its documentation teaches — has it already.

Exceptions

NotSupportedException: This delegate cannot discover scheduler names.

SelectSchedulerStateRecords(ConnectionAndTransactionHolder, string?, CancellationToken)

A List of all current SchedulerStateRecords.

If instanceId is not null, then only the record for the identified instance will be returned.

ValueTask<List<SchedulerStateRecord>> SelectSchedulerStateRecords(ConnectionAndTransactionHolder conn, string? instanceId, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
instanceId string: The instance id, or null for every instance.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<SchedulerStateRecord>>

SelectStoredTriggerHeaders(ConnectionAndTransactionHolder, IReadOnlyCollection<TriggerKey>, CancellationToken)

Selects the stored headers of a whole set of triggers, chunking the keys into as few statements as the provider's parameter ceiling allows. Keys that have no row are simply absent from the result.

ValueTask<List<StoredTriggerHeader>> SelectStoredTriggerHeaders(ConnectionAndTransactionHolder conn, IReadOnlyCollection<TriggerKey> triggerKeys, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
triggerKeys IReadOnlyCollection<TriggerKey>: The keys identifying the triggers. May be empty.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<StoredTriggerHeader>>

Remarks

The plural of SelectTriggerHeader(ConnectionAndTransactionHolder, TriggerKey, CancellationToken) — the storage-side header a state transition decides on, not the listing entry SelectTriggerHeaders(ConnectionAndTransactionHolder, TriggerQuery, CancellationToken) pages over. Pause and resume read one of these per key and then decide the whole set's transitions at once; the default implementation is the per-key loop they used to make.

SelectTrigger(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Select a trigger.

ValueTask<IOperableTrigger?> SelectTrigger(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
triggerKey TriggerKey: The key identifying the trigger.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<IOperableTrigger>: The ITrigger object.

SelectTriggerGroupNames(ConnectionAndTransactionHolder, GroupMatcher<TriggerKey>, CancellationToken)

Select all trigger group names a group matcher selects. Pass AnyGroup() for every group.

ValueTask<List<string>> SelectTriggerGroupNames(ConnectionAndTransactionHolder conn, GroupMatcher<TriggerKey> matcher, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
matcher GroupMatcher<TriggerKey>: The matcher to apply for searching.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<string>>: The names of the matching groups.

Remarks

Not a listing — SelectTriggerGroups(ConnectionAndTransactionHolder, TriggerGroupQuery, CancellationToken) with a TriggerGroupQuery is. This one serves the pause/resume mutation paths, which need every matching group in one go so that they can update them under the same lock, and which therefore must not be paged.

SelectTriggerGroupPause(ConnectionAndTransactionHolder, string, CancellationToken)

The pause recorded on a paused trigger group's row, or null when there is no row or it recorded nothing.

ValueTask<PauseInfo?> SelectTriggerGroupPause(ConnectionAndTransactionHolder conn, string groupName, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
groupName string: The trigger group to ask about.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<PauseInfo>

Remarks

A default interface member, whose default answers null.

SelectTriggerGroups(ConnectionAndTransactionHolder, TriggerGroupQuery, CancellationToken)

Selects one page of trigger groups, ordered by name.

ValueTask<PagedResult<TriggerGroup>> SelectTriggerGroups(ConnectionAndTransactionHolder conn, TriggerGroupQuery query, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
query TriggerGroupQuery: What to select and which page of it to return.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<PagedResult<TriggerGroup>>

Remarks

A query for paused groups only reads PAUSED_TRIGGER_GRPS, so it reports a paused group that currently has no triggers as well. It must not report AllGroupsPaused: that row records "everything is paused" and is not a group any trigger can belong to.

SelectTriggerHeader(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Select the stored state, next fire time and job of one trigger, in a single statement.

ValueTask<StoredTriggerHeader?> SelectTriggerHeader(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
triggerKey TriggerKey: The key identifying the trigger.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<StoredTriggerHeader>: The trigger's header, or null when no such trigger exists.

SelectTriggerHeaders(ConnectionAndTransactionHolder, TriggerQuery, CancellationToken)

Selects one page of trigger listing entries, ordered by group and then name.

ValueTask<PagedResult<TriggerHeader>> SelectTriggerHeaders(ConnectionAndTransactionHolder conn, TriggerQuery query, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
query TriggerQuery: What to select and which page of it to return.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<PagedResult<TriggerHeader>>

Remarks

The listing reads the TRIGGERS row only: no type table, no BLOB, no JOB_DATA.

SelectTriggerJobDataMap(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Select a trigger's JobDataMap.

ValueTask<JobDataMap> SelectTriggerJobDataMap(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
triggerKey TriggerKey: The key identifying the trigger.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<JobDataMap>: The JobDataMap of the Trigger, never null, but possibly empty.

SelectTriggerKeysForJob(ConnectionAndTransactionHolder, JobKey, StoredTriggerState, CancellationToken)

Get the keys of the triggers of the given job that are in the given state.

ValueTask<List<TriggerKey>> SelectTriggerKeysForJob(ConnectionAndTransactionHolder conn, JobKey jobKey, StoredTriggerState state, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKey JobKey: The key identifying the job.
state StoredTriggerState: The state the triggers must be in.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<TriggerKey>>

Remarks

The filtered form of the overload above, for the callers that want the state rather than the trigger — completion bookkeeping asking which of a job's triggers it has just unblocked, where loading each trigger and then asking the database for its state one at a time is a read per trigger for an answer one read can give.

SelectTriggerKeysForJob(ConnectionAndTransactionHolder, JobKey, CancellationToken)

Get the keys of all the triggers associated with the given job.

ValueTask<List<TriggerKey>> SelectTriggerKeysForJob(ConnectionAndTransactionHolder conn, JobKey jobKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKey JobKey: The key identifying the job.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<TriggerKey>>

Remarks

Not a listing — SelectTriggerHeaders(ConnectionAndTransactionHolder, TriggerQuery, CancellationToken) with a job filter is. This one serves the pause/resume and removal mutation paths, which need every key of the job in one go so that they can update them under the same lock, and which therefore must not be paged.

SelectTriggerKeysForJobs(ConnectionAndTransactionHolder, IReadOnlyCollection<JobKey>, CancellationToken)

Get the keys of every trigger belonging to any of the given jobs.

ValueTask<List<TriggerKey>> SelectTriggerKeysForJobs(ConnectionAndTransactionHolder conn, IReadOnlyCollection<JobKey> jobKeys, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKeys IReadOnlyCollection<JobKey>: The keys identifying the jobs. May be empty.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<TriggerKey>>

Remarks

The job-set form of the first overload above, for pausing and resuming a whole matcher's worth of jobs: what those paths want is one flat set of trigger keys, and reading it a job at a time is a statement per job for an answer one statement can give. The default implementation is that per-job loop.

SelectTriggerKeysInGroup(ConnectionAndTransactionHolder, GroupMatcher<TriggerKey>, CancellationToken)

Select the keys of all the triggers a group matcher selects.

ValueTask<List<TriggerKey>> SelectTriggerKeysInGroup(ConnectionAndTransactionHolder conn, GroupMatcher<TriggerKey> matcher, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
matcher GroupMatcher<TriggerKey>: Criteria for matching groups.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<TriggerKey>>: The keys of the matching triggers.

Remarks

Not a listing — SelectTriggerHeaders(ConnectionAndTransactionHolder, TriggerQuery, CancellationToken) is. This one serves the pause/resume mutation paths, which need every matching key in one go so that they can update them under the same lock, and which therefore must not be paged.

SelectTriggerKeysInState(ConnectionAndTransactionHolder, IReadOnlyCollection<TriggerKey>, StoredTriggerState, CancellationToken)

Select which of the given triggers are in the given state.

ValueTask<List<TriggerKey>> SelectTriggerKeysInState(ConnectionAndTransactionHolder conn, IReadOnlyCollection<TriggerKey> triggerKeys, StoredTriggerState state, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
triggerKeys IReadOnlyCollection<TriggerKey>: The keys to ask about.
state StoredTriggerState: The state the triggers must be in.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<TriggerKey>>: The keys of those triggers that are in the state.

Remarks

The set-taking form of SelectTriggerState(ConnectionAndTransactionHolder, TriggerKey, CancellationToken), for a caller that already holds the keys — cluster recovery asking which of a failed node's triggers ran to COMPLETE, where a state per key is a round trip per key for an answer one read gives. A key with no row, or with a row in another state, is simply absent from the result.

SelectTriggerPause(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

The pause recorded for a trigger that is paused: its own record, or its trigger group's — the pause-all marker's, for a group row written with no record of its own — or its job group's.

ValueTask<PauseInfo?> SelectTriggerPause(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
triggerKey TriggerKey: The trigger to ask about.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<PauseInfo>

Remarks

null for a trigger that is missing or not PAUSED or PAUSED_BLOCKED — so a record a node that does not record pauses left behind when it resumed the trigger is never read — and for one whose pause recorded nothing. A default interface member, whose default answers null.

SelectTriggerState(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Select a trigger's state value.

ValueTask<StoredTriggerState> SelectTriggerState(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
triggerKey TriggerKey: The key identifying the trigger.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<StoredTriggerState>: The trigger's stored state, or Deleted when no such trigger exists.

SelectTriggerStateWithExecuting(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Selects a trigger's stored state together with whether it currently has an execution in flight.

ValueTask<TriggerExecutionState> SelectTriggerStateWithExecuting(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder
triggerKey TriggerKey
cancellationToken CancellationToken

Returns

ValueTask<TriggerExecutionState>: The trigger's state and execution, or NotFound when no such trigger exists.

SelectTriggers(ConnectionAndTransactionHolder, IReadOnlyCollection<TriggerKey>, CancellationToken)

Selects several triggers at once, chunking the keys into as few statements as the provider's parameter ceiling allows. Keys that have no row are simply absent from the result.

ValueTask<List<IOperableTrigger>> SelectTriggers(ConnectionAndTransactionHolder conn, IReadOnlyCollection<TriggerKey> triggerKeys, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
triggerKeys IReadOnlyCollection<TriggerKey>: The keys of the triggers to select.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<IOperableTrigger>>

SelectTriggersForCalendar(ConnectionAndTransactionHolder, string, CancellationToken)

Select the triggers for a calendar

ValueTask<List<IOperableTrigger>> SelectTriggersForCalendar(ConnectionAndTransactionHolder conn, string calendarName, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
calendarName string: Name of the calendar.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<IOperableTrigger>>: An array of ITrigger objects associated with a given job.

SelectTriggersForJob(ConnectionAndTransactionHolder, JobKey, CancellationToken)

Select the triggers for a job>

ValueTask<List<IOperableTrigger>> SelectTriggersForJob(ConnectionAndTransactionHolder conn, JobKey jobKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKey JobKey: The key identifying the job.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<IOperableTrigger>>: an array of ITrigger objects associated with a given job.

SelectTriggersForRecoveringJobs(ConnectionAndTransactionHolder, CancellationToken)

Select all of the triggers for jobs that are requesting recovery. The returned trigger objects will have unique "recoverXXX" trigger names and will be in the DefaultRecoveryGroup trigger group. Each keeps the execution group its firing's trigger carried.

ValueTask<List<IOperableTrigger>> SelectTriggersForRecoveringJobs(ConnectionAndTransactionHolder conn, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<IOperableTrigger>>: An array of ITrigger objects

Remarks

In order to preserve the ordering of the triggers, the fire time will be set from the ColumnFiredTime column in the TableFiredTriggers table. The caller is responsible for calling ComputeFirstFireTimeUtc(ICalendar?) on each returned trigger. It is also up to the caller to insert the returned triggers to ensure that they are fired. Each trigger's data map names the firing it replays under FailedJobOriginalTriggerName and the keys beside it; a replay of a recovery trigger keeps the names that trigger's map already carries.

SelectTriggersInState(ConnectionAndTransactionHolder, StoredTriggerState, CancellationToken)

Select all the triggers in a given state.

ValueTask<List<TriggerKey>> SelectTriggersInState(ConnectionAndTransactionHolder conn, StoredTriggerState state, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
state StoredTriggerState: The state the triggers must be in.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<TriggerKey>>: An array of trigger TriggerKeys.

SelectTriggersToAcquire(ConnectionAndTransactionHolder, TriggerAcquisitionCriteria, CancellationToken)

Selects the next triggers to fire, in ascending order of fire time and then descending by priority.

ValueTask<List<TriggerAcquireResult>> SelectTriggersToAcquire(ConnectionAndTransactionHolder conn, TriggerAcquisitionCriteria criteria, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
criteria TriggerAcquisitionCriteria: What to acquire, and how much of it.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<TriggerAcquireResult>>: A (never null, possibly empty) list of the next triggers to be fired, refused candidates flagged.

Remarks

A candidate refused for its execution group's limit is best returned with ExecutionGroupAtLimit set rather than left out: the store counts such a row as one it read and skipped, and reads past it to what is due behind it. A delegate that leaves the row out instead still works, but a node reading one trigger at a time cannot then see past a group at its limit (#3928). Every dialect Quartz ships flags the row.

TriggerExists(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Check whether or not a trigger exists.

ValueTask<bool> TriggerExists(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: the DB Connection
triggerKey TriggerKey: The key identifying the trigger.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<bool>: the number of rows updated

UpdateBlobTrigger(ConnectionAndTransactionHolder, IOperableTrigger, CancellationToken)

Update the blob trigger data.

ValueTask<int> UpdateBlobTrigger(ConnectionAndTransactionHolder conn, IOperableTrigger trigger, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: the DB Connection
trigger IOperableTrigger: The trigger.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: the number of rows updated

UpdateCalendar(ConnectionAndTransactionHolder, string, ICalendar, CancellationToken)

Update a calendar.

ValueTask<int> UpdateCalendar(ConnectionAndTransactionHolder conn, string calendarName, ICalendar calendar, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
calendarName string: The name for the new calendar.
calendar ICalendar: The calendar.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows updated.

UpdateJobData(ConnectionAndTransactionHolder, IJobDetail, CancellationToken)

Update the job data map for the given job.

ValueTask<int> UpdateJobData(ConnectionAndTransactionHolder conn, IJobDetail job, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
job IJobDetail: The job.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: the number of rows updated

UpdateJobDetail(ConnectionAndTransactionHolder, IJobDetail, CancellationToken)

Update the job detail record.

ValueTask<int> UpdateJobDetail(ConnectionAndTransactionHolder conn, IJobDetail job, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection.
job IJobDetail: The job to update.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: Number of rows updated.

UpdateMisfireOriginalFireTime(ConnectionAndTransactionHolder, TriggerKey, DateTimeOffset?, CancellationToken)

Updates the misfire original fire time for the given trigger.

ValueTask UpdateMisfireOriginalFireTime(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, DateTimeOffset? fireTime, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder
triggerKey TriggerKey
fireTime DateTimeOffset?
cancellationToken CancellationToken

Returns

ValueTask

UpdateMisfiredTrigger(ConnectionAndTransactionHolder, IOperableTrigger, StoredTriggerState, DateTimeOffset?, CancellationToken)

Performs a targeted UPDATE of only the columns that change during misfire recovery, bypassing the heavyweight AddTrigger / UpdateTrigger path which performs many unnecessary SELECTs (existence check, pause-group checks, job retrieval, trigger-type lookup) that are redundant for a trigger known to be in WAITING state.

ValueTask UpdateMisfiredTrigger(ConnectionAndTransactionHolder conn, IOperableTrigger trigger, StoredTriggerState newState, DateTimeOffset? misfireOriginalFireTime, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
trigger IOperableTrigger: The trigger after UpdateAfterMisfire has been applied in-memory.
newState StoredTriggerState: The new trigger state to persist (e.g. WAITING, COMPLETE, BLOCKED).
misfireOriginalFireTime DateTimeOffset?: The original scheduled fire time for "fire now" misfire policies. When non-null, the value is written to the MISFIRE_ORIG_FIRE_TIME column. null leaves the column unchanged, preserving any previously stored original fire time.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

UpdateMisfiredTriggers(ConnectionAndTransactionHolder, IReadOnlyList<MisfiredTriggerUpdate>, CancellationToken)

Applies a whole batch of misfire updates. Semantically identical to calling UpdateMisfiredTrigger(ConnectionAndTransactionHolder, IOperableTrigger, StoredTriggerState, DateTimeOffset?, CancellationToken) once per entry, but collapses the statements into a single round-trip on providers that support batching.

ValueTask UpdateMisfiredTriggers(ConnectionAndTransactionHolder conn, IReadOnlyList<MisfiredTriggerUpdate> updates, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
updates IReadOnlyList<MisfiredTriggerUpdate>: The triggers, after UpdateAfterMisfire has been applied in-memory.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

UpdateMisfiredTriggersIfUnchanged(ConnectionAndTransactionHolder, IReadOnlyList<MisfiredTriggerUpdate>, CancellationToken)

UpdateMisfiredTriggers(ConnectionAndTransactionHolder, IReadOnlyList<MisfiredTriggerUpdate>, CancellationToken), writing each row only while it still holds the fire time its misfire was decided from (ExpectedNextFireTimeUtc), and saying which rows were written.

ValueTask<List<TriggerKey>> UpdateMisfiredTriggersIfUnchanged(ConnectionAndTransactionHolder conn, IReadOnlyList<MisfiredTriggerUpdate> updates, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
updates IReadOnlyList<MisfiredTriggerUpdate>: The triggers, after UpdateAfterMisfire has been applied in-memory.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<TriggerKey>>: The keys of the triggers whose row took the write, in the order given.

Remarks

The misfire handler reads under TRIGGER_ACCESS; a firing round of work that allows concurrent execution takes no lock (#4067), so a row exactly a misfire threshold late can be in both their reads, and the round's fire can commit between the handler's read and its write. A write by key would then re-arm the occurrence the round has just fired. Held to the fire time it read, it finds zero rows, and the store neither reports the trigger misfired nor finalized.

A default interface member, so a delegate written against an earlier 4.x keeps compiling; the default calls UpdateMisfiredTriggers(ConnectionAndTransactionHolder, IReadOnlyList<MisfiredTriggerUpdate>, CancellationToken) and answers every key, which is the behaviour such a delegate had. An update whose expectation is null is written as that member writes it, whatever the row holds.

UpdateSchedulerState(ConnectionAndTransactionHolder, string, DateTimeOffset, CancellationToken)

Update a scheduler-instance state record.

ValueTask<int> UpdateSchedulerState(ConnectionAndTransactionHolder conn, string instanceId, DateTimeOffset checkInTime, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
instanceId string: The instance id.
checkInTime DateTimeOffset: The check in time.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of updated rows.

UpdateTrigger(ConnectionAndTransactionHolder, IOperableTrigger, StoredTriggerState, IJobDetail, CancellationToken)

Update the base trigger data.

ValueTask<int> UpdateTrigger(ConnectionAndTransactionHolder conn, IOperableTrigger trigger, StoredTriggerState state, IJobDetail jobDetail, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: the DB Connection
trigger IOperableTrigger: The trigger.
state StoredTriggerState: The state.
jobDetail IJobDetail: The job detail.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: the number of rows updated

Remarks

In a state that is not paused, StdAdoDelegate also clears the row's PAUSE_REASON, PAUSED_BY and PAUSED_AT in the same statement, so a pause that a replace ended cannot be read back by a later reasonless pause. An override that writes its own statement and leaves them out keeps the behaviour before 4.4.

UpdateTriggerForRetry(ConnectionAndTransactionHolder, IOperableTrigger, StoredTriggerState, CancellationToken)

Writes the retry a completing trigger has just scheduled for itself: where it fires next, how many attempts at the current occurrence are behind it, and the state it waits in.

ValueTask<int> UpdateTriggerForRetry(ConnectionAndTransactionHolder conn, IOperableTrigger trigger, StoredTriggerState newState, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
trigger IOperableTrigger: The completing trigger, carrying the retry instant as its next fire time and the incremented attempt.
newState StoredTriggerState: The state to leave the trigger in — waiting, or paused if its group is.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: How many rows were updated.

Remarks

Narrow on purpose. The trigger's schedule has not changed — only which instant it fires at next — so the generic trigger UPDATE would write a row's worth of columns to move one, and would write back a preferred node and a job data map this path has no business touching.

The completion of a simple trigger that measures its interval from completion writes its next fire time through it too, for the same reason: the instant and the state its hold gives way to, with the attempt the row already holds (#4140).

See Also: RetryTrigger

UpdateTriggerGroupStateFromOtherState(ConnectionAndTransactionHolder, GroupMatcher<TriggerKey>, StoredTriggerState, StoredTriggerState, CancellationToken)

Update all of the triggers the group matcher selects to the given new state, if they are in the given old state.

ValueTask<int> UpdateTriggerGroupStateFromOtherState(ConnectionAndTransactionHolder conn, GroupMatcher<TriggerKey> matcher, StoredTriggerState newState, StoredTriggerState oldState, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection
matcher GroupMatcher<TriggerKey>: Criteria for matching groups.
newState StoredTriggerState: The new state for the trigger group
oldState StoredTriggerState: The old state the triggers must be in.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: int the number of rows updated

Remarks

Matcher-based rather than query-based on purpose: this is the pause/resume mutation path, which has to move every matching trigger under one lock and therefore cannot be paged.

UpdateTriggerGroupStateFromOtherStates(ConnectionAndTransactionHolder, GroupMatcher<TriggerKey>, StoredTriggerState, IReadOnlyCollection<StoredTriggerState>, CancellationToken)

Update all triggers the group matcher selects to the given new state, if they are in one of the given old states.

ValueTask<int> UpdateTriggerGroupStateFromOtherStates(ConnectionAndTransactionHolder conn, GroupMatcher<TriggerKey> matcher, StoredTriggerState newState, IReadOnlyCollection<StoredTriggerState> oldStates, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection
matcher GroupMatcher<TriggerKey>: Criteria for matching groups.
newState StoredTriggerState: The new state for the trigger
oldStates IReadOnlyCollection<StoredTriggerState>: The states a trigger must be in to be updated. Must not be empty.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows updated

Remarks

Matcher-based rather than query-based on purpose: this is the pause/resume mutation path, which has to move every matching trigger under one lock and therefore cannot be paged.

UpdateTriggerIfUnchanged(ConnectionAndTransactionHolder, IOperableTrigger, StoredTriggerState, IJobDetail, DateTimeOffset?, CancellationToken)

UpdateTrigger(ConnectionAndTransactionHolder, IOperableTrigger, StoredTriggerState, IJobDetail, CancellationToken), writing the row only while it still holds the fire time it was read with: an editor's read-modify-write of a trigger that a firing round may move in between.

ValueTask<int> UpdateTriggerIfUnchanged(ConnectionAndTransactionHolder conn, IOperableTrigger trigger, StoredTriggerState state, IJobDetail jobDetail, DateTimeOffset? expectedNextFireTimeUtc, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
trigger IOperableTrigger: The trigger, as edited.
state StoredTriggerState: The state to store it in.
jobDetail IJobDetail: The job detail.
expectedNextFireTimeUtc DateTimeOffset?: The next fire time the row held when it was read, or null for a row read with none.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows updated: zero when the row moved, or went, since it was read.

Remarks

An editor holding TRIGGER_ACCESS — UpdateTriggerDetails, a calendar update that recomputes its triggers — reads a trigger's row, changes what it was asked to and writes the row back whole. A firing round of work that allows concurrent execution takes no lock (#4067), so it can fire the row between that read and that write; written back by key, the edit would re-arm the occurrence the round has just fired. Held to NEXT_FIRE_TIME as read, the write finds zero rows instead, and the editor reads the row again and applies the edit to it.

A default interface member, so a delegate written against an earlier 4.x keeps compiling; the default is UpdateTrigger(ConnectionAndTransactionHolder, IOperableTrigger, StoredTriggerState, IJobDetail, CancellationToken) itself, which keeps the behaviour such a delegate had. StdAdoDelegate appends the predicate to the same statement, and writes the trigger's own table only when the row took the write.

UpdateTriggerPreferredNodeConditional(ConnectionAndTransactionHolder, TriggerKey, PreferredNodeTransition, CancellationToken)

Updates the preferred node columns for a trigger only when they still hold the expected values (compare-and-swap). Used by the auto-pin claim/steal in TriggerFired so a concurrent re-pin or clear (e.g. via UpdateTriggerDetails between acquisition and firing) wins over the claim instead of being clobbered by it.

ValueTask<int> UpdateTriggerPreferredNodeConditional(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, PreferredNodeTransition transition, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
triggerKey TriggerKey: The key identifying the trigger.
transition PreferredNodeTransition: The pin the row must still hold, and the one to put in its place.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: Number of rows updated: 1 when the claim succeeded, 0 when the value changed concurrently.

UpdateTriggerState(ConnectionAndTransactionHolder, TriggerKey, StoredTriggerState, CancellationToken)

Update the state for a given trigger.

ValueTask<int> UpdateTriggerState(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, StoredTriggerState state, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
triggerKey TriggerKey: The key identifying the trigger.
state StoredTriggerState: The new state for the trigger.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: the number of rows updated

UpdateTriggerStateFromOtherState(ConnectionAndTransactionHolder, TriggerKey, StoredTriggerState, StoredTriggerState, CancellationToken)

Update the given trigger to the given new state, if it is in the given old state.

ValueTask<int> UpdateTriggerStateFromOtherState(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, StoredTriggerState newState, StoredTriggerState oldState, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection
triggerKey TriggerKey: The key identifying the trigger.
newState StoredTriggerState: The new state for the trigger
oldState StoredTriggerState: The old state the trigger must be in
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: int the number of rows updated

UpdateTriggerStateFromOtherStateWithNextFireTime(ConnectionAndTransactionHolder, TriggerKey, StoredTriggerState, StoredTriggerState, DateTimeOffset, CancellationToken)

Update the given trigger to the given new state, if it is in the given old state and has the given next fire time.

ValueTask<int> UpdateTriggerStateFromOtherStateWithNextFireTime(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, StoredTriggerState newState, StoredTriggerState oldState, DateTimeOffset nextFireTime, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection
triggerKey TriggerKey: The key identifying the trigger.
newState StoredTriggerState: The new state for the trigger
oldState StoredTriggerState: The old state the trigger must be in
nextFireTime DateTimeOffset: The next fire time the trigger must have
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: int the number of rows updated

UpdateTriggerStateFromOtherStates(ConnectionAndTransactionHolder, TriggerKey, StoredTriggerState, IReadOnlyCollection<StoredTriggerState>, CancellationToken)

Update the given trigger to the given new state, if it is one of the given old states.

ValueTask<int> UpdateTriggerStateFromOtherStates(ConnectionAndTransactionHolder conn, TriggerKey triggerKey, StoredTriggerState newState, IReadOnlyCollection<StoredTriggerState> oldStates, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection
triggerKey TriggerKey: The key identifying the trigger.
newState StoredTriggerState: The new state for the trigger
oldStates IReadOnlyCollection<StoredTriggerState>: The states the trigger must be in to be updated. Must not be empty.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: int the number of rows updated

UpdateTriggerStatesForJob(ConnectionAndTransactionHolder, JobKey, StoredTriggerState, CancellationToken)

Update the states of all triggers associated with the given job, leaving any trigger in Awaiting as it is.

ValueTask<int> UpdateTriggerStatesForJob(ConnectionAndTransactionHolder conn, JobKey jobKey, StoredTriggerState state, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKey JobKey: The key identifying the job.
state StoredTriggerState: The new state for the triggers.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows updated

Remarks

The statement behind SetAllJobTriggersError and SetAllJobTriggersComplete, both issued by a completion of one of the job's triggers. An awaiting trigger belongs to its parent's settlement rather than to that firing, and moved to another state it would be waiting for its parent in a state the parent's completion cannot release it from.

UpdateTriggerStatesForJobFromOtherState(ConnectionAndTransactionHolder, JobKey, StoredTriggerState, StoredTriggerState, CancellationToken)

Update the states of any triggers associated with the given job, that are the given current state.

ValueTask<int> UpdateTriggerStatesForJobFromOtherState(ConnectionAndTransactionHolder conn, JobKey jobKey, StoredTriggerState newState, StoredTriggerState oldState, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKey JobKey: The key identifying the job.
newState StoredTriggerState: The new state for the triggers
oldState StoredTriggerState: The old state of the triggers
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: the number of rows updated

UpdateTriggerStatesForJobFromOtherState(ConnectionAndTransactionHolder, JobKey, IReadOnlyList<TriggerStateTransition>, CancellationToken)

Apply several conditional state changes to a job's triggers in as few round trips as the provider allows.

ValueTask UpdateTriggerStatesForJobFromOtherState(ConnectionAndTransactionHolder conn, JobKey jobKey, IReadOnlyList<TriggerStateTransition> transitions, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKey JobKey: The key identifying the job.
transitions IReadOnlyList<TriggerStateTransition>: The state changes to apply, in order.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

Remarks

The transitions are applied in the order given, so a set of them that overlaps means what issuing them one after another meant. Blocking and unblocking a job's triggers is always two or three of these at once, which is two or three round trips inside the trigger-access lock when they travel separately.

UpdateTriggerStatesForJobsFromOtherState(ConnectionAndTransactionHolder, IReadOnlyCollection<JobKey>, StoredTriggerState, StoredTriggerState, CancellationToken)

Apply the same conditional state change to the triggers of each of several jobs, in as few round trips as the provider allows.

ValueTask UpdateTriggerStatesForJobsFromOtherState(ConnectionAndTransactionHolder conn, IReadOnlyCollection<JobKey> jobKeys, StoredTriggerState newState, StoredTriggerState oldState, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
jobKeys IReadOnlyCollection<JobKey>: The keys identifying the jobs. An empty collection does nothing.
newState StoredTriggerState: The new state for the triggers
oldState StoredTriggerState: The old state a trigger must be in to be updated
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask

Remarks

The same statement as the single-job overload, once per job key, issued as one DbBatch where the provider supports batching. Cluster recovery unblocks the siblings of every interrupted execution, which is one or two of these per fired-trigger row when they travel separately — and the same job over and over when a dead node left several rows behind. No row count comes back: a batch does not report one per command in any portable way, and the caller counts the rows it asked about rather than the rows that moved.

UpdateTriggerStatesFromOtherStateWithNextFireTime(ConnectionAndTransactionHolder, IReadOnlyList<TriggerClaim>, StoredTriggerState, StoredTriggerState, CancellationToken)

Update each of the given triggers to the given new state, if it is in the given old state and still has the next fire time it is claimed with.

ValueTask<List<TriggerKey>> UpdateTriggerStatesFromOtherStateWithNextFireTime(ConnectionAndTransactionHolder conn, IReadOnlyList<TriggerClaim> claims, StoredTriggerState newState, StoredTriggerState oldState, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
claims IReadOnlyList<TriggerClaim>: The triggers to claim, each with the next fire time it was read with.
newState StoredTriggerState: The new state for the triggers.
oldState StoredTriggerState: The old state each trigger must be in.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<List<TriggerKey>>: The keys of the triggers whose row moved, in the order given. A claim that found its row in another state, or due at another time, is absent.

Remarks

The plural of UpdateTriggerStateFromOtherStateWithNextFireTime(ConnectionAndTransactionHolder, TriggerKey, StoredTriggerState, StoredTriggerState, DateTimeOffset, CancellationToken), for an acquisition that fires what is due in the same transaction (#3864): its claims go together, where the provider can batch them. StdAdoDelegate sends them as one DbBatch. Called only for a delegate that answers SupportsFireOnAcquire with true.

A default interface member, so a delegate written against an earlier 4.x keeps working: the default is the single-trigger call for each claim, in order.

UpdateTriggerStatesFromOtherStates(ConnectionAndTransactionHolder, StoredTriggerState, IReadOnlyCollection<StoredTriggerState>, CancellationToken)

Update all triggers having one of the given states, to the given new state.

ValueTask<int> UpdateTriggerStatesFromOtherStates(ConnectionAndTransactionHolder conn, StoredTriggerState newState, IReadOnlyCollection<StoredTriggerState> oldStates, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB Connection
newState StoredTriggerState: The new state for the triggers
oldStates IReadOnlyCollection<StoredTriggerState>: The states a trigger must be in to be updated. Must not be empty.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: Number of rows updated

UpdateTriggerStatesFromOtherStates(ConnectionAndTransactionHolder, IReadOnlyCollection<TriggerKey>, StoredTriggerState, IReadOnlyCollection<StoredTriggerState>, CancellationToken)

Moves a whole set of triggers to the given new state, each one only if it is in one of the given old states.

ValueTask<int> UpdateTriggerStatesFromOtherStates(ConnectionAndTransactionHolder conn, IReadOnlyCollection<TriggerKey> triggerKeys, StoredTriggerState newState, IReadOnlyCollection<StoredTriggerState> oldStates, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection
triggerKeys IReadOnlyCollection<TriggerKey>: The keys identifying the triggers. May be empty.
newState StoredTriggerState: The new state for the triggers
oldStates IReadOnlyCollection<StoredTriggerState>: The states a trigger must be in to be updated. Must not be empty.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of rows updated.

Remarks

The key-set form of the member above, for the paths that decide one transition for a set of keys and then have no reason to issue it a key at a time: pause, resume, and cluster recovery releasing every trigger a dead node had reserved. A set of one old state is how a caller that wants exactly one asks for it.

The default implementation is the per-key loop, so a delegate that says nothing about key sets keeps behaving as it did. StdAdoDelegate issues one UPDATE with a key-set predicate per chunk, so the row count is the database's own and not a tally of what was asked about.

ValidateSchema(ConnectionAndTransactionHolder, CancellationToken)

Verifies that the schema objects this delegate reads and writes are there, and reports how many were checked.

ValueTask<int> ValidateSchema(ConnectionAndTransactionHolder conn, CancellationToken cancellationToken = default)

Parameters

conn ConnectionAndTransactionHolder: The DB connection.
cancellationToken CancellationToken: The cancellation instruction.

Returns

ValueTask<int>: The number of schema objects validated.

Remarks

Called at startup for every SchemaProvisioning but None, so that a missing or mis-prefixed table is reported once, by name, instead of as the first failing operation. A delegate that owns tables of its own checks those too.

Tables, and the columns 4.x added to the tables 3.x already had: a schema that took none of the 4.0 migration is missing one table and six columns, and a table-level check alone would pass a database that then fails every acquisition for ever. What it does not check is the shape of a column — a type or a width that a hand-built table got wrong is still found by the statement that binds it.

Exceptions

JobPersistenceException: An object could not be queried.

Table of Contents

Interface IDriverDelegate

Remarks

Properties

FiltersAcquisitionExecutionGroups

Property Value

Remarks

FiltersAcquisitionJobTypeExclusions

Property Value

Remarks

SupportsFireOnAcquire

Property Value

Remarks

Methods

ApplyTriggerFired(ConnectionAndTransactionHolder, TriggerFiredUpdate, CancellationToken)

Parameters

Returns

Remarks

ApplyTriggersFired(ConnectionAndTransactionHolder, IReadOnlyList<TriggerFiredUpdate>, CancellationToken)

Parameters

Returns

Remarks

CalendarExists(ConnectionAndTransactionHolder, string, CancellationToken)

Parameters

Returns

CalendarIsReferenced(ConnectionAndTransactionHolder, string, CancellationToken)

Parameters

Returns

ClearData(ConnectionAndTransactionHolder, CancellationToken)

Parameters

Returns

ClearMisfireOriginalFireTime(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Parameters

Returns

Remarks

ClearTriggerPauses(ConnectionAndTransactionHolder, IReadOnlyCollection<TriggerKey>, CancellationToken)

Parameters

Returns

Remarks

ClearTriggerRetryAttempt(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Parameters

Returns

Remarks

CountMisfiredTriggersInState(ConnectionAndTransactionHolder, StoredTriggerState, DateTimeOffset, CancellationToken)

Parameters

Returns

CountTriggersForJob(ConnectionAndTransactionHolder, JobKey, CancellationToken)

Parameters

Returns

CreateSchema(ConnectionAndTransactionHolder, CancellationToken)

Parameters

Returns

Remarks

Exceptions

DeleteBlobTrigger(ConnectionAndTransactionHolder, TriggerKey, CancellationToken)

Parameters

Returns

DeleteCalendar(ConnectionAndTransactionHolder, string, CancellationToken)

Parameters

Returns

DeleteFiredTrigger(ConnectionAndTransactionHolder, string, CancellationToken)

Parameters

Returns

DeleteFiredTriggers(ConnectionAndTransactionHolder, FiredTriggerQuery, CancellationToken)

Parameters

Returns

DeleteFiredTriggers(ConnectionAndTransactionHolder, IReadOnlyCollection<string>, CancellationToken)

Parameters

Returns

Remarks

DeleteJobDetail(ConnectionAndTransactionHolder, JobKey, CancellationToken)

Parameters

Returns

DeletePausedJobGroup(ConnectionAndTransactionHolder, GroupMatcher<JobKey>, CancellationToken)

Parameters

Returns

DeletePausedTriggerGroup(ConnectionAndTransactionHolder, GroupMatcher<TriggerKey>, CancellationToken)

Parameters

Returns

DeleteSchedulerState(ConnectionAndTransactionHolder, string, CancellationToken)