1 /*
2  * Copyright (C) 2016 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef CHRE_PLATFORM_SYSTEM_TIMER_H_
18 #define CHRE_PLATFORM_SYSTEM_TIMER_H_
19 
20 #include <cstdint>
21 
22 #include "chre/target_platform/system_timer_base.h"
23 #include "chre/util/non_copyable.h"
24 #include "chre/util/time.h"
25 
26 namespace chre {
27 
28 /**
29  * The function signature of a timer callback.
30  *
31  * @param The data pointer here is passed in by the entity that requested the
32  *        timer and is used to provided a context in the callback.
33  */
34 typedef void (SystemTimerCallback)(void *data);
35 
36 /**
37  * Abstracts a system timer from the underlying platform, which will invoke the
38  * supplied callback after at least the given amount of time has passed. The
39  * calling context for the callback is undefined, and may be inside an
40  * interrupt, or in a different thread, etc. Therefore, the callback is
41  * responsible for ensuring that it handles this potential concurrency
42  * appropriately.
43  */
44 class SystemTimer : public SystemTimerBase,
45                     public NonCopyable {
46  public:
47   /**
48    * Allows the platform to construct a timer.
49    */
50   SystemTimer();
51 
52   /**
53    * Cleans up a timer when it goes out of scope.
54    */
55   ~SystemTimer();
56 
57   /**
58    * Initializes the timer. This must be called before other methods in this
59    * class are called.
60    *
61    * @return true on successful, false on failure
62    */
63   bool init();
64 
65   /**
66    * Sets the timer to expire after the given delay. If the timer was already
67    * running, its expiry time is updated to this value.
68    *
69    * Note that it is possible for the timer to fire before this function
70    * returns.
71    *
72    * @param callback The callback to invoke when the timer has elapsed.
73    * @param data The data to pass to the callback when it is invoked.
74    * @param delay The minimum delay until the first firing of the timer.
75    * @return true on success, false on failure
76    */
77   bool set(SystemTimerCallback *callback, void *data, Nanoseconds delay);
78 
79   /**
80    * Disarms the timer. If it was armed and is not currently in the process of
81    * firing, this prevents the callback from being invoked until the timer is
82    * restarted by a subsequent call to set().
83    *
84    * @return Whether or not the timer was cancelled successfully.
85    */
86   bool cancel();
87 
88   /**
89    * Determines whether or not the timer is currently timing.
90    *
91    * @return true if the timer is currently active and false if it is idle.
92    */
93   bool isActive();
94 
95  private:
96   // We make SystemTimerBase a friend to allow the base platform class to
97   // access the members of this class.
98   friend class SystemTimerBase;
99 
100   //! The callback to invoke when the timer has elapsed.
101   SystemTimerCallback *mCallback;
102 
103   //! The data to pass to the callback when invoked.
104   void *mData;
105 };
106 
107 }  // namespace chre
108 
109 #endif  // CHRE_PLATFORM_SYSTEM_TIMER_H_
110