Class PolledTimer

Implements a timer suitable for use in scenarios that need to poll periodically to see if an action needs to be performed.

Inheritance

object

PolledTimer

Namespace: Neon.Time

Assembly: Neon.Common.dll

Syntax

public sealed class PolledTimer

Remarks

A common programming pattern is to have background threads check periodically for something to do; like resend a message, clean up idle connections, or signal a timeout. The PolledTimer class provides an easy way to encapsulate the interval and next scheduled time at which these events should happen.

Use PolledTimer(TimeSpan) or PolledTimer(TimeSpan, bool) to create a timer, specifying the firing interval. The second constructor also specifies the autoReset parameter which indicates that the timer should automatically reschedule itself after being fired. Note that one of these constructors must be used. PolledTimer structures created with the default constructor will thow a InvalidOperationException when an attempt is made to use it.

While being constructed, a polled timer calculates its next scheduled firing time (SYS). Note that this value generated by SysTime not a normal system time. The scheduled firing time is available as the FireTime property. Ther current interval is available as the Interval property.

Use HasFired to determine if the timer has been fired. This will return true if this is the case. If autoReset=true was passed to the constructor, then HasFired will automatically reset the timer by scheduling the next firing time. If autoReset=false, then the timer will remain in the fired state until Reset() is called.

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

The Reset(), ResetImmediate(), and ResetRandom() methods are used recalcuclate the firing time. The first variation schedules this time as the current time plus the timer interval. The second variation schedules the timer for immediate firing (typically used right after the timer is constructed in situations where the application wishes the timer to fire right away the first time it is polled), and the third method resets the timer to fire at a random interval between zero and the timer's interval (useful when trying to avoid having multiple timers fire at the same time).

The Disable() method prevents the timer from firing until Reset() is called or Interval is set. This is useful for preventing a timer from firing when an operation initiated from a previous firing is still executing (perhaps on another thread).

Constructors

PolledTimer()

The default constructor creates a timer that is initially disabled.

Declaration

public PolledTimer()

PolledTimer(bool)

The default constructor creates a timer that is initially disabled with optional auto reset capabilities.

Declaration

public PolledTimer(bool autoReset)

Parameters

Type	Name	Description
bool	autoReset	Indicates whether the timer should automatically reset itself after firing.

PolledTimer(TimeSpan)

Constructs a timer, initializing it to fire at the specified interval.

Declaration

public PolledTimer(TimeSpan interval)

Parameters

Type	Name	Description
TimeSpan	interval	The timer interval.

Exceptions

Type	Condition
ArgumentException	Thrown if the interval passed is not positive.

PolledTimer(TimeSpan, bool)

Constructs a timer with the option of auto resetting itself.

Declaration

public PolledTimer(TimeSpan interval, bool autoReset)

Parameters

Type	Name	Description
TimeSpan	interval	The timer interval.
bool	autoReset	Pass true to create an auto reset timer.

Exceptions

Type	Condition
ArgumentException	Thrown if the interval passed is not positive.

Properties

FireTime

Returns the scheduled firing time (SYS).

Declaration

public DateTime FireTime { get; }

Property Value

Type	Description
DateTime

Exceptions

Type	Condition
InvalidOperationException	Thrown if the timer was created using the default constructor.

HasFired

Determines whether the timer has fired.

Declaration

public bool HasFired { get; }

Property Value

Type	Description
bool	true if the timer has fired.

Remarks

For auto reset timers, this property will reschedule the next firing time if the timer has fired.

Exceptions

Type	Condition
InvalidOperationException	Thrown if the timer was created using the default constructor.

Interval

The current timer interval.

Declaration

public TimeSpan Interval { get; set; }

Property Value

Type	Description
TimeSpan

Remarks

note

Setting a new interval causes the timer fire time to be rescheduled.

Exceptions

Type	Condition
InvalidOperationException	Thrown if the timer was created using the default constructor.
ArgumentException	Thrown if the interval passed is not positive.

Methods

Disable()

Prevents the timer from firing until one of the Reset() methods are called or Interval is assigned a new value.

Declaration

public void Disable()

FireNow()

Sets the timer into the fired state.

Declaration

public void FireNow()

Reset()

Reschedules the timer to fire at the current time plus the timer interval.

Declaration

public void Reset()

Exceptions

Type	Condition
InvalidOperationException	Thrown if the timer was created using the default constructor.

Reset(TimeSpan)

Assigns a new interval to the timer and reschedules the timer to fire at the current time plus the new interval.

Declaration

public void Reset(TimeSpan interval)

Parameters

Type	Name	Description
TimeSpan	interval	The new timer interval.

Exceptions

Type	Condition
ArgumentException	Thrown if the interval passed is not positive.
InvalidOperationException	Thrown if the timer was created using the default constructor.

ResetAddRandom(TimeSpan)

Reschedules the timer to fire at a random time between the current scheduled firing time and a random interval between Zero and interval.

Declaration

public void ResetAddRandom(TimeSpan interval)

Parameters

Type	Name	Description
TimeSpan	interval	The interval to be randomized (can be positive or negative).

ResetImmediate()

Reschedules the timer to fire immediately.

Declaration

public void ResetImmediate()

Exceptions

Type	Condition
InvalidOperationException	Thrown if the timer was created using the default constructor.

ResetRandom()

Reschedules the timer to fire at a random time between now and the timer interval.

Declaration

public void ResetRandom()

Exceptions

Type	Condition
InvalidOperationException	Thrown if the timer was created using the default constructor.

ResetRandomTemporary(TimeSpan, TimeSpan)

Reschedules the timer to fire at the current time plus a randomly selected time between the two intervals passed. This call does not change the underlying timer interval. Subsequent timer resets will continue to use the original interval.

Declaration

public void ResetRandomTemporary(TimeSpan minInterval, TimeSpan maxInterval)

Parameters

Type	Name	Description
TimeSpan	minInterval	The minimum timer wait interval.
TimeSpan	maxInterval	The maximum timer wait interval.

ResetTemporary(TimeSpan)

Reschedules the timer to fire at the current time plus the specified interval but does not change the underlying timer interval. Subsequent timer resets will continue to use the original interval.

Declaration

public void ResetTemporary(TimeSpan interval)

Parameters

Type	Name	Description
TimeSpan	interval	The timer wait interval.

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.