backoffAlgorithm v1.3.0
Algorithmic library for calculating retry intervals using exponential backoff and jitter.
backoff_algorithm.h File Reference

API for calculating backoff period for retry attempts using exponential backoff with jitter algorithm. This library represents the "Full Jitter" backoff strategy explained in the following document. https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/. More...

#include <stdint.h>

Go to the source code of this file.

Data Structures

struct  BackoffAlgorithmContext_t
 Represents parameters required for calculating the back-off delay for the next retry attempt. More...
 

Macros

#define BACKOFF_ALGORITHM_RETRY_FOREVER   ( UINT32_MAX )
 Constant to represent unlimited number of retry attempts.
 

Enumerations

enum  BackoffAlgorithmStatus_t { BackoffAlgorithmSuccess = 0 , BackoffAlgorithmRetriesExhausted }
 Status for BackoffAlgorithm_GetNextBackoff. More...
 

Functions

void BackoffAlgorithm_InitializeParams (BackoffAlgorithmContext_t *pContext, uint16_t backOffBase, uint16_t maxBackOff, uint32_t maxAttempts)
 Initializes the context for using backoff algorithm. The parameters are required for calculating the next retry backoff delay. This function must be called by the application before the first new retry attempt. More...
 
BackoffAlgorithmStatus_t BackoffAlgorithm_GetNextBackoff (BackoffAlgorithmContext_t *pRetryContext, uint32_t randomValue, uint16_t *pNextBackOff)
 Simple exponential backoff and jitter function that provides the delay value for the next retry attempt. After a failure of an operation that needs to be retried, the application should use this function to obtain the backoff delay value for the next retry, and then wait for the backoff time period before retrying the operation. More...
 

Detailed Description

API for calculating backoff period for retry attempts using exponential backoff with jitter algorithm. This library represents the "Full Jitter" backoff strategy explained in the following document. https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/.

Function Documentation

◆ BackoffAlgorithm_InitializeParams()

void BackoffAlgorithm_InitializeParams ( BackoffAlgorithmContext_t pContext,
uint16_t  backOffBase,
uint16_t  maxBackOff,
uint32_t  maxAttempts 
)

Initializes the context for using backoff algorithm. The parameters are required for calculating the next retry backoff delay. This function must be called by the application before the first new retry attempt.

Parameters
[out]pContextThe context to initialize with parameters required for the next backoff delay calculation function.
[in]maxBackOffThe maximum backoff delay (in milliseconds) between consecutive retry attempts.
[in]backOffBaseThe base value (in milliseconds) of backoff delay to use in the exponential backoff and jitter model.
[in]maxAttemptsThe maximum number of retry attempts. Set the value to BACKOFF_ALGORITHM_RETRY_FOREVER to retry for ever.

◆ BackoffAlgorithm_GetNextBackoff()

BackoffAlgorithmStatus_t BackoffAlgorithm_GetNextBackoff ( BackoffAlgorithmContext_t pRetryContext,
uint32_t  randomValue,
uint16_t *  pNextBackOff 
)

Simple exponential backoff and jitter function that provides the delay value for the next retry attempt. After a failure of an operation that needs to be retried, the application should use this function to obtain the backoff delay value for the next retry, and then wait for the backoff time period before retrying the operation.

Parameters
[in,out]pRetryContextStructure containing parameters for the next backoff value calculation.
[in]randomValueThe random value to use for calculation of the backoff period. The random value should be in the range of [0, UINT32_MAX].
[out]pNextBackOffThis will be populated with the backoff value (in milliseconds) for the next retry attempt. The value does not exceed the maximum backoff delay configured in the context.
Note
For generating a random number, it is recommended to use a Random Number Generator that is seeded with a device-specific entropy source so that possibility of collisions between multiple devices retrying the network operations can be mitigated.
Returns
BackoffAlgorithmSuccess after a successful sleep; BackoffAlgorithmRetriesExhausted when all attempts are exhausted.