lib/librte_eal/common/include/rte_alarm.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2010-2014 Intel Corporation
   3  */
   4
   5 #ifndef _RTE_ALARM_H_
   6 #define _RTE_ALARM_H_
   7
   8 /**
   9  * @file
  10  *
  11  * Alarm functions
  12  *
  13  * Simple alarm-clock functionality supplied by eal.
  14  * Does not require hpet support.
  15  */
  16
  17 #ifdef __cplusplus
  18 extern "C" {
  19 #endif
  20
  21 #include <stdint.h>
  22
  23 /**
  24  * Signature of callback back function called when an alarm goes off.
  25  */
  26 typedef void (*rte_eal_alarm_callback)(void *arg);
  27
  28 /**
  29  * Function to set a callback to be triggered when us microseconds
  30  * have expired. Accuracy of timing to the microsecond is not guaranteed. The
  31  * alarm function will not be called *before* the requested time, but may
  32  * be called a short period of time afterwards.
  33  * The alarm handler will be called only once. There is no need to call
  34  * "rte_eal_alarm_cancel" from within the callback function.
  35  *
  36  * @param us
  37  *   The time in microseconds before the callback is called
  38  * @param cb
  39  *   The function to be called when the alarm expires
  40  * @param cb_arg
  41  *   Pointer parameter to be passed to the callback function
  42  *
  43  * @return
  44  *   On success, zero.
  45  *   On failure, a negative error number
  46  */
  47 int rte_eal_alarm_set(uint64_t us, rte_eal_alarm_callback cb, void *cb_arg);
  48
  49 /**
  50  * Function to cancel an alarm callback which has been registered before. If
  51  * used outside alarm callback it wait for all callbacks to finish execution.
  52  *
  53  * @param cb_fn
  54  *  alarm callback
  55  * @param cb_arg
  56  *  Pointer parameter to be passed to the callback function. To remove all
  57  *  copies of a given callback function, irrespective of parameter, (void *)-1
  58  *  can be used here.
  59  *
  60  * @return
  61  *    - value greater than 0 and rte_errno not changed - returned value is
  62  *      the number of canceled alarm callback functions
  63  *    - value greater or equal 0 and rte_errno set to EINPROGRESS, at least one
  64  *      alarm could not be canceled because cancellation was requested from alarm
  65  *      callback context. Returned value is the number of successfully canceled
  66  *      alarm callbacks
  67  *    -  0 and rte_errno set to ENOENT - no alarm found
  68  *    - -1 and rte_errno set to EINVAL - invalid parameter (NULL callback)
  69  */
  70 int rte_eal_alarm_cancel(rte_eal_alarm_callback cb_fn, void *cb_arg);
  71
  72 #ifdef __cplusplus
  73 }
  74 #endif
  75
  76
  77 #endif /* _RTE_ALARM_H_ */