keepalive/flextimer/doc_pub/flextimer_for_clients_doxygen/flextimer_for_clients.dox
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/keepalive/flextimer/doc_pub/flextimer_for_clients_doxygen/flextimer_for_clients.dox Mon May 24 20:51:35 2010 +0300
@@ -0,0 +1,186 @@
+/*
+ * 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.
+
+*/