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