ctiller | 18b49ab | 2014-12-09 14:39:16 -0800 | [diff] [blame] | 1 | /* |
| 2 | * |
Jan Tattermusch | 7897ae9 | 2017-06-07 22:57:36 +0200 | [diff] [blame] | 3 | * Copyright 2015 gRPC authors. |
ctiller | 18b49ab | 2014-12-09 14:39:16 -0800 | [diff] [blame] | 4 | * |
Jan Tattermusch | 7897ae9 | 2017-06-07 22:57:36 +0200 | [diff] [blame] | 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 |
ctiller | 18b49ab | 2014-12-09 14:39:16 -0800 | [diff] [blame] | 8 | * |
Jan Tattermusch | 7897ae9 | 2017-06-07 22:57:36 +0200 | [diff] [blame] | 9 | * http://www.apache.org/licenses/LICENSE-2.0 |
ctiller | 18b49ab | 2014-12-09 14:39:16 -0800 | [diff] [blame] | 10 | * |
Jan Tattermusch | 7897ae9 | 2017-06-07 22:57:36 +0200 | [diff] [blame] | 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. |
ctiller | 18b49ab | 2014-12-09 14:39:16 -0800 | [diff] [blame] | 16 | * |
| 17 | */ |
| 18 | |
Craig Tiller | 9a4dddd | 2016-03-25 17:08:13 -0700 | [diff] [blame] | 19 | #ifndef GRPC_CORE_LIB_IOMGR_TIMER_H |
| 20 | #define GRPC_CORE_LIB_IOMGR_TIMER_H |
ctiller | 18b49ab | 2014-12-09 14:39:16 -0800 | [diff] [blame] | 21 | |
murgatroid99 | 9030c81 | 2016-09-16 13:25:08 -0700 | [diff] [blame] | 22 | #include "src/core/lib/iomgr/port.h" |
| 23 | |
| 24 | #ifdef GRPC_UV |
| 25 | #include "src/core/lib/iomgr/timer_uv.h" |
| 26 | #else |
| 27 | #include "src/core/lib/iomgr/timer_generic.h" |
| 28 | #endif /* GRPC_UV */ |
| 29 | |
ctiller | 18b49ab | 2014-12-09 14:39:16 -0800 | [diff] [blame] | 30 | #include <grpc/support/port_platform.h> |
| 31 | #include <grpc/support/time.h> |
Craig Tiller | 9533d04 | 2016-03-25 17:11:06 -0700 | [diff] [blame] | 32 | #include "src/core/lib/iomgr/exec_ctx.h" |
| 33 | #include "src/core/lib/iomgr/iomgr.h" |
ctiller | 18b49ab | 2014-12-09 14:39:16 -0800 | [diff] [blame] | 34 | |
Yash Tibrewal | a7e6d65 | 2017-09-20 18:56:37 -0700 | [diff] [blame] | 35 | #ifdef __cplusplus |
| 36 | extern "C" { |
| 37 | #endif |
| 38 | |
murgatroid99 | 9030c81 | 2016-09-16 13:25:08 -0700 | [diff] [blame] | 39 | typedef struct grpc_timer grpc_timer; |
ctiller | 18b49ab | 2014-12-09 14:39:16 -0800 | [diff] [blame] | 40 | |
Masood Malekghassemi | b5b4372 | 2017-01-05 15:07:26 -0800 | [diff] [blame] | 41 | /* Initialize *timer. When expired or canceled, closure will be called with |
| 42 | error set to indicate if it expired (GRPC_ERROR_NONE) or was canceled |
| 43 | (GRPC_ERROR_CANCELLED). timer_cb is guaranteed to be called exactly once, and |
| 44 | application code should check the error to determine how it was invoked. The |
| 45 | application callback is also responsible for maintaining information about |
| 46 | when to free up any user-level state. */ |
David Garcia Quintas | f747bbc | 2015-10-04 23:09:47 -0700 | [diff] [blame] | 47 | void grpc_timer_init(grpc_exec_ctx *exec_ctx, grpc_timer *timer, |
Masood Malekghassemi | b5b4372 | 2017-01-05 15:07:26 -0800 | [diff] [blame] | 48 | gpr_timespec deadline, grpc_closure *closure, |
| 49 | gpr_timespec now); |
ctiller | 18b49ab | 2014-12-09 14:39:16 -0800 | [diff] [blame] | 50 | |
Vijay Pai | 58c33ba | 2017-09-01 14:08:42 -0700 | [diff] [blame] | 51 | /* Initialize *timer without setting it. This can later be passed through |
| 52 | the regular init or cancel */ |
| 53 | void grpc_timer_init_unset(grpc_timer *timer); |
| 54 | |
David Garcia Quintas | f747bbc | 2015-10-04 23:09:47 -0700 | [diff] [blame] | 55 | /* Note that there is no timer destroy function. This is because the |
| 56 | timer is a one-time occurrence with a guarantee that the callback will |
ctiller | 18b49ab | 2014-12-09 14:39:16 -0800 | [diff] [blame] | 57 | be called exactly once, either at expiration or cancellation. Thus, all |
David Garcia Quintas | f747bbc | 2015-10-04 23:09:47 -0700 | [diff] [blame] | 58 | the internal timer event management state is destroyed just before |
ctiller | 18b49ab | 2014-12-09 14:39:16 -0800 | [diff] [blame] | 59 | that callback is invoked. If the user has additional state associated with |
David Garcia Quintas | f747bbc | 2015-10-04 23:09:47 -0700 | [diff] [blame] | 60 | the timer, the user is responsible for determining when it is safe to |
ctiller | 18b49ab | 2014-12-09 14:39:16 -0800 | [diff] [blame] | 61 | destroy that state. */ |
| 62 | |
David Garcia Quintas | f747bbc | 2015-10-04 23:09:47 -0700 | [diff] [blame] | 63 | /* Cancel an *timer. |
ctiller | 18b49ab | 2014-12-09 14:39:16 -0800 | [diff] [blame] | 64 | There are three cases: |
David Garcia Quintas | f747bbc | 2015-10-04 23:09:47 -0700 | [diff] [blame] | 65 | 1. We normally cancel the timer |
| 66 | 2. The timer has already run |
| 67 | 3. We can't cancel the timer because it is "in flight". |
ctiller | 18b49ab | 2014-12-09 14:39:16 -0800 | [diff] [blame] | 68 | |
| 69 | In all of these cases, the cancellation is still considered successful. |
David Garcia Quintas | f747bbc | 2015-10-04 23:09:47 -0700 | [diff] [blame] | 70 | They are essentially distinguished in that the timer_cb will be run |
Mark D. Roth | 7c8b756 | 2016-10-05 07:34:01 -0700 | [diff] [blame] | 71 | exactly once from either the cancellation (with error GRPC_ERROR_CANCELLED) |
| 72 | or from the activation (with error GRPC_ERROR_NONE). |
ctiller | 18b49ab | 2014-12-09 14:39:16 -0800 | [diff] [blame] | 73 | |
ctiller | 3bf466f | 2014-12-19 16:21:57 -0800 | [diff] [blame] | 74 | Note carefully that the callback function MAY occur in the same callstack |
David Garcia Quintas | f747bbc | 2015-10-04 23:09:47 -0700 | [diff] [blame] | 75 | as grpc_timer_cancel. It's expected that most timers will be cancelled (their |
ctiller | 3bf466f | 2014-12-19 16:21:57 -0800 | [diff] [blame] | 76 | primary use is to implement deadlines), and so this code is optimized such |
| 77 | that cancellation costs as little as possible. Making callbacks run inline |
| 78 | matches this aim. |
| 79 | |
Mark D. Roth | 7c8b756 | 2016-10-05 07:34:01 -0700 | [diff] [blame] | 80 | Requires: cancel() must happen after init() on a given timer */ |
David Garcia Quintas | f747bbc | 2015-10-04 23:09:47 -0700 | [diff] [blame] | 81 | void grpc_timer_cancel(grpc_exec_ctx *exec_ctx, grpc_timer *timer); |
ctiller | 18b49ab | 2014-12-09 14:39:16 -0800 | [diff] [blame] | 82 | |
Craig Tiller | ccdea19 | 2016-02-16 08:06:46 -0800 | [diff] [blame] | 83 | /* iomgr internal api for dealing with timers */ |
| 84 | |
Craig Tiller | b2ef1cf | 2017-05-30 09:25:48 -0700 | [diff] [blame] | 85 | typedef enum { |
| 86 | GRPC_TIMERS_NOT_CHECKED, |
| 87 | GRPC_TIMERS_CHECKED_AND_EMPTY, |
| 88 | GRPC_TIMERS_FIRED, |
| 89 | } grpc_timer_check_result; |
| 90 | |
Craig Tiller | ccdea19 | 2016-02-16 08:06:46 -0800 | [diff] [blame] | 91 | /* Check for timers to be run, and run them. |
Craig Tiller | 311445f | 2016-02-18 07:31:39 -0800 | [diff] [blame] | 92 | Return true if timer callbacks were executed. |
Craig Tiller | ccdea19 | 2016-02-16 08:06:46 -0800 | [diff] [blame] | 93 | If next is non-null, TRY to update *next with the next running timer |
| 94 | IF that timer occurs before *next current value. |
| 95 | *next is never guaranteed to be updated on any given execution; however, |
| 96 | with high probability at least one thread in the system will see an update |
| 97 | at any time slice. */ |
Craig Tiller | b2ef1cf | 2017-05-30 09:25:48 -0700 | [diff] [blame] | 98 | grpc_timer_check_result grpc_timer_check(grpc_exec_ctx *exec_ctx, |
| 99 | gpr_timespec now, gpr_timespec *next); |
Craig Tiller | ccdea19 | 2016-02-16 08:06:46 -0800 | [diff] [blame] | 100 | void grpc_timer_list_init(gpr_timespec now); |
Craig Tiller | 311445f | 2016-02-18 07:31:39 -0800 | [diff] [blame] | 101 | void grpc_timer_list_shutdown(grpc_exec_ctx *exec_ctx); |
Craig Tiller | ccdea19 | 2016-02-16 08:06:46 -0800 | [diff] [blame] | 102 | |
Craig Tiller | 185f6c9 | 2017-03-17 08:33:19 -0700 | [diff] [blame] | 103 | /* Consume a kick issued by grpc_kick_poller */ |
| 104 | void grpc_timer_consume_kick(void); |
| 105 | |
Craig Tiller | ccdea19 | 2016-02-16 08:06:46 -0800 | [diff] [blame] | 106 | /* the following must be implemented by each iomgr implementation */ |
| 107 | |
| 108 | void grpc_kick_poller(void); |
| 109 | |
Yash Tibrewal | a7e6d65 | 2017-09-20 18:56:37 -0700 | [diff] [blame] | 110 | #ifdef __cplusplus |
| 111 | } |
| 112 | #endif |
| 113 | |
Craig Tiller | 9a4dddd | 2016-03-25 17:08:13 -0700 | [diff] [blame] | 114 | #endif /* GRPC_CORE_LIB_IOMGR_TIMER_H */ |