Class RecurringTimer

Used to manage tasks that need to be performed on a periodic basis.

Inheritance

object

RecurringTimer

Namespace: Neon.Time

Assembly: Neon.Common.dll

Syntax

public class RecurringTimer

Remarks

This timer is designed to be polled periodically from an application's background thread by calling the HasFired() or HasFired(DateTime) methods. These methods will return true if the action associated with the timer is to be performed.

This class works by watching for the transition between a call to HasFired() made at a time before the scheduled event and then a subsequent call made when the current time is at or after the scheduled event time. HasFired() will return true on the subsequent call if the time is right.

This behavior ensures that scheduled tasks will only be executed once for any recurring schedule, even if the application is restarted.

The HasFired() method uses the current UTC time to perform the time comparison. The HasFired(DateTime) will use the time passed (which may be local time, etc.) to do this.

note

This timer auto resets after HasFired() returns true. Note also that HasFired() must be called fairly frequently (on the order of a few minutes or less) to obtain reasonable accuracy.

Asynchronous applications may find it more convienent to call WaitAsync(TimeSpan) to wait for the timer to fire.

The Reset() and Reset(DateTime) methods may be used to explicitly reset the timer to fire at the next scheduled time. This may be useful for ensuring that short duration timers are properly reset after an operation that may take longer to complete than the timer interval.

Recurring timers are represented as strings with the format of the string depending on the type of timer. The table below describes these formats:

Disabled	Disabled timers never fire. Simply place the word Disabled at the beginning of the timer string.
Minute	Minute timers fire at the top of every minute. There is no offset. Minute timers are formatted as: Minute
QuarterHour	Quarter hour timers are fired four times an hour at the offset from the 15 minute time. Quarter hour timers formatted as: QuarterHour QuarterHour:MM QuarterHour:MM:SS
Hourly	Hourly timers are fired once per hour at the offset from the top of the hour. Hourly timers are formatted as: Hourly Hourly:MM Hourly:MM:SS
Daily	Daily timers are fired once per day at the specified time of day. Daily timers are formatted as: Daily Daily:HH:MM Daily:HH:MM:SS
Interval	Interval timers are fired on a regular interval that is not not tied to a specific period. Interval timers are formatted as: Interval:HH:MM:SS

Constructors

RecurringTimer()

Default constructor that creates a Disabled timer.

Declaration

public RecurringTimer()

RecurringTimer(RecurringTimerType, TimeSpan)

Constructs a recurring timer of the specified type and time offset from the beginning of the implied period.

Declaration

public RecurringTimer(RecurringTimerType type, TimeSpan timeOffset)

Parameters

Type	Name	Description
RecurringTimerType	type	Describes the timer type which implies the period.
TimeSpan	timeOffset	The time offset from the beginning of the implied timer period.

RecurringTimer(TimeOfDay)

Constructs a recurring timer that will fire once a day at the specified time offset.

Declaration

public RecurringTimer(TimeOfDay timeOfDay)

Parameters

Type	Name	Description
TimeOfDay	timeOfDay	The time of day offset.

RecurringTimer(string)

Constructs a timer by parsing a string value.

Declaration

public RecurringTimer(string value)

Parameters

Type	Name	Description
string	value	The string representation.

Exceptions

Type	Condition
ArgumentException	Thrown if the string passed is not valid.

Properties

Disabled

Returns a disabled timer.

Declaration

public static RecurringTimer Disabled { get; }

Property Value

Type	Description
RecurringTimer

TimeOffset

Returns the TimeSpan offet from the beginning of the period when the timer is scheduled to fire.

Declaration

public TimeSpan TimeOffset { get; }

Property Value

Type	Description
TimeSpan

Type

Returns the timer type.

Declaration

public RecurringTimerType Type { get; }

Property Value

Type	Description
RecurringTimerType

Methods

HasFired()

Determines whether the timer has fired by comparing the current UTC time with the scheduled event time.

Declaration

public bool HasFired()

Returns

Type	Description
bool

HasFired(DateTime)

Determines if the timer has fired by comparing the current time passed with the next scheduled firing time.

Declaration

public bool HasFired(DateTime nowUtc)

Parameters

Type	Name	Description
DateTime	nowUtc	The current time (UTC).

Returns

Type	Description
bool

Reset()

Resets the timer to fire at the next scheduled interval after the current UTC time.

Declaration

public void Reset()

Reset(DateTime)

Resets the timer to fire at the next scheduled interval after the time passed.

Declaration

public void Reset(DateTime now)

Parameters

Type	Name	Description
DateTime	now	The current time.

Set(DateTime)

Sets the firing time for the timer.

Declaration

public void Set(DateTime timeUtc = default)

Parameters

Type	Name	Description
DateTime	timeUtc	Optionally specifies the scheduled time (UTC) (defaults to now).

Remarks

This is useful in situations where it is necessary to special-case a specific firing time.

Start()

Starts the timer by computing the next firing time after the current time (UTC).

Declaration

public void Start()

Remarks

Applications may use this method to initalize the timer. This is useful in situations where some time may pass between the time the timer was constructed and the first time HasFired() has been called. In these situations, the timer will not fire for a scheduled event that occurs during this interval.

Start(DateTime)

Starts the timer by computing the next firing time after the time passed.

Declaration

public void Start(DateTime nowUtc)

Parameters

Type	Name	Description
DateTime	nowUtc	The current time (UTC).

Remarks

Applications may use this method to initalize the timer. This is useful in situations where some time may pass between the time the timer was constructed and the first time HasFired() has been called. In these situations, the timer will not fire for a scheduled event that occurs during this interval.

ToString()

Renders the timer into a string.

Declaration

public override string ToString()

Returns

Type	Description
string	The timer string.

Overrides

object.ToString()

TryParse(string, out RecurringTimer)

Attempts to parse RecurringTimer from a string.

Declaration

public static bool TryParse(string input, out RecurringTimer timer)

Parameters

Type	Name	Description
string	input	The input string.
RecurringTimer	timer	Returns as the parsed timer.

Returns

Type	Description
bool	true if the timer was parsed successfully.

WaitAsync(TimeSpan)

Waits aynchronously for the timer to fire.

Declaration

public Task WaitAsync(TimeSpan pollInterval = default)

Parameters

Type	Name	Description
TimeSpan	pollInterval	Optional timer polling interval (defaults to 15 seconds).

Returns

Type	Description
Task	The tracking Task.