/**
@mainpage Overview
@anchor BackOff Algorithm
@brief backoffAlgorithm Library

<p>
A library that calculates the back-off period for a retry attempt using exponential back-off with jitter algorithm.
This library uses the "Full Jitter" strategy for the exponential back-off with jitter algorithm.

More information about the algorithm can be seen in the [Exponential Backoff and Jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) AWS blog.

Exponential backoff with jitter is typically used when retrying a failed network
connection or operation request with the server. An exponential backoff with jitter helps to
mitigate failed network operations with servers, that are caused due to network congestion or high request load on
the server, by spreading out retry requests across multiple devices attempting network operations.
Besides, in an environment with poor connectivity, a client can get disconnected at any time.
A backoff strategy helps the client to conserve battery by not repeatedly attempting reconnections when they are
unlikely to succeed.

Before retrying the failed communication to the server, there is a delay period.
In this delay period, the task that is retrying must sleep for some random amount
of milliseconds between 0 and the lesser of the backoff window (related to the retry attempt)
and a predefined maximum delay value. The backoff window is doubled with each retry
attempt until the maximum delay value is reached.<br>

> sleep_ms = random_between( 0, min( 2<sup>attempts_count</sup> * base_ms, maximum_ms ) )

The library is written in C and designed to be compliant with ISO C90 and MISRA C:2012.

For a reference example of using the library, refer to the related README section in the repository [here](https://github.com/FreeRTOS/backoffAlgorithm#reference-example).

</p>

@section backoff_algorithm_memory_requirements Memory Requirements
@brief Memory requirements of the backoffAlgorithm library.

<table>
    <tr>
        <td colspan="4"><center><b>Code size (in bytes) of backoffAlgorithm library files (sizes generated with [GCC for ARM Cortex-M toolchain](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads/9-2020-q2-update))</b></center></td>
    </tr>
    <tr>
        <td><b>File</b></td>
        <td><b>No Optimization (asserts enabled)</b></td>
        <td><b>With -O1 Optimization (asserts disabled)</b></td>
        <td><b>With -Os Optimization (asserts disabled)</b></td>
    </tr>
    <tr>
        <td>backoff_algorithm.c</td>
        <td>678</td>
        <td>140</td>
        <td>136</td>
    </tr>
</table>

@section backoff_algorithm_design Design
@brief backoffAlgorithm Library Design

<h3>Memory Usage</h3>
<p>
All functions in the backoffAlgorithm library operate only on the buffer provided and use only
local variables on the stack.
</p>

<h3>Random Number Generation</h3>
<p>
The library takes a random number each time it calculates the backoff period value for the
retry attempt. To avoid calculation of the same random numbers across your fleet of devices
attempting retry of network operations, it is RECOMMENDED to generate the random number with
a random number generator that is seeded with an entropy source unique to the device.
</p>

<h3>Compliance & Coverage</h3>
<p>
The backoffAlgorithm library is designed to be compliant with ISO C90 and MISRA C:2012.
All functions are written to have minimal complexity. Unit tests are written to cover
every path of execution and achieve 100% branch coverage.
</p>
*/

/**
@page backoff_algorithm_functions Functions
@brief Primary functions of the backoffAlgorithm library:<br><br>
@subpage define_backoffalgorithm_initializeparams <br>
@subpage define_backoffalgorithm_getnextbackoff <br>

@page define_backoffalgorithm_initializeparams BackoffAlgorithm_InitializeParams
@snippet backoff_algorithm.h define_backoffalgorithm_initializeparams
@copydoc BackoffAlgorithm_InitializeParams

@page define_backoffalgorithm_getnextbackoff BackoffAlgorithm_GetNextBackoff
@snippet backoff_algorithm.h define_backoffalgorithm_getnextbackoff
@copydoc BackoffAlgorithm_GetNextBackoff
*/

<!-- We do not use doxygen ALIASes here because there have been issues in the past versions with "^^" newlines within the alias definition. -->

/**
@defgroup backoff_algorithm_struct_types Parameter Structure
@brief Structure passed as parameter to [backoffAlgorithm library functions](@ref backoff_algorithm_functions)
*/

/**
@defgroup backoff_algorithm_enum_types Enumerated Types
@brief Enumerated types of the backoffAlgorithm library
*/

/**
@defgroup backoff_algorithm_constants Constants
@brief Constants defined in the backoffAlgorithm library
*/