System.Threading.Timer Class

public sealed class Timer : MarshalByRefObject, IDisposable

Base Types

Object
  MarshalByRefObject
    Timer

This type implements IDisposable.

Assembly

mscorlib

Library

BCL

Summary

Provides a mechanism for executing methods at specified intervals.

Description

A TimerCallback delegate is used to specify the methods associated with a Timer . The methods do not execute in the thread that created the timer; they execute in a separate thread that is automatically allocated by the system. The timer delegate is specified when the timer is constructed, and cannot be changed.

When creating a timer, the application specifies an amount of time to wait before the first invocation of the delegate methods (due time), and an amount of time to wait between subsequent invocations (period). A timer invokes its methods once when its due time elapses, and invokes its methods once per period thereafter. These values can be changed, or the timer disabled using the System.Threading.Timer.Change(System.Int32,System.Int32) method.

When a timer is no longer needed, use the System.Threading.Timer.Dispose(System.Threading.WaitHandle) method to free the resources held by the timer.

Example

The following example demonstrates the features of the Timer class.

using System;
using System.Threading;

class TimerExampleState {
    public int counter = 0;
    public Timer tmr;
}

class App {
   public static void Main() {
    TimerExampleState s = new TimerExampleState();

    // Create the delegate that invokes methods for the timer.
    TimerCallback timerDelegate = new TimerCallback(CheckStatus);

    // Create a timer that waits one second, then invokes every second.
    Timer timer = new Timer(timerDelegate, s, 1000, 1000);
    
    // Keep a handle to the timer, so it can be disposed.
    s.tmr = timer;

    // The main thread does nothing until the timer is disposed.
    while (s.tmr != null)
        Thread.Sleep(0);
    Console.WriteLine("Timer example done.");
   }
   // The following method is called by the timer's delegate.

   static void CheckStatus(Object state) {
    TimerExampleState s = (TimerExampleState) state;
    s.counter++;
          Console.WriteLine("{0} Checking Status {1}.",DateTime.Now.TimeOfDay, s.counter);
        if (s.counter == 5) {
        // Shorten the period. Wait 10 seconds to restart the timer.
        (s.tmr).Change(10000,100);
        Console.WriteLine("changed...");
    }
        if (s.counter == 10) {
        Console.WriteLine("disposing of timer...");
        s.tmr.Dispose();
        s.tmr = null;
    }
   }
}

An example of some output is

10:51:40.5809015 Checking Status 1.

10:51:41.5823515 Checking Status 2.

10:51:42.5838015 Checking Status 3.

10:51:43.5852515 Checking Status 4.

10:51:44.5867015 Checking Status 5.

changed...

10:51:54.5911870 Checking Status 6.

10:51:54.6913320 Checking Status 7.

10:51:54.7914770 Checking Status 8.

10:51:54.8916220 Checking Status 9.

10:51:54.9917670 Checking Status 10.

disposing of timer...

Timer example done.

The exact timings returned by this example will vary.

See Also

System.Threading Namespace

Members

Timer Constructors

Timer(System.Threading.TimerCallback, System.Object, int, int) Constructor
Timer(System.Threading.TimerCallback, System.Object, System.TimeSpan, System.TimeSpan) Constructor

Timer Methods

Timer.Change(int, int) Method
Timer.Change(System.TimeSpan, System.TimeSpan) Method
Timer.Dispose() Method
Timer.Dispose(System.Threading.WaitHandle) Method
Timer.Finalize Method

callback

A TimerCallback delegate.

state

A Object containing application-specific information relevant to the methods invoked by callback, or null .

dueTime

A Int32 containing the amount of time to delay before callback invokes its methods, in milliseconds. Specify System.Threading.Timeout.Infinite to prevent the timer from starting. Specify zero to start the timer immediately.

period

A Int32 containing the time interval between invocations of the methods referenced by callback, in milliseconds. Specify System.Threading.Timeout.Infinite to disable periodic signaling.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	dueTime or period is negative and is not equal to System.Threading.Timeout.Infinite.
ArgumentNullException	callback is a null reference.

Description

callback invokes its methods once after dueTime elapses, and then invokes its methods each time the period time interval elapses.

If dueTime is zero, callback performs its first invocation immediately. If dueTime is System.Threading.Timeout.Infinite, callback does not invoke its methods; the timer is disabled, but can be re-enabled using the System.Threading.Timer.Change(System.Int32,System.Int32) method.

If period is zero or System.Threading.Timeout.Infinite and dueTime is not System.Threading.Timeout.Infinite, callback invokes its methods exactly once; the periodic behavior of the timer is disabled, but can be re-enabled using the System.Threading.Timer.Change(System.Int32,System.Int32) method.

See Also

System.Threading.Timer Class, System.Threading Namespace

