backoffAlgorithm  v1.1.0
Algorithmic library for calculating retry intervals using exponential backoff and jitter.
backoff_algorithm.h
Go to the documentation of this file.
1 /*
2  * backoffAlgorithm v1.1.0
3  * Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
4  *
5  * Permission is hereby granted, free of charge, to any person obtaining a copy of
6  * this software and associated documentation files (the "Software"), to deal in
7  * the Software without restriction, including without limitation the rights to
8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
9  * the Software, and to permit persons to whom the Software is furnished to do so,
10  * subject to the following conditions:
11  *
12  * The above copyright notice and this permission notice shall be included in all
13  * copies or substantial portions of the Software.
14  *
15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
17  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
18  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
19  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
20  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21  */
22 
33 #ifndef BACKOFF_ALGORITHM_H_
34 #define BACKOFF_ALGORITHM_H_
35 
36 /* Standard include. */
37 #include <stdint.h>
38 
39 /* *INDENT-OFF* */
40 #ifdef __cplusplus
41  extern "C" {
42 #endif
43 /* *INDENT-ON* */
44 
49 #define BACKOFF_ALGORITHM_RETRY_FOREVER ( UINT32_MAX )
50 
55 typedef enum BackoffAlgorithmStatus
56 {
60 
66 typedef struct BackoffAlgorithmContext
67 {
71  uint16_t maxBackoffDelay;
72 
77  uint32_t attemptsDone;
78 
82  uint16_t nextJitterMax;
83 
87  uint32_t maxRetryAttempts;
89 
104 /* @[define_backoffalgorithm_initializeparams] */
106  uint16_t backOffBase,
107  uint16_t maxBackOff,
108  uint32_t maxAttempts );
109 /* @[define_backoffalgorithm_initializeparams] */
110 
133 /* @[define_backoffalgorithm_getnextbackoff] */
135  uint32_t randomValue,
136  uint16_t * pNextBackOff );
137 /* @[define_backoffalgorithm_getnextbackoff] */
138 
139 /* *INDENT-OFF* */
140 #ifdef __cplusplus
141  }
142 #endif
143 /* *INDENT-ON* */
144 
145 #endif /* ifndef BACKOFF_ALGORITHM_H_ */
BackoffAlgorithmContext_t::maxRetryAttempts
uint32_t maxRetryAttempts
The maximum number of retry attempts.
Definition: backoff_algorithm.h:87
BackoffAlgorithmContext_t::maxBackoffDelay
uint16_t maxBackoffDelay
The maximum backoff delay (in milliseconds) between consecutive retry attempts.
Definition: backoff_algorithm.h:71
BackoffAlgorithmContext_t
Represents parameters required for calculating the back-off delay for the next retry attempt.
Definition: backoff_algorithm.h:67
BackoffAlgorithmStatus_t
BackoffAlgorithmStatus_t
Status for BackoffAlgorithm_GetNextBackoff.
Definition: backoff_algorithm.h:56
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 ...
Definition: backoff_algorithm.c:84
BackoffAlgorithmRetriesExhausted
@ BackoffAlgorithmRetriesExhausted
The function exhausted all retry attempts.
Definition: backoff_algorithm.h:58
BackoffAlgorithmContext_t::nextJitterMax
uint16_t nextJitterMax
The maximum backoff value (in milliseconds) for the next retry attempt.
Definition: backoff_algorithm.h:82
BackoffAlgorithmSuccess
@ BackoffAlgorithmSuccess
The function successfully calculated the next back-off value.
Definition: backoff_algorithm.h:57
BackoffAlgorithmContext_t::attemptsDone
uint32_t attemptsDone
The total number of retry attempts completed. This value is incremented on every call to BackoffAlgor...
Definition: backoff_algorithm.h:77
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 attem...
Definition: backoff_algorithm.c:38