osi/include/alarm.h

   1 /******************************************************************************
   2  *
   3  *  Copyright (C) 2014 Google, Inc.
   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 #pragma once
  20
  21 #include <stdbool.h>
  22 #include <stdint.h>
  23
  24 typedef struct alarm_t alarm_t;
  25 typedef struct fixed_queue_t fixed_queue_t;
  26 typedef struct thread_t thread_t;
  27 typedef uint64_t period_ms_t;
  28
  29 // Prototype for the alarm callback function.
  30 typedef void (*alarm_callback_t)(void *data);
  31
  32 // Creates a new one-time off alarm object with user-assigned
  33 // |name|. |name| may not be NULL, and a copy of the string will
  34 // be stored internally. The value of |name| has no semantic
  35 // meaning. It is recommended that the name is unique (for
  36 // better debuggability), but that is not enforced. The returned
  37 // object must be freed by calling |alarm_free|. Returns NULL on
  38 // failure.
  39 alarm_t *alarm_new(const char *name);
  40
  41 // Creates a new periodic alarm object with user-assigned |name|.
  42 // |name| may not be NULL, and a copy of the string will be
  43 // stored internally. The value of |name| has no semantic
  44 // meaning. It is recommended that the name is unique (for better
  45 // debuggability), but that is not enforced. The returned object
  46 // must be freed by calling |alarm_free|. Returns NULL on
  47 // failure.
  48 alarm_t *alarm_new_periodic(const char *name);
  49
  50 // Frees an |alarm| object created by |alarm_new| or
  51 // |alarm_new_periodic|. |alarm| may be NULL. If the alarm is
  52 // pending, it will be cancelled first. It is not safe to call
  53 // |alarm_free| from inside the callback of |alarm|.
  54 void alarm_free(alarm_t *alarm);
  55
  56 // Sets an |alarm| to execute a callback in the future. The |cb|
  57 // callback is called after the given |interval_ms|, where
  58 // |interval_ms| is the number of milliseconds relative to the
  59 // current time. If |alarm| was created with
  60 // |alarm_new_periodic|, the alarm is scheduled to fire
  61 // periodically every |interval_ms|, otherwise it is a one time
  62 // only alarm. A periodic alarm repeats every |interval_ms| until
  63 // it is cancelled or freed. When the alarm fires, the |cb|
  64 // callback is called with the context argument |data|:
  65 //
  66 //      void cb(void *data) {...}
  67 //
  68 // The |data| argument may be NULL, but the |cb| callback may not
  69 // be NULL. All |cb| callbacks scheduled through this call are
  70 // called within a single (internally created) thread. That
  71 // thread is not same as the caller’s thread. If two (or more)
  72 // alarms are set back-to-back with the same |interval_ms|, the
  73 // callbacks will be called in the order the alarms are set.
  74 void alarm_set(alarm_t *alarm, period_ms_t interval_ms,
  75                alarm_callback_t cb, void *data);
  76
  77 // Sets an |alarm| to execute a callback in the future on a
  78 // specific |queue|. This function is same as |alarm_set| except
  79 // that the |cb| callback is scheduled for execution in the
  80 // context of the thread responsible for processing |queue|.
  81 // Also, the callback execution ordering guarantee exists only
  82 // among alarms that are scheduled on the same queue. |queue|
  83 // may not be NULL.
  84 void alarm_set_on_queue(alarm_t *alarm, period_ms_t interval_ms,
  85                         alarm_callback_t cb, void *data,
  86                         fixed_queue_t *queue);
  87
  88 // This function cancels the |alarm| if it was previously set.
  89 // When this call returns, the caller has a guarantee that the
  90 // callback is not in progress and will not be called if it
  91 // hasn't already been called. This function is idempotent.
  92 // |alarm| may not be NULL.
  93 void alarm_cancel(alarm_t *alarm);
  94
  95 // Tests whether the |alarm| is scheduled.
  96 // Return true if the |alarm| is scheduled or NULL, otherwise false.
  97 bool alarm_is_scheduled(const alarm_t *alarm);
  98
  99 // Registers |queue| for processing alarm callbacks on |thread|.
 100 // |queue| may not be NULL. |thread| may not be NULL.
 101 void alarm_register_processing_queue(fixed_queue_t *queue, thread_t *thread);
 102
 103 // Unregisters |queue| for processing alarm callbacks on whichever thread
 104 // it is registered with. |queue| may not be NULL.
 105 // This function is idempotent.
 106 void alarm_unregister_processing_queue(fixed_queue_t *queue);
 107
 108 // Figure out how much time until next expiration.
 109 // Returns 0 if not armed. |alarm| may not be NULL.
 110 // TODO: Remove this function once PM timers can be re-factored
 111 period_ms_t alarm_get_remaining_ms(const alarm_t *alarm);
 112
 113 // Cleanup the alarm internal state.
 114 // This function should be called by the OSI module cleanup during
 115 // graceful shutdown.
 116 void alarm_cleanup(void);
 117
 118 // Dump alarm-related statistics and debug info to the |fd| file descriptor.
 119 // The information is in user-readable text format. The |fd| must be valid.
 120 void alarm_debug_dump(int fd);