eal: fix thread header include

[dpdk.git] / lib / librte_timer / rte_timer.h

diff --git a/lib/librte_timer/rte_timer.h b/lib/librte_timer/rte_timer.h
index 9dc5fc3..22a27aa 100644 (file)
--- a/lib/librte_timer/rte_timer.h
+++ b/lib/librte_timer/rte_timer.h
@@ -133,9 +133,6 @@ struct rte_timer
 #endif
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * Allocate a timer data instance in shared memory to track a set of pending
  * timer lists.
  *
@@ -147,13 +144,9 @@ struct rte_timer
  *   - 0: Success
  *   - -ENOSPC: maximum number of timer data instances already allocated
  */
-__rte_experimental
 int rte_timer_data_alloc(uint32_t *id_ptr);
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * Deallocate a timer data instance.
  *
  * @param id
@@ -163,7 +156,6 @@ int rte_timer_data_alloc(uint32_t *id_ptr);
  *   - 0: Success
  *   - -EINVAL: invalid timer data instance identifier
  */
-__rte_experimental
 int rte_timer_data_dealloc(uint32_t id);
 
 /**
@@ -183,12 +175,8 @@ int rte_timer_data_dealloc(uint32_t id);
 int rte_timer_subsystem_init(void);
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * Free timer subsystem resources.
  */
-__rte_experimental
 void rte_timer_subsystem_finalize(void);
 
 /**
@@ -274,6 +262,12 @@ int rte_timer_reset(struct rte_timer *tim, uint64_t ticks,
  *   The callback function of the timer.
  * @param arg
  *   The user argument of the callback function.
+ *
+ * @note
+ *   This API should not be called inside a timer's callback function to
+ *   reset another timer; doing so could hang in certain scenarios. Instead,
+ *   the rte_timer_reset() API can be called directly and its return code
+ *   can be checked for success or failure.
  */
 void
 rte_timer_reset_sync(struct rte_timer *tim, uint64_t ticks,
@@ -313,6 +307,12 @@ int rte_timer_stop(struct rte_timer *tim);
  *
  * @param tim
  *   The timer handle.
+ *
+ * @note
+ *   This API should not be called inside a timer's callback function to
+ *   stop another timer; doing so could hang in certain scenarios. Instead, the
+ *   rte_timer_stop() API can be called directly and its return code can
+ *   be checked for success or failure.
  */
 void rte_timer_stop_sync(struct rte_timer *tim);
 
@@ -331,6 +331,22 @@ void rte_timer_stop_sync(struct rte_timer *tim);
  */
 int rte_timer_pending(struct rte_timer *tim);
 
+/**
+ * @warning
+ * @b EXPERIMENTAL: this API may change without prior notice
+ *
+ * Time until the next timer on the current lcore
+ * This function gives the ticks until the next timer will be active.
+ *
+ * @return
+ *   - -EINVAL: invalid timer data instance identifier
+ *   - -ENOENT: no timer pending
+ *   - 0: a timer is pending and will run at next rte_timer_manage()
+ *   - >0: ticks until the next timer is ready
+ */
+__rte_experimental
+int64_t rte_timer_next_ticks(void);
+
 /**
  * Manage the timer list and execute callback functions.
  *
@@ -360,9 +376,6 @@ int rte_timer_manage(void);
 int rte_timer_dump_stats(FILE *f);
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * This function is the same as rte_timer_reset(), except that it allows a
  * caller to specify the rte_timer_data instance containing the list to which
  * the timer should be added.
@@ -397,16 +410,12 @@ int rte_timer_dump_stats(FILE *f);
  *   - (-1): Timer is in the RUNNING or CONFIG state.
  *   - -EINVAL: invalid timer_data_id
  */
-__rte_experimental
 int
 rte_timer_alt_reset(uint32_t timer_data_id, struct rte_timer *tim,
                    uint64_t ticks, enum rte_timer_type type,
                    unsigned int tim_lcore, rte_timer_cb_t fct, void *arg);
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * This function is the same as rte_timer_stop(), except that it allows a
  * caller to specify the rte_timer_data instance containing the list from which
  * this timer should be removed.
@@ -423,7 +432,6 @@ rte_timer_alt_reset(uint32_t timer_data_id, struct rte_timer *tim,
  *   - (-1): The timer is in the RUNNING or CONFIG state.
  *   - -EINVAL: invalid timer_data_id
  */
-__rte_experimental
 int
 rte_timer_alt_stop(uint32_t timer_data_id, struct rte_timer *tim);
 
@@ -433,9 +441,6 @@ rte_timer_alt_stop(uint32_t timer_data_id, struct rte_timer *tim);
 typedef void (*rte_timer_alt_manage_cb_t)(struct rte_timer *tim);
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * Manage a set of timer lists and execute the specified callback function for
  * all expired timers. This function is similar to rte_timer_manage(), except
  * that it allows a caller to specify the timer_data instance that should
@@ -460,7 +465,6 @@ typedef void (*rte_timer_alt_manage_cb_t)(struct rte_timer *tim);
  *   - 0: success
  *   - -EINVAL: invalid timer_data_id
  */
-__rte_experimental
 int
 rte_timer_alt_manage(uint32_t timer_data_id, unsigned int *poll_lcores,
                     int n_poll_lcores, rte_timer_alt_manage_cb_t f);
@@ -471,9 +475,6 @@ rte_timer_alt_manage(uint32_t timer_data_id, unsigned int *poll_lcores,
 typedef void (*rte_timer_stop_all_cb_t)(struct rte_timer *tim, void *arg);
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * Walk the pending timer lists for the specified lcore IDs, and for each timer
  * that is encountered, stop it and call the specified callback function to
  * process it further.
@@ -493,15 +494,11 @@ typedef void (*rte_timer_stop_all_cb_t)(struct rte_timer *tim, void *arg);
  *   - 0: success
  *   - EINVAL: invalid timer_data_id
  */
-__rte_experimental
 int
 rte_timer_stop_all(uint32_t timer_data_id, unsigned int *walk_lcores,
                   int nb_walk_lcores, rte_timer_stop_all_cb_t f, void *f_arg);
 
 /**
- * @warning
- * @b EXPERIMENTAL: this API may change without prior notice
- *
  * This function is the same as rte_timer_dump_stats(), except that it allows
  * the caller to specify the rte_timer_data instance that should be used.
  *
@@ -516,7 +513,6 @@ rte_timer_stop_all(uint32_t timer_data_id, unsigned int *walk_lcores,
  *   - 0: success
  *   - -EINVAL: invalid timer_data_id
  */
-__rte_experimental
 int
 rte_timer_alt_dump_stats(uint32_t timer_data_id, FILE *f);