GRPC Core  9.0.0
timer.h
Go to the documentation of this file.
1 /*
2  *
3  * Copyright 2015 gRPC authors.
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 #ifndef GRPC_CORE_LIB_IOMGR_TIMER_H
20 #define GRPC_CORE_LIB_IOMGR_TIMER_H
21 
23 
25 
26 #include <grpc/support/time.h>
29 
30 typedef struct grpc_timer {
32  // Uninitialized if not using heap, or INVALID_HEAP_INDEX if not in heap.
33  uint32_t heap_index;
34  bool pending;
35  struct grpc_timer* next;
36  struct grpc_timer* prev;
38 #ifndef NDEBUG
40 #endif
41 
42  // Optional field used by custom timers
43  void* custom_timer;
45 
46 typedef enum {
51 
52 typedef struct grpc_timer_vtable {
53  void (*init)(grpc_timer* timer, grpc_millis, grpc_closure* closure);
54  void (*cancel)(grpc_timer* timer);
55 
56  /* Internal API */
58  void (*list_init)();
59  void (*list_shutdown)(void);
60  void (*consume_kick)(void);
62 
63 /* Initialize *timer. When expired or canceled, closure will be called with
64  error set to indicate if it expired (GRPC_ERROR_NONE) or was canceled
65  (GRPC_ERROR_CANCELLED). *closure is guaranteed to be called exactly once, and
66  application code should check the error to determine how it was invoked. The
67  application callback is also responsible for maintaining information about
68  when to free up any user-level state. Behavior is undefined for a deadline of
69  GRPC_MILLIS_INF_FUTURE. */
70 void grpc_timer_init(grpc_timer* timer, grpc_millis deadline,
71  grpc_closure* closure);
72 
73 /* Initialize *timer without setting it. This can later be passed through
74  the regular init or cancel */
76 
77 /* Note that there is no timer destroy function. This is because the
78  timer is a one-time occurrence with a guarantee that the callback will
79  be called exactly once, either at expiration or cancellation. Thus, all
80  the internal timer event management state is destroyed just before
81  that callback is invoked. If the user has additional state associated with
82  the timer, the user is responsible for determining when it is safe to
83  destroy that state. */
84 
85 /* Cancel an *timer.
86  There are three cases:
87  1. We normally cancel the timer
88  2. The timer has already run
89  3. We can't cancel the timer because it is "in flight".
90 
91  In all of these cases, the cancellation is still considered successful.
92  They are essentially distinguished in that the timer_cb will be run
93  exactly once from either the cancellation (with error GRPC_ERROR_CANCELLED)
94  or from the activation (with error GRPC_ERROR_NONE).
95 
96  Note carefully that the callback function MAY occur in the same callstack
97  as grpc_timer_cancel. It's expected that most timers will be cancelled (their
98  primary use is to implement deadlines), and so this code is optimized such
99  that cancellation costs as little as possible. Making callbacks run inline
100  matches this aim.
101 
102  Requires: cancel() must happen after init() on a given timer */
103 void grpc_timer_cancel(grpc_timer* timer);
104 
105 /* iomgr internal api for dealing with timers */
106 
107 /* Check for timers to be run, and run them.
108  Return true if timer callbacks were executed.
109  If next is non-null, TRY to update *next with the next running timer
110  IF that timer occurs before *next current value.
111  *next is never guaranteed to be updated on any given execution; however,
112  with high probability at least one thread in the system will see an update
113  at any time slice. */
115 void grpc_timer_list_init();
117 
118 /* Consume a kick issued by grpc_kick_poller */
119 void grpc_timer_consume_kick(void);
120 
121 /* the following must be implemented by each iomgr implementation */
122 void grpc_kick_poller(void);
123 
124 /* Sets the timer implementation */
126 
127 #endif /* GRPC_CORE_LIB_IOMGR_TIMER_H */
QueuedPick * next
Definition: client_channel.cc:113
int64_t grpc_millis
Definition: exec_ctx.h:35
A closure over a grpc_iomgr_cb_func.
Definition: closure.h:56
Definition: timer.h:52
void(* cancel)(grpc_timer *timer)
Definition: timer.h:54
void(* list_shutdown)(void)
Definition: timer.h:59
void(* init)(grpc_timer *timer, grpc_millis, grpc_closure *closure)
Definition: timer.h:53
void(* list_init)()
Definition: timer.h:58
void(* consume_kick)(void)
Definition: timer.h:60
grpc_timer_check_result(* check)(grpc_millis *next)
Definition: timer.h:57
Definition: timer.h:30
void * custom_timer
Definition: timer.h:43
grpc_millis deadline
Definition: timer.h:31
uint32_t heap_index
Definition: timer.h:33
struct grpc_timer * hash_table_next
Definition: timer.h:39
grpc_closure * closure
Definition: timer.h:37
struct grpc_timer * next
Definition: timer.h:35
bool pending
Definition: timer.h:34
struct grpc_timer * prev
Definition: timer.h:36
struct grpc_timer grpc_timer
void grpc_timer_list_init()
Definition: timer.cc:41
void grpc_set_timer_impl(grpc_timer_vtable *vtable)
Definition: timer.cc:26
void grpc_timer_cancel(grpc_timer *timer)
Definition: timer.cc:35
void grpc_timer_list_shutdown()
Definition: timer.cc:43
void grpc_timer_init(grpc_timer *timer, grpc_millis deadline, grpc_closure *closure)
Definition: timer.cc:30
grpc_timer_check_result grpc_timer_check(grpc_millis *next)
Definition: timer.cc:37
void grpc_timer_consume_kick(void)
Definition: timer.cc:45
struct grpc_timer_vtable grpc_timer_vtable
void grpc_timer_init_unset(grpc_timer *timer)
Definition: timer_generic.cc:351
void grpc_kick_poller(void)
Definition: timer_manager.cc:353
grpc_timer_check_result
Definition: timer.h:46
@ GRPC_TIMERS_CHECKED_AND_EMPTY
Definition: timer.h:48
@ GRPC_TIMERS_FIRED
Definition: timer.h:49
@ GRPC_TIMERS_NOT_CHECKED
Definition: timer.h:47