2121 */
2222
2323/**
24- * @file retry_utils .h
24+ * @file backoff_algorithm .h
2525 * @brief Declaration of retry utility functions and constants for exponential backoff with
2626 * jitter strategy of retry attempts.
2727 * This library represents the "Full Jitter" backoff strategy explained in the
3030 *
3131 */
3232
33- #ifndef RETRY_UTILS_H_
34- #define RETRY_UTILS_H_
33+ #ifndef BACKOFF_ALGORITHM_H_
34+ #define BACKOFF_ALGORITHM_H_
3535
3636/* Standard include. */
3737#include <stdint.h>
3838
3939/**
40- * @page retryutils_page Retry Utilities
41- * @brief An abstraction of utilities for retrying with exponential back off and
42- * jitter.
40+ * @page backoffalgorithm_page Backoff Algorithm
41+ * @brief Library for calculating backoff of retry attempts using exponential back off and
42+ * jitter algorithm .
4343 *
44- * @section retryutils_overview Overview
45- * The retry utilities are a set of APIs that aid in retrying with exponential
44+ * @section backoffalgorithm_overview Overview
45+ * The backoff algorithm library is a set of APIs that aid in retrying with exponential
4646 * backoff and jitter. Exponential backoff with jitter is strongly recommended
4747 * for retrying failed actions over the network with servers. Please see
4848 * https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/ for
6666/**
6767 * @brief Constant to represent unlimited number of retry attempts.
6868 */
69- #define RETRY_UTILS_RETRY_FOREVER 0
69+ #define BACKOFF_ALGORITHM_RETRY_FOREVER 0
7070
7171/**
7272 * @brief Interface for a random number generator.
7373 * The user should supply the platform-specific random number generator to the
74- * library through the @ref RetryUtils_InitializeParams API function.
74+ * library through the @ref BackoffAlgorithm_InitializeParams API function.
7575 *
7676 * @note It is recommended that a true random number generator is supplied
7777 * to the library. The random number generator should be seeded with an entropy
8080 * @return The random number if successful; otherwise a negative value to indicate
8181 * failure.
8282 */
83- typedef int32_t ( * RetryUtils_RNG_t )();
83+ typedef int32_t ( * BackoffAlgorithm_RNG_t )();
8484
8585/**
86- * @brief Status for @ref RetryUtils_GetNextBackOff .
86+ * @brief Status for @ref BackoffAlgorithm_GetNextBackoff .
8787 */
88- typedef enum RetryUtilsStatus
88+ typedef enum BackoffAlgorithmStatus
8989{
90- RetryUtilsSuccess = 0 , /**< @brief The function successfully calculated the next back-off value. */
91- RetryUtilsRngFailure = 1 , /**< @brief The function encountered failure in generating random number. */
92- RetryUtilsRetriesExhausted /**< @brief The function exhausted all retry attempts. */
93- } RetryUtilsStatus_t ;
90+ BackoffAlgorithmSuccess = 0 , /**< @brief The function successfully calculated the next back-off value. */
91+ BackoffAlgorithmRngFailure = 1 , /**< @brief The function encountered failure in generating random number. */
92+ BackoffAlgorithmRetriesExhausted /**< @brief The function exhausted all retry attempts. */
93+ } BackoffAlgorithmStatus_t ;
9494
9595/**
9696 * @brief Represents parameters required for calculating the back-off delay for the
9797 * next retry attempt.
9898 */
99- typedef struct RetryUtilsContext
99+ typedef struct BackoffAlgorithmContext
100100{
101101 /**
102102 * @brief The maximum backoff delay (in milliseconds) between consecutive retry attempts.
@@ -105,7 +105,7 @@ typedef struct RetryUtilsContext
105105
106106 /**
107107 * @brief The total number of retry attempts completed.
108- * This value is incremented on every call to #RetryUtils_GetNextBackOff API.
108+ * This value is incremented on every call to #BackoffAlgorithm_GetNextBackoff API.
109109 */
110110 uint32_t attemptsDone ;
111111
@@ -123,11 +123,11 @@ typedef struct RetryUtilsContext
123123 * @brief The random number generator function used for calculating the
124124 * backoff value for the next retry attempt.
125125 */
126- RetryUtils_RNG_t pRng ;
127- } RetryUtilsContext_t ;
126+ BackoffAlgorithm_RNG_t pRng ;
127+ } BackoffAlgorithmContext_t ;
128128
129129/**
130- * @brief Initializes the context for using retry utils . The parameters
130+ * @brief Initializes the context for using backoff algorithm . The parameters
131131 * are required for calculating the next retry backoff delay.
132132 * This function must be called by the application before the first new retry attempt.
133133 *
@@ -138,17 +138,17 @@ typedef struct RetryUtilsContext
138138 * @param[in] backOffBase The base value (in milliseconds) of backoff delay to
139139 * use in the exponential backoff and jitter model.
140140 * @param[in] maxAttempts The maximum number of retry attempts. Set the value to
141- * #RETRY_UTILS_RETRY_FOREVER to retry for ever.
141+ * #BACKOFF_ALGORITHM_RETRY_FOREVER to retry for ever.
142142 * @param[in] pRng The platform-specific function to use for random number generation.
143143 * The random number generator should be seeded before calling this function.
144144 */
145- /* @[define_retryutils_initializeparams ] */
146- void RetryUtils_InitializeParams ( RetryUtilsContext_t * pContext ,
147- uint16_t backOffBase ,
148- uint16_t maxBackOff ,
149- uint32_t maxAttempts ,
150- RetryUtils_RNG_t pRng );
151- /* @[define_retryutils_initializeparams ] */
145+ /* @[define_backoffalgorithm_initializeparams ] */
146+ void BackoffAlgorithm_InitializeParams ( BackoffAlgorithmContext_t * pContext ,
147+ uint16_t backOffBase ,
148+ uint16_t maxBackOff ,
149+ uint32_t maxAttempts ,
150+ BackoffAlgorithm_RNG_t pRng );
151+ /* @[define_backoffalgorithm_initializeparams ] */
152152
153153/**
154154 * @brief Simple exponential backoff and jitter function that provides the
@@ -163,12 +163,12 @@ void RetryUtils_InitializeParams( RetryUtilsContext_t * pContext,
163163 * for the next retry attempt. The value does not exceed the maximum backoff delay
164164 * configured in the context.
165165 *
166- * @return #RetryUtilsSuccess after a successful sleep, #RetryUtilsRngFailure for a failure
167- * in random number generation, #RetryUtilsRetriesExhausted when all attempts are exhausted.
166+ * @return #BackoffAlgorithmSuccess after a successful sleep, #BackoffAlgorithmRngFailure for a failure
167+ * in random number generation, #BackoffAlgorithmRetriesExhausted when all attempts are exhausted.
168168 */
169- /* @[define_retryutils_getnextbackoff ] */
170- RetryUtilsStatus_t RetryUtils_GetNextBackOff ( RetryUtilsContext_t * pRetryContext ,
171- uint16_t * pNextBackOff );
172- /* @[define_retryutils_getnextbackoff ] */
169+ /* @[define_BackoffAlgorithm_GetNextBackoff ] */
170+ BackoffAlgorithmStatus_t BackoffAlgorithm_GetNextBackoff ( BackoffAlgorithmContext_t * pRetryContext ,
171+ uint16_t * pNextBackOff );
172+ /* @[define_BackoffAlgorithm_GetNextBackoff ] */
173173
174- #endif /* ifndef RETRY_UTILS_H_ */
174+ #endif /* ifndef BACKOFF_ALGORITHM_H_ */
0 commit comments