Class Job

Namespace

VpnHood.Net.Toolkit.Jobs

Assembly

VpnHood.Net.Toolkit.dll

Represents a function that a JobRunner runs periodically: first after a due time, then at an interval from the end of each run, never two runs at once.

public class Job : IDisposable

Inheritance

object

Job

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

DisposableExtensions.TryDispose(IDisposable?, LogLevel)

Remarks

The runner checks its jobs at its own interval, so its polling and its busy run slots may delay a run: the shared fast runner checks every 2 seconds, the slow one, which takes the jobs with an interval of 10 seconds or more, every 10 seconds. The runner holds a job weakly: keep a reference while it should run, and dispose it to end it. A function's exception counts as a failure, a cancellation too unless the run's token is canceled, and the runner logs it as critical; an ObjectDisposedException makes the runner drop the job instead.

Constructors

Job(Func<CancellationToken, ValueTask>, string?)

Initializes a new instance of the Job class that starts at once, runs at its runner's next check, and then every DefaultInterval.

public Job(Func<CancellationToken, ValueTask> jobFunc, string? name = null)

Parameters

jobFunc Func<CancellationToken, ValueTask>

The function to run. Its token is canceled when the job is disposed.

name string

The job's name, for the log, or null.

Job(Func<CancellationToken, ValueTask>, TimeSpan, string?)

Initializes a new instance of the Job class that starts at once, runs at its runner's next check, and then every period.

public Job(Func<CancellationToken, ValueTask> jobFunc, TimeSpan period, string? name = null)

Parameters

jobFunc Func<CancellationToken, ValueTask>

The function to run. Its token is canceled when the job is disposed.

period TimeSpan

The time from the end of a run to the next one.

name string

The job's name, for the log, or null.

Job(Func<CancellationToken, ValueTask>, JobOptions, JobRunner?)

Initializes a new instance of the Job class, and adds it to a runner.

public Job(Func<CancellationToken, ValueTask> jobFunc, JobOptions options, JobRunner? jobRunner = null)

Parameters

jobFunc Func<CancellationToken, ValueTask>

The function to run. Its token is canceled when the job is disposed, or when a RunNow(CancellationToken) caller cancels.

options JobOptions

The job's options.

jobRunner JobRunner

The runner, or null for the shared one that fits the interval: SlowInstance from 10 seconds up, else FastInstance.

Properties

FailedCount

Gets the number of runs that failed; an OperationCanceledException is not counted when the run's token is canceled.

public long FailedCount { get; }

Property Value

long

Interval

Gets or sets the time from the end of a run to the next one.

public TimeSpan Interval { get; set; }

Property Value

TimeSpan

IsReadyToRun

Gets a value indicating whether the job is started, not running, and due.

public bool IsReadyToRun { get; }

Property Value

bool

IsStarted

Gets a value indicating whether the job is started.

public bool IsStarted { get; }

Property Value

bool

LastExecutedTime

Gets when the last run ended, in UTC, or null before the first.

public DateTime? LastExecutedTime { get; }

Property Value

DateTime?

Name

Gets the job's name, for the log.

public string Name { get; init; }

Property Value

string

StartedTime

Gets or sets when the job was started, in UTC, which its due time counts from, or null while it is stopped.

public DateTime? StartedTime { get; set; }

Property Value

DateTime?

SucceededCount

Gets the number of runs that succeeded.

public long SucceededCount { get; }

Property Value

long

Methods

Dispose()

Cancels a run under way, stops the job and removes it from its runner. Calling it again does nothing.

public void Dispose()

RunNow()

Runs the job now, started or not, once a run under way ends. A cancellation by the job's disposal while the function runs ends it quietly.

public Task RunNow()

Returns

Task

A task that represents the asynchronous operation.

Exceptions

ObjectDisposedException

The job is disposed.

OperationCanceledException

The run was canceled before the function started, as while it waited for a run under way to end.

Exception

The function's exception, which also counts as a failure.

RunNow(CancellationToken)

Runs the job now, started or not, once a run under way ends. A cancellation, by the token or by the job's disposal, while the function runs ends it quietly.

public Task RunNow(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

The token to monitor for cancellation requests.

Returns

Task

A task that represents the asynchronous operation.

Exceptions

ObjectDisposedException

The job is disposed.

OperationCanceledException

The run was canceled before the function started, as while it waited for a run under way to end.

Exception

The function's exception, which also counts as a failure.

Start()

Starts the job: its first run comes after the due time, counted from now; after an earlier run, after the interval from that run's end.

public void Start()

Exceptions

ObjectDisposedException

The job is disposed.

InvalidOperationException

The job is started already.

Stop()

Stops the job and resets its count of failures in a row; a run under way goes on.

public void Stop()

Exceptions

InvalidOperationException

The job is not started.