1 /*

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

     3  * All rights reserved.

     4  * This component and the accompanying materials are made available

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

     6  * which accompanies this distribution, and is available

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

     8  *

     9  * Initial Contributors:

    10  * Nokia Corporation - Initial contribution

    11  *

    12  * Description:

    13  * This class contains definition of CFlexTimerContainer.

    14  *

    15  */

    16 

    17 // Protection against nested includes

    18 #ifndef FLEXTIMERCONTAINER_H

    19 #define FLEXTIMERCONTAINER_H

    20 

    21 // System includes

    22 #include <e32base.h>

    23 

    24 // Forward declarations

    25 class MFlexTimerServiceCB;

    26 class CFlexTimerItem;

    27 

    28 // Class declaration

    29 /**

    30  *  Timer container that contains list of CFlexTimerItems, means to add and

    31  *  delete them and implementation of algorithms that select which timers

    32  *   should be expired.

    33  */

    34 class CFlexTimerContainer : public CBase

    35     {

    36 public:

    37     /** Supported timer algorithms.*/

    38     enum TFlexTimerAlgorithm

    39         {

    40         /** Simple algorithm timeouts all timers that have open timeout

    41          * window when one timer expires.

    42          */

    43         EFlexTimerAlgorithmSimple = 1,

    44         /** Latest possible algorithm tries to delay expiration of timer

    45          * as long as possible.

    46          */

    47         EFlexTimerAlgorithmLatestPossible

    48         };

    49 

    50     /**

    51      * Constructs new CFlexTimerContainer.

    52      */

    53     static CFlexTimerContainer* NewL();

    54 

    55     /**

    56      * Destructs timercontainer and all timers in the internal lists.

    57      */

    58     virtual ~CFlexTimerContainer();

    59 

    60 public:

    61     /**

    62      * Makes new timer item and adds it to timerlist.

    63      *

    64      * @param aWinStartInterval Time interval from present to left side of the

    65      *  timer launch window

    66      * @param aWinEndInterval Time interval from present to right side of the

    67      *  timer launch window

    68      * @param aCancelAtSystemTimeChange Whether system time change should

    69      *  trigger abort

    70      * @param aFlexTimerServiceCB Call back interface. Used to inform about

    71      *  timeout, abort etc.

    72      */

    73     void AddTimerL(

    74         const TTimeIntervalMicroSeconds& aWinStartInterval,

    75         const TTimeIntervalMicroSeconds& aWinEndInterval,

    76         TBool aCancelAtSystemTimeChange,

    77         const MFlexTimerServiceCB* aFlexTimerServiceCB );

    78 

    79     /**

    80      * Finds correct timer according to aFlexTimerServiceCB and removes it

    81      * from list and finally 

    82      * deletes the corresponding CFlexTimerItem.

    83      * @param aFlexTimerServiceCB Call back interface aka. session that

    84      * handles timer.

    85      * @return KErrNone or some system wide error code.

    86      */

    87     TInt RemoveTimer( const MFlexTimerServiceCB* aFlexTimerServiceCB );

    88 

    89     /**

    90      * Finds earliest moment that at least one timer must expire and after

    91      * this function returns aNextTimeoutDelay contains number of microseconds

    92      * from now to that moment.

    93      *

    94      * @param after return aNextTimeoutDelay contains time in microseconds

    95      * from now till next timer expiry. If aNextTimeoutDelay is zero, it means

    96      * that expiry time has already passed or is due right now

    97      * @return Active timers indication

    98      * - ETrue if there is at least one timer in queue

    99      * - EFalse if there are no timers

   100      */

   101     TBool GetNextTimeout( TTimeIntervalMicroSeconds& aNextTimeoutDelay );

   102 

   103     /**

   104      * Fires all timers that can be fired according to algorithm that is

   105      * supplied as parameter.

   106      *

   107      * @param aAlgorithmToBeUsed Algorithm that is used to fire timers.

   108      * - EFlexTimerAlgorithmSimple

   109      * - EFlexTimerAlgorithmLatestPossible

   110      */

   111     void FireTimers( TFlexTimerAlgorithm aAlgorithmToBeUsed );

   112 

   113     /**

   114      * Aborts and removes all timers that are marked with

   115      * aCancelAtSystemTimeChange = ETrue during adding timer.

   116      *

   117      * @param aReason Timers will be aborted with this reason code. Can be

   118      * e.g. KErrAbort

   119      */

   120     void AbortTimersDueToTimeChange( TInt aReason );

   121 

   122 private:

   123     /**

   124      * Private constructor.

   125      */

   126     CFlexTimerContainer();

   127 

   128     /**

   129      * Excecutes simple algorithm.

   130      * 

   131      * Moves timers (that can be fired right now) from iTimerList to

   132      * candidateList.

   133      * 

   134      * @param aCandidateList After this function returns, this list contains

   135      * all timers that can be fire right now.

   136      * @param aCurrentTime Current safe UTC time.

   137      */

   138     void SimpleAlgorithm( TSglQue<CFlexTimerItem>& aCandidateList,

   139         TTime& aCurrentTime );

   140 

   141     /**

   142      * Excecutes latest possible algorithm.

   143      * 

   144      * Moves timers (that don't necessarily be fired right now) from

   145      * candidateList to iTimerList.

   146      * 

   147      * @param aCandidateList After this function returns, this list contains

   148      * all timers that can be fire right now.

   149      */

   150     void LatestPossibleAlgorithm( TSglQue<CFlexTimerItem>& aCandidateList );

   151 

   152     /**

   153      * Fires all timers in aCandidateList. Calls Timeout() to all timers and

   154      * deletes timer items.

   155      * 

   156      * @param aCandidateList Timers that are fired.

   157      */

   158     void ExpireTimers( TSglQue<CFlexTimerItem>& aCandidateList );

   159 

   160     /**

   161      * Gets current absolute time. The time in FlexTimer engine time base, not

   162      * system time base. This time base is begins from the first call to

   163      *  GetCurrentTime and it is base on system ticks.

   164      * 

   165      * @param aCurrentAbsoluteTime After this function returns this contains

   166      * current flextimer timebase time.

   167      */

   168     void GetCurrentTime( TTime& aCurrentAbsoluteTime );

   169 

   170     /**

   171      * Converts microseconds interval to tick based reference time used by

   172      * FlexTimer engine (also in microseconds). All FlexTimer timeout element

   173      * time handling is based on this tick based absolute time.

   174      *

   175      * @param aInterval Interval to be converted.

   176      */

   177     inline TInt64 IntervalToAbsoluteTime(

   178         const TTimeIntervalMicroSeconds& aInterval );

   179 

   180     /**

   181      * Converts ticks to microseconds.

   182      *

   183      * @param aTicks. Ticks to be converted to microseconds

   184      */

   185     inline TInt64 TicksToAbsoluteTime( TUint32 aTicks );

   186 

   187 private:

   188     // Data

   189     /**

   190      * Linked list and iterator for all timer objects.

   191      */

   192     TSglQue<CFlexTimerItem> iTimerList;

   193     

   194     /**

   195      * Length of system tick in milliseconds. The value is read once

   196      * to member variable during construction of FlexTimerContainer so that

   197      * it does not need be read every time the absolute time is calculated.

   198      */

   199     TInt iTickPeriod;

   200      

   201     /**

   202      * Number of tics during the last time they were read. This is used to

   203      * detect possible tick counter overflow and to calculate time passed

   204      * since the last read.

   205      */

   206     TUint32 iLastTicks;

   207     

   208     /**

   209      * Current FlexTimer engine time. This is system tick based time and

   210      * it is updated every time someone request for it.

   211      */

   212     TInt64 iCurrentAbsoluteTime;

   213     };

   214 

   215 #include "flextimercontainer.inl"

   216 

   217 #endif  //FLEXTIMERCONTAINER_H