• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 
24 typedef struct alarm_t alarm_t;
25 typedef struct fixed_queue_t fixed_queue_t;
26 typedef struct thread_t thread_t;
27 
28 // Prototype for the alarm callback function.
29 typedef void (*alarm_callback_t)(void* data);
30 
31 // Creates a new one-time off alarm object with user-assigned
32 // |name|. |name| may not be NULL, and a copy of the string will
33 // be stored internally. The value of |name| has no semantic
34 // meaning. It is recommended that the name is unique (for
35 // better debuggability), but that is not enforced. The returned
36 // object must be freed by calling |alarm_free|. Returns NULL on
37 // failure.
38 alarm_t* alarm_new(const char* name);
39 
40 // Creates a new periodic alarm object with user-assigned |name|.
41 // |name| may not be NULL, and a copy of the string will be
42 // stored internally. The value of |name| has no semantic
43 // meaning. It is recommended that the name is unique (for better
44 // debuggability), but that is not enforced. The returned object
45 // must be freed by calling |alarm_free|. Returns NULL on
46 // failure.
47 alarm_t* alarm_new_periodic(const char* name);
48 
49 // Frees an |alarm| object created by |alarm_new| or
50 // |alarm_new_periodic|. |alarm| may be NULL. If the alarm is
51 // pending, it will be cancelled first. It is not safe to call
52 // |alarm_free| from inside the callback of |alarm|.
53 void alarm_free(alarm_t* alarm);
54 
55 // Sets an |alarm| to execute a callback in the future. The |cb|
56 // callback is called after the given |interval_ms|, where
57 // |interval_ms| is the number of milliseconds relative to the
58 // current time. If |alarm| was created with
59 // |alarm_new_periodic|, the alarm is scheduled to fire
60 // periodically every |interval_ms|, otherwise it is a one time
61 // only alarm. A periodic alarm repeats every |interval_ms| until
62 // it is cancelled or freed. When the alarm fires, the |cb|
63 // callback is called with the context argument |data|:
64 //
65 //      void cb(void *data) {...}
66 //
67 // The |data| argument may be NULL, but the |cb| callback may not
68 // be NULL. All |cb| callbacks scheduled through this call are
69 // called within a single (internally created) thread. That
70 // thread is not same as the caller’s thread. If two (or more)
71 // alarms are set back-to-back with the same |interval_ms|, the
72 // callbacks will be called in the order the alarms are set.
73 void alarm_set(alarm_t* alarm, uint64_t interval_ms, alarm_callback_t cb,
74                void* data);
75 
76 // Sets an |alarm| to execute a callback in the main message loop. This function
77 // is same as |alarm_set| except that the |cb| callback is scheduled for
78 // execution in the context of the main message loop.
79 void alarm_set_on_mloop(alarm_t* alarm, uint64_t interval_ms,
80                         alarm_callback_t cb, void* data);
81 
82 // This function cancels the |alarm| if it was previously set.
83 // When this call returns, the caller has a guarantee that the
84 // callback is not in progress and will not be called if it
85 // hasn't already been called. This function is idempotent.
86 // |alarm| may not be NULL.
87 void alarm_cancel(alarm_t* alarm);
88 
89 // Tests whether the |alarm| is scheduled.
90 // Return true if the |alarm| is scheduled or NULL, otherwise false.
91 bool alarm_is_scheduled(const alarm_t* alarm);
92 
93 // Figure out how much time until next expiration.
94 // Returns 0 if not armed. |alarm| may not be NULL.
95 // TODO: Remove this function once PM timers can be re-factored
96 uint64_t alarm_get_remaining_ms(const alarm_t* alarm);
97 
98 // Cleanup the alarm internal state.
99 // This function should be called by the OSI module cleanup during
100 // graceful shutdown.
101 void alarm_cleanup(void);
102 
103 // Dump alarm-related statistics and debug info to the |fd| file descriptor.
104 // The information is in user-readable text format. The |fd| must be valid.
105 void alarm_debug_dump(int fd);
106