/*

 * Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies).

 * All rights reserved.

 * This component and the accompanying materials are made available

 * under the terms of "Eclipse Public License v1.0"

 * which accompanies this distribution, and is available

 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

 *

 * Initial Contributors:

 * Nokia Corporation - initial contribution.

 *

 * Contributors:

 *

 * Description:

 *      Flexible timer documentation's main page

 *

 */

/*

 * %version: 1 %

 */

/**

@mainpage

@section mainGeneral General

Flexible timers are timers for synchronizing network access. This is achieved

by providing a timer service that instead of generating timeout at exact moment

of time, generates timeout within given window of time. This allows several

timeouts to be aligned, and only one wakeup is needed instead of many. This

improves battery life. The improvement depends on the used bearer and its 

configuration.

Flexible timers are designed to provided similar API with existing Symbian

timers (RTimer, CTimer and CPeriodic), and (besides they extend the interfaces

by providing 64-bit interface for After(). I.e. using At() for longer than 35

minutes timers is not required.

@subsection mainYes When you should consider using Flexible timers 

- If your timer can handle several minutes variation in expiration times @b AND

- If your timer is used to trigger network connectivity @b AND

- If your timer is long enough (> 5 min)

@subsection mainNo Who should NOT use Flexible timers

- If you need accurate timing (in resolution of minutes) @b OR

- If your timer is too rapid, i.e. less than 5 minutes @b OR

- If you need timeout when phone is powered off @b OR

- If you need reboot-proof timeouts

@section mainTimerWindow Concept

The main idea of flexible timer concept is that timers can expire @a early.

The time how much earlier timer can expire, is called @b timer @b expiration 

@b window (or just window).

For example, a timer that is started to expire after 10 minutes timer that 

window is configured to 2 minutes can expire at any time between 8 to 10 

minutes. See the figure below.

\image html FlexTimerWindowConcept.png

There are two reasons when timer can expire:

-# The timer has reached the time it's set to be expired

-# Another timer is expiring within this timer's window

In picture below is shown two set of periodical timers; normal timers and

flexible timers. Each time a timer expires, it causes network access.

\image html FlexTimersExample.png

The picture also illustrates main differences between using normal and flexible

timers:

- number of network initializations decreases (12 vs. 6).

- timers are being "drifted" (e.g. interval of Timer 2 is actually 12 minutes)

@section mainArchitecture Architecture

In picture below is illustrated components of flexible timers.

\image html FlexTimerComponents.png

When a client uses flexible timers, the actual timer request is forwarded to

Flex Timer Server using Symbian's inter process communication (IPC). The

biggest difference to normal timers is that flexible timers actually are run in

different process than the client as the normal timers are run in local thread.

@section mainLimitations Limitations of flexible timers

@subsection mainTimerAccuracy Timer Accuracy

Although the timer can be set to expire in 1 microsecond accuracy, the actual

accuracy can vary from 1/64 second (one system tick) to 1 second. It depends

when the timer is set; timers are "rounded" to the next full second.

This implies that e.g. 1 microsecond periodic timer's period is 1 second; not

1 microsecond.

As the flexible timer's implementation relies on system ticks, it's possible 

that the timer expires 1/64 second (one system tick) too early.

I.e. the timer can expire from -1/64 second to +1 second when it is set.

@note If timer accuracy at this resolution is concern for you, you should not

use flexible timers at all. Use normal timers instead.

@subsection mainMinValue Minimum timer value

The minimum timer value is 0 microsecond. Only exception is CFlexPeriodic's

interval that can be 1 microseconds. 

@subsection mainMaxValue Maximum timer value

Maximum value for timer is 2 years (i.e. 730 days, 63072000 seconds).

@subsection mainMinWindow Minimum window value

The minimum value for timer window is zero microseconds.

@subsection mainMaxWindow Maximum window value

The maximum value for timer window is two years (i.e. 730 days, 63072000 

seconds). 

The default value for window is 20% of the timer's value (e.g. 10 minutes timer

has 2 minutes default window).

@subsection mainTimerDrifting Timer drifting

As the timer expiration can happen in timer expiration window, it usually

causes periodic timers to "drift".

For example:

@c CPeriodic is started at 8 o'clock with 30 minute interval.

It will then expire at 8.30, 9.00, ... 15.30, 16.00

If @c CFlexPeriodic is used as a timer it can possibly expire at

8.30, 9.00, 9.28, 9.55, ... 15.15, 15.42 etc. 

@subsection mainReboot Reboot-proof

Flexible timers are @b not reboot-proof. I.e. after reboot all timers has to

be set again.

@section mainHowTo How to start using flexible timers

The flexible timer API is designed to be as similar to normal Symbian timers

as possible. 

In the table below is described Symbian OS timer and its corresponding flexible

timer.

<table border=1 bordercolor="#84B0C7" cellspacing="0" align="center">

<tr><td><b>Symbian OS timer</b></td><td><b>Flexible timer</b></td></tr>

<tr><td><code>CPeriodic</code></td><td><code>CFlexPeriodic</code></td></tr>

<tr><td><code>CTimer</code></td><td><code>CFlexTimer</code></td></tr>

<tr><td><code>RTimer</code></td><td><code>RFlexTimer</code></td></tr>

</table>

Using of flexible timer is easy and fun. There are only three following steps;

-# Add following line to MMP-file

   @code 

   LIBRARY flextimer.lib 

   @endcode

-# Include flexible timer's header to your code files, e.g. for periodic timer

   @code

   #include <flexperiodic.h>

   @endcode

-# Convert the used Symbian OS timers to flexible timers, e.g.

   @code

   //Old: CPeriodic* myTimer = CPeriodic::NewL( CActive::EPriorityStandard );

   CFlexPeriodic* myTimer = CFlexPeriodic::NewL( CActive::EPriorityStandard );

   ...

   // By default the window is 20% of timer's values

   myTimer->Start( myDelay, myInterval, myCallback ); // No changes

   ...

   myTimer->Cancel(); // No changes

   delete myTimer; // No changes

   @endcode

More examples available in flexible timer's class documentation.

*/