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, public NonCopyable {
45  public:
46   /**
47    * Allows the platform to construct a timer.
48    */
49   SystemTimer();
50 
51   /**
52    * Cleans up a timer when it goes out of scope.
53    */
54   ~SystemTimer();
55 
56   /**
57    * Initializes the timer. This must be called before other methods in this
58    * class are called.
59    *
60    * @return true on successful, false on failure
61    */
62   bool init();
63 
64   /**
65    * Sets the timer to expire after the given delay. If the timer was already
66    * running, its expiry time is updated to this value.
67    *
68    * Note that it is possible for the timer to fire before this function
69    * returns.
70    *
71    * @param callback Non-null pointer to a callback to invoke when the timer has
72    *     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 true if the timer was cancelled successfully and false if the timer
85    *     was already canceled or something failed.
86    */
87   bool cancel();
88 
89   /**
90    * Determines whether or not the timer is currently timing.
91    *
92    * @return true if the timer is currently active and false if it is idle.
93    */
94   bool isActive();
95 
96  private:
97   // We make SystemTimerBase a friend to allow the base platform class to
98   // access the members of this class.
99   friend class SystemTimerBase;
100 
101   //! The callback to invoke when the timer has elapsed.
102   SystemTimerCallback *mCallback;
103 
104   //! The data to pass to the callback when invoked.
105   void *mData;
106 };
107 
108 }  // namespace chre
109 
110 #endif  // CHRE_PLATFORM_SYSTEM_TIMER_H_
111