1 /****************************************************************************** 2 * 3 * Copyright 2014 Google, Inc. 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at: 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 ******************************************************************************/ 18 19 #pragma once 20 21 #include <stdbool.h> 22 #include <stdint.h> 23 #include "osi/include/time.h" 24 25 typedef struct alarm_t alarm_t; 26 typedef struct fixed_queue_t fixed_queue_t; 27 typedef struct thread_t thread_t; 28 29 // Prototype for the alarm callback function. 30 typedef void (*alarm_callback_t)(void* data); 31 32 // Creates a new one-time off alarm object with user-assigned 33 // |name|. |name| may not be NULL, and a copy of the string will 34 // be stored internally. The value of |name| has no semantic 35 // meaning. It is recommended that the name is unique (for 36 // better debuggability), but that is not enforced. The returned 37 // object must be freed by calling |alarm_free|. Returns NULL on 38 // failure. 39 alarm_t* alarm_new(const char* name); 40 41 // Creates a new periodic alarm object with user-assigned |name|. 42 // |name| may not be NULL, and a copy of the string will be 43 // stored internally. The value of |name| has no semantic 44 // meaning. It is recommended that the name is unique (for better 45 // debuggability), but that is not enforced. The returned object 46 // must be freed by calling |alarm_free|. Returns NULL on 47 // failure. 48 alarm_t* alarm_new_periodic(const char* name); 49 50 // Frees an |alarm| object created by |alarm_new| or 51 // |alarm_new_periodic|. |alarm| may be NULL. If the alarm is 52 // pending, it will be cancelled first. It is not safe to call 53 // |alarm_free| from inside the callback of |alarm|. 54 void alarm_free(alarm_t* alarm); 55 56 // Sets an |alarm| to execute a callback in the future. The |cb| 57 // callback is called after the given |interval_ms|, where 58 // |interval_ms| is the number of milliseconds relative to the 59 // current time. If |alarm| was created with 60 // |alarm_new_periodic|, the alarm is scheduled to fire 61 // periodically every |interval_ms|, otherwise it is a one time 62 // only alarm. A periodic alarm repeats every |interval_ms| until 63 // it is cancelled or freed. When the alarm fires, the |cb| 64 // callback is called with the context argument |data|: 65 // 66 // void cb(void *data) {...} 67 // 68 // The |data| argument may be NULL, but the |cb| callback may not 69 // be NULL. All |cb| callbacks scheduled through this call are 70 // called within a single (internally created) thread. That 71 // thread is not same as the callers thread. If two (or more) 72 // alarms are set back-to-back with the same |interval_ms|, the 73 // callbacks will be called in the order the alarms are set. 74 void alarm_set(alarm_t* alarm, period_ms_t interval_ms, alarm_callback_t cb, 75 void* data); 76 77 // Sets an |alarm| to execute a callback in the main message loop. This function 78 // is same as |alarm_set| except that the |cb| callback is scheduled for 79 // execution in the context of the main message loop. 80 void alarm_set_on_mloop(alarm_t* alarm, period_ms_t interval_ms, 81 alarm_callback_t cb, void* data); 82 83 // This function cancels the |alarm| if it was previously set. 84 // When this call returns, the caller has a guarantee that the 85 // callback is not in progress and will not be called if it 86 // hasn't already been called. This function is idempotent. 87 // |alarm| may not be NULL. 88 void alarm_cancel(alarm_t* alarm); 89 90 // Tests whether the |alarm| is scheduled. 91 // Return true if the |alarm| is scheduled or NULL, otherwise false. 92 bool alarm_is_scheduled(const alarm_t* alarm); 93 94 // Figure out how much time until next expiration. 95 // Returns 0 if not armed. |alarm| may not be NULL. 96 // TODO: Remove this function once PM timers can be re-factored 97 period_ms_t alarm_get_remaining_ms(const alarm_t* alarm); 98 99 // Cleanup the alarm internal state. 100 // This function should be called by the OSI module cleanup during 101 // graceful shutdown. 102 void alarm_cleanup(void); 103 104 // Dump alarm-related statistics and debug info to the |fd| file descriptor. 105 // The information is in user-readable text format. The |fd| must be valid. 106 void alarm_debug_dump(int fd); 107
