Use the TimerWheel class to provide timers in a Unified Communications Managed API application. Most SIP-based applications for real-time communications and collaboration need to manage many timers. The TimerWheel class provides a single system timer, giving authors an efficient solution using the smallest possible amount of system resources.

Understand the Timer Wheel

The easiest way to understand the timer wheel is to imagine a wheel divided into segments. Each segment is a sector holding individual timer items. When a timer item is created it is added to a sector. When the timer item stops or expires, it is removed from the timer wheel.

The sector span indicates the interval before processing begins on the next sector. If processing on the first sector is not finished, the next sector is processed in another thread in parallel while processing continues on the first sector. While it is ideal to process all items in a sector within the sector span, it is not required. Within each sector, the timer wheel processes each item, looking for expired items. The expiry callback method associated with each expired item is called in a worker thread. When the timer for a sector expires, the timer wheel begins processing the next sector.

Setting TimerWheel Values

When choosing the number of sectors and sector span it is ideal but not required that the timer wheel identifies all the expired items in a sector within the sector's allotted span. The time needed to invoke the expiry callback methods is not included in this time, since that processing occurs on a worker thread. Select the number of sectors and sector span so that the timers are nicely spread across all sectors.

Using the Timer Wheel

Use the properties and methods of the TimerWheel class to manage timer items.

Creating a Timer Wheel

A typical application might use two timer wheels. One timer wheel can be used for micro timers—to manage timer items smaller than 10 minutes. A second timer wheel can be used to manage items with spans larger than 10 minutes. See the following example code.

Copy Code 
using Microsoft.Rtc.Signaling

//Uses default values for 
//number of sectors (512) 
//and sector span (1 second)
TimerWheel microTimerWheel = new TimerWheel();

//Uses 512 sectors and 1 minute for sector span
TimerWheel macroTimer = new TimerWheel(512, new TimeSpan(0,1,0));

Disposing of the Timer Wheel

When an application no longer needs a timer wheel it can dispose of it using the Dispose method. Once Dispose is used, the timer wheel is no longer functional, and timer items cease to expire. See the following example statement.

Copy Code 
microTimerWheel.Dispose();

Creating and Starting a Timer Item

See the following code for an example of how to create an instance of the TimerItem class.

Copy Code 
using Microsoft.Rtc.Signaling

void SetupTimerItem
{ 
  //Creates a 30 second timer and 
  //associates it with a timer wheel.
  TimerItem timerItem = new TimerItem(microTimerWheel, new TimeSpan(0, 0, 30));
  timerItem.Start();
  timerItem.Expired += MyTimerExpired; 
}

Resetting a Timer

Before a timer item expires, it is possible to use the Reset method to reset it using the same or a different time span. This has the effect of removing the timer item, and then adding it back in with the new values.

The Reset method can also be used to start the item again when it is expired. For example, at a periodic interval the Expired event can check to see whether some event of interest has occurred. If not, Expired can use the Reset method to start the timer item again. When the event occurs, the item is not restarted and so it is done.

Copy Code 
//Reset, using the same time span.
timerItem.Reset();
			
//Or, reset, making it a 2 minute timer.
timerItem.Reset(new TimeSpan(0,2,0));

Stopping a Timer

Use the Stop method if a timer item is no longer needed.

Copy Code 
timerItem.Stop();

See Also