callback

A TimerCallback delegate.

state

A Object containing application-specific information relevant to the methods invoked by callback, or null .

dueTime

A TimeSpan set to the amount of time to delay before callback invokes its methods. Set the value to System.Threading.Timeout.Infinite milliseconds to prevent the timer from starting. Specify zero to start the timer immediately.

period

A TimeSpan set to the time interval between invocations of the methods referenced by callback . Set the value to System.Threading.Timeout.Infinite milliseconds to disable periodic signaling.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	The number of milliseconds in the value of dueTime or period is negative and not equal to System.Threading.Timeout.Infinite, or is greater than System.Int32.MaxValue.
ArgumentNullException	callback is a null reference.

Description

The callback delegate invokes its methods once after dueTime elapses, and then invokes its methods each time the period time interval elapses.

If dueTime, in milliseconds, is zero, callback performs its first invocation immediately. If dueTime is System.Threading.Timeout.Infinite , no method invocation occurs. The timer is disabled, but can be re-enabled using the System.Threading.Timer.Change(System.Int32,System.Int32) method.

If period is zero or System.Threading.Timeout.Infinite milliseconds and dueTime is not System.Threading.Timeout.Infinite, callback invokes its methods exactly once. The periodic behavior of the timer is disabled, but can be re-enabled using the System.Threading.Timer.Change(System.Int32,System.Int32) method.

See Also

System.Threading.Timer Class, System.Threading Namespace

dueTime

A Int32 containing the amount of time to delay before the delegate specified at Timer construction time invokes its methods, in milliseconds. Specify System.Threading.Timeout.Infinite to prevent the timer from restarting. Specify zero to restart the timer immediately.

period

A Int32 containing the time interval between invocations of the methods referenced by the delegate specified at Timer construction time, in milliseconds. Specify System.Threading.Timeout.Infinite to disable periodic signaling.

Return Value

true if the current instance has not been disposed; otherwise, false .

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	dueTime or period is negative and is not equal to System.Threading.Timeout.Infinite .

Description

The delegate specified at Timer construction time invokes its methods once after dueTime elapses, and then invokes its methods each time the period time interval elapses.

If dueTime is zero, the delegate specified at Timer construction time performs its next invocation immediately. If dueTime is System.Threading.Timeout.Infinite , no method invocation occurs. The timer is disabled, but can be re-enabled by calling this method and specifying a non-negative value for dueTime .

If period is zero or System.Threading.Timeout.Infinite and dueTime is not System.Threading.Timeout.Infinite, the delegate specified at Timer construction time invokes its methods exactly once. The periodic behavior of the timer is disabled, but can be re-enabled by calling this method and specifying a positive value for period .

See Also

System.Threading.Timer Class, System.Threading Namespace

dueTime

A TimeSpan set to the amount of time to delay before the delegate specified at Timer construction time invokes its methods. Specify System.Threading.Timeout.Infinite milliseconds to prevent the timer from restarting. Specify zero to restart the timer immediately.

period

A TimeSpan set to the time interval between invocations of the methods referenced by the delegate specified at Timer construction time. Specify System.Threading.Timeout.Infinite milliseconds to disable periodic signaling.

Return Value

true if the current instance has not been disposed; otherwise, false .

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	dueTime or period is negative and is not equal to System.Threading.Timeout.Infinite .

Description

The delegate specified at Timer construction time invokes its methods once after dueTime elapses, and then invokes its methods each time the period time interval elapses.

If dueTime, in milliseconds, is zero, the delegate specified at Timer construction time performs its next invocation immediately. If dueTime is System.Threading.Timeout.Infinite milliseconds, no method invocation occurs. The timer is disabled, but can be re-enabled by calling this method and specifying a non-negative value for dueTime .

If period is zero or System.Threading.Timeout.Infinite milliseconds and dueTime is not System.Threading.Timeout.Infinite milliseconds, the delegate specified at Timer construction time invokes its methods exactly once. The periodic behavior of the timer is disabled, but can be re-enabled by calling this method and specifying a positive value for period .

See Also

System.Threading.Timer Class, System.Threading Namespace

[Note: This method is implemented to support the IDisposable interface.]

See Also

System.Threading.Timer Class, System.Threading Namespace

notifyObject

Specifies a WaitHandle to be signaled when the timer has been disposed of.

Return Value

true if the call succeeds; otherwise, false .

Exceptions

Exception Type	Condition
ArgumentNullException	notifyObject is null .

Description

When this method completes, the WaitHandle specified by notifyObject is signaled.

This method calls System.GC.SuppressFinalize(System.Object) to prevent the garbage collector from finalizing the current instance.

See Also

System.Threading.Timer Class, System.Threading Namespace

System.Threading.Timer Class, System.Threading Namespace