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