legacy-libs/grpc/deps/grpc/src/core/lib/iomgr/timer.h

   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   // 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;
  37   grpc_closure* closure;
  38 #ifndef NDEBUG
  39   struct grpc_timer* hash_table_next;
  40 #endif
  41
  42   // Optional field used by custom timers
  43   void* custom_timer;
  44 } grpc_timer;
  45
  46 typedef enum {
  47   GRPC_TIMERS_NOT_CHECKED,
  48   GRPC_TIMERS_CHECKED_AND_EMPTY,
  49   GRPC_TIMERS_FIRED,
  50 } grpc_timer_check_result;
  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 */
  57   grpc_timer_check_result (*check)(grpc_millis* next);
  58   void (*list_init)();
  59   void (*list_shutdown)(void);
  60   void (*consume_kick)(void);
  61 } grpc_timer_vtable;
  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 */
  75 void grpc_timer_init_unset(grpc_timer* timer);
  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. */
 114 grpc_timer_check_result grpc_timer_check(grpc_millis* next);
 115 void grpc_timer_list_init();
 116 void grpc_timer_list_shutdown();
 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 */
 125 void grpc_set_timer_impl(grpc_timer_vtable* vtable);
 126
 127 #endif /* GRPC_CORE_LIB_IOMGR_TIMER_H */