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 = nullptr; 103 104 //! The data to pass to the callback when invoked. 105 void *mData = nullptr; 106 }; 107 108 } // namespace chre 109 110 #endif // CHRE_PLATFORM_SYSTEM_TIMER_H_ 111