Skip to content

Commit 8498cbb

Browse files
aggarw13aggarw13
authored
Refactor directory structure, enable unit tests and update README (#1)
1 parent d59dc99 commit 8498cbb

11 files changed

+418
-1
lines changed

‎.gitmodules

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
[submodule "test/unit-test/Unity"]
2+
path = test/unit-test/Unity
3+
url = https://github.com/ThrowTheSwitch/Unity
4+
update = none

‎README.md

+132
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,135 @@ This repository contains the backoffAlgorithm library, a utility library to calc
55
This library supports the "Full Jitter" algorithm for exponential back-off with jitter.
66
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.
77

8+
## Reference example
9+
10+
The example below shows how to use the backoffAlgorithm library to retry a DNS resolution query for `amazon.com`.
11+
12+
```c
13+
#include "retry_utils.h"
14+
#include <stdlib.h>
15+
#include <string.h>
16+
#include <netdb.h>
17+
18+
/* The maximum number of retries for the example code. */
19+
#define RETRY_MAX_ATTEMPTS ( 5U )
20+
21+
/* The maximum back-off delay (in milliseconds) for between retries in the example. */
22+
#define RETRY_MAX_BACKOFF_DELAY_MS ( 5000U )
23+
24+
/* The base back-off delay (in milliseconds) for retry configuration in the example. */
25+
#define RETRY_BACKOFF_BASE_MS ( 500U )
26+
27+
/**
28+
* A random number generator to provide to the backoffAlgorithm
29+
* library.
30+
*
31+
* This function is used in the exponential backoff with jitter algorithm
32+
* to calculate the backoff value for the next retry attempt.
33+
*
34+
* It is recommended to either use a True Random Number Generator (TRNG) for
35+
* calculation of unique back-off values in devices so that collision between
36+
* devices attempting retries at the same intervals can be avoided.
37+
*
38+
* For the simplicity of the code example, this function is a pseudo
39+
* random number generator.
40+
*
41+
* @return The generated random number. This example function ALWAYS succeeds
42+
* in generating a random number.
43+
*/
44+
static int32_t pseudoRng()
45+
{
46+
return( rand() % ( INT32_MAX ) );
47+
}
48+
49+
int main()
50+
{
51+
/* Variables used in this example. */
52+
RetryUtilsStatus_t retryStatus = RetryUtilsSuccess;
53+
RetryUtilsContext_t retryParams;
54+
char serverAddress[] = "amazon.com";
55+
uint16_t nextRetryBackOff = 0;
56+
57+
int32_t dnsStatus = -1;
58+
struct addrinfo hints;
59+
struct addrinfo ** pListHead;
60+
61+
/* Add hints to retrieve only TCP sockets in getaddrinfo. */
62+
( void ) memset( &hints, 0, sizeof( hints ) );
63+
64+
/* Address family of either IPv4 or IPv6. */
65+
hints.ai_family = AF_UNSPEC;
66+
/* TCP Socket. */
67+
hints.ai_socktype = ( int32_t ) SOCK_STREAM;
68+
hints.ai_protocol = IPPROTO_TCP;
69+
70+
/* Initialize reconnect attempts and interval. */
71+
RetryUtils_InitializeParams( &retryParams,
72+
RETRY_BACKOFF_BASE_MS,
73+
RETRY_MAX_BACKOFF_DELAY_MS,
74+
RETRY_MAX_ATTEMPTS,
75+
pseudoRng );
76+
77+
do
78+
{
79+
/* Perform a DNS lookup on the given host name. */
80+
dnsStatus = getaddrinfo( serverAddress, NULL, &hints, pListHead );
81+
82+
/* Retry if DNS resolution query failed. */
83+
if( dnsStatus != 0 )
84+
{
85+
/* Get back-off value (in milliseconds) for the next retry. */
86+
retryStatus = RetryUtils_GetNextBackOff( &retryParams, &nextRetryBackOff );
87+
}
88+
} while( ( dnsStatus != 0 ) && ( retryStatus != RetryUtilsRetriesExhausted ) );
89+
90+
return dnsStatus;
91+
}
92+
```
93+
94+
## Building the library
95+
96+
A compiler that supports **C89 or later** such as *gcc* is required to build the library.
97+
98+
For instance, if the example above is copied to a file named `example.c`, *gcc* can be used like so:
99+
```bash
100+
gcc -I source/include example.c source/retry_utils.c -o example
101+
./example
102+
```
103+
104+
*gcc* can also produce an output file to be linked:
105+
```bash
106+
gcc -I source/include -c source/retry_utils.c
107+
```
108+
109+
## Building unit tests
110+
111+
### Checkout Unity Submodule
112+
By default, the submodules in this repository are configured with `update=none` in [.gitmodules](.gitmodules), to avoid increasing clone time and disk space usage of other repositories (like [amazon-freertos](https://github.com/aws/amazon-freertos) that submodules this repository).
113+
114+
To build unit tests, the submodule dependency of Unity is required. Use the following command to clone the submodule:
115+
```
116+
git submodule update --checkout --init --recursive --test/unit-test/Unity
117+
```
118+
119+
### Platform Prerequisites
120+
121+
- For running unit tests
122+
- C90 compiler like gcc
123+
- CMake 3.13.0 or later
124+
- Ruby 2.0.0 or later is additionally required for the Unity test framework (that we use).
125+
- For running the coverage target, gcov is additionally required.
126+
127+
### Steps to build Unit Tests
128+
129+
1. Go to the root directory of this repository. (Make sure that the **Unity** submodule is cloned as described [above](#checkout-unity-submodule).)
130+
131+
1. Create build directory: `mkdir build && cd build`
132+
133+
1. Run *cmake* while inside build directory: `cmake -S ../test`
134+
135+
1. Run this command to build the library and unit tests: `make all`
136+
137+
1. The generated test executables will be present in `build/bin/tests` folder.
138+
139+
1. Run `ctest` to execute all tests and view the test run summary.

‎retryUtilsFilePaths.cmake ‎backoffAlgorithmFilePaths.cmake

File renamed without changes.

‎test/CMakeLists.txt

+87
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
cmake_minimum_required( VERSION 3.13.0 )
2+
project( "backoffAlgorithm unit test"
3+
VERSION 1.0.0
4+
LANGUAGES C )
5+
6+
# Allow the project to be organized into folders.
7+
set_property( GLOBAL PROPERTY USE_FOLDERS ON )
8+
9+
# Use C90.
10+
set( CMAKE_C_STANDARD 90 )
11+
set( CMAKE_C_STANDARD_REQUIRED ON )
12+
13+
# Do not allow in-source build.
14+
if( ${PROJECT_SOURCE_DIR} STREQUAL ${PROJECT_BINARY_DIR} )
15+
message( FATAL_ERROR "In-source build is not allowed. Please build in a separate directory, such as ${PROJECT_SOURCE_DIR}/build." )
16+
endif()
17+
18+
# Set global path variables.
19+
get_filename_component(__MODULE_ROOT_DIR "${CMAKE_CURRENT_LIST_DIR}/.." ABSOLUTE)
20+
set( MODULE_ROOT_DIR ${__MODULE_ROOT_DIR} CACHE INTERNAL "backoffAlgorithm source root." )
21+
set( UNIT_TEST_DIR ${MODULE_ROOT_DIR}/test/unit-test CACHE INTERNAL "backoffAlgorithm unit test directory." )
22+
set( UNITY_DIR ${UNIT_TEST_DIR}/Unity CACHE INTERNAL "Unity library source directory." )
23+
24+
# Configure options to always show in CMake GUI.
25+
option( BUILD_CLONE_SUBMODULES
26+
"Set this to ON to automatically clone any required Git submodules. When OFF, submodules must be manually cloned."
27+
OFF )
28+
29+
# Set output directories.
30+
set( CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin )
31+
set( CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib )
32+
set( CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib )
33+
34+
# ================================ Coverity Analysis Configuration =================================
35+
36+
# Include filepaths for source and include.
37+
include( ${MODULE_ROOT_DIR}/backoffAlgorithmFilePaths.cmake )
38+
39+
# Target for Coverity analysis that builds the library.
40+
add_library( coverity_analysis
41+
${RETRY_UTILS_SOURCES} )
42+
43+
# Backoff Algorithm library public include path.
44+
target_include_directories( coverity_analysis
45+
PUBLIC
46+
${RETRY_UTILS_INCLUDE_PUBLIC_DIRS} )
47+
48+
# ==================================== Unit Test Configuration ====================================
49+
50+
# Include Unity build configuration.
51+
include( unit-test/unity_build.cmake )
52+
53+
# Check if the Unity source directory exists, and if not present, clone the submodule
54+
# if BUILD_CLONE_SUBMODULES configuration is enabled.
55+
if( NOT EXISTS ${UNITY_DIR}/src )
56+
# Attempt to clone Unity.
57+
if( ${BUILD_CLONE_SUBMODULES} )
58+
clone_unity()
59+
else()
60+
message( FATAL_ERROR "The required submodule Unity does not exist. Either clone it manually, or set BUILD_CLONE_SUBMODULES to 1 to automatically clone it during build." )
61+
endif()
62+
endif()
63+
64+
# Add unit test and coverage configuration.
65+
66+
# Use CTest utility for managing test runs. This has to be added BEFORE
67+
# defining test targets with add_test()
68+
enable_testing()
69+
70+
# Add build targets for Unity and Unit, required for unit testing.
71+
add_unity_targets()
72+
73+
# Add function to enable Unity based tests and coverage.
74+
include( ${MODULE_ROOT_DIR}/tools/unity/create_test.cmake )
75+
76+
# Include build configuration for unit tests.
77+
add_subdirectory( unit-test )
78+
79+
# ==================================== Coverage Analysis configuration ============================
80+
81+
# Add a target for running coverage on tests.
82+
add_custom_target( coverage
83+
COMMAND ${CMAKE_COMMAND} -DUNITY_DIR=${UNITY_DIR}
84+
-P ${MODULE_ROOT_DIR}/tools/unity/coverage.cmake
85+
DEPENDS unity retry_utils_utest
86+
WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
87+
)

‎utest/CMakeLists.txt ‎test/unit-test/CMakeLists.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# Include file path configuration for retry utils library.
2-
include(../retryUtilsFilePaths.cmake)
2+
include(${MODULE_ROOT_DIR}/backoffAlgorithmFilePaths.cmake)
33

44
project ("retry utils unit test")
55
cmake_minimum_required (VERSION 3.2.0)

‎test/unit-test/Unity

Submodule Unity added at 386c540

‎utest/retry_utils_utest.c ‎test/unit-test/retry_utils_utest.c

File renamed without changes.

‎test/unit-test/unity_build.cmake

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Macro utility to clone the Unity submodule.
2+
macro( clone_unity )
3+
find_package( Git REQUIRED )
4+
message( "Cloning submodule Unity." )
5+
execute_process( COMMAND rm -rf ${UNITY_DIR}
6+
COMMAND ${GIT_EXECUTABLE} submodule update --checkout --init --recursive ${UNITY_DIR}
7+
WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
8+
RESULT_VARIABLE UNITY_CLONE_RESULT )
9+
10+
if( NOT ${UNITY_CLONE_RESULT} STREQUAL "0" )
11+
message( FATAL_ERROR "Failed to clone Unity submodule." )
12+
endif()
13+
endmacro()
14+
15+
# Macro utility to add library targets for Unity and Unity to build configuration.
16+
macro( add_unity_targets )
17+
# Build Configuration for Unity and Unity libraries.
18+
list( APPEND UNITY_INCLUDE_DIRS
19+
"${UNITY_DIR}/src/"
20+
"${UNITY_DIR}/extras/fixture/src"
21+
"${UNITY_DIR}/extras/memory/src"
22+
)
23+
24+
add_library( unity STATIC
25+
"${UNITY_DIR}/src/unity.c"
26+
"${UNITY_DIR}/extras/fixture/src/unity_fixture.c"
27+
"${UNITY_DIR}/extras/memory/src/unity_memory.c"
28+
)
29+
30+
set_target_properties( unity PROPERTIES
31+
ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib
32+
POSITION_INDEPENDENT_CODE ON
33+
)
34+
35+
target_include_directories( unity PUBLIC
36+
${UNITY_INCLUDE_DIRS}
37+
)
38+
endmacro()

‎tools/unity/coverage.cmake

+70
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Taken from amazon-freertos repository
2+
cmake_minimum_required(VERSION 3.13)
3+
set(BINARY_DIR ${CMAKE_BINARY_DIR})
4+
# reset coverage counters
5+
execute_process(
6+
COMMAND lcov --directory ${CMAKE_BINARY_DIR}
7+
--base-directory ${CMAKE_BINARY_DIR}
8+
--zerocounters
9+
10+
COMMAND mkdir -p ${CMAKE_BINARY_DIR}/coverage
11+
)
12+
# make the initial/baseline capture a zeroed out files
13+
execute_process( COMMAND lcov --directory ${CMAKE_BINARY_DIR}
14+
--base-directory ${CMAKE_BINARY_DIR}
15+
--initial
16+
--capture
17+
--rc lcov_branch_coverage=1
18+
--rc genhtml_branch_coverage=1
19+
--output-file=${CMAKE_BINARY_DIR}/base_coverage.info
20+
)
21+
file(GLOB files "${CMAKE_BINARY_DIR}/bin/tests/*")
22+
23+
set(REPORT_FILE ${CMAKE_BINARY_DIR}/utest_report.txt)
24+
file(WRITE ${REPORT_FILE} "")
25+
# execute all files in bin directory, gathering the output to show it in CI
26+
foreach(testname ${files})
27+
get_filename_component(test
28+
${testname}
29+
NAME_WLE
30+
)
31+
message("Running ${testname}")
32+
execute_process(COMMAND ${testname} OUTPUT_FILE ${CMAKE_BINARY_DIR}/${test}_out.txt)
33+
34+
file(READ ${CMAKE_BINARY_DIR}/${test}_out.txt CONTENTS)
35+
file(APPEND ${REPORT_FILE} "${CONTENTS}")
36+
endforeach()
37+
38+
# generate Junit style xml output
39+
execute_process(COMMAND ruby
40+
${UNITY_DIR}/auto/parse_output.rb
41+
-xml ${REPORT_FILE}
42+
WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
43+
)
44+
45+
# capture data after running the tests
46+
execute_process(
47+
COMMAND lcov --capture
48+
--rc lcov_branch_coverage=1
49+
--rc genhtml_branch_coverage=1
50+
--base-directory ${CMAKE_BINARY_DIR}
51+
--directory ${CMAKE_BINARY_DIR}
52+
--output-file ${CMAKE_BINARY_DIR}/second_coverage.info
53+
)
54+
55+
# combile baseline results (zeros) with the one after running the tests
56+
execute_process(
57+
COMMAND lcov --base-directory ${CMAKE_BINARY_DIR}
58+
--directory ${CMAKE_BINARY_DIR}
59+
--add-tracefile ${CMAKE_BINARY_DIR}/base_coverage.info
60+
--add-tracefile ${CMAKE_BINARY_DIR}/second_coverage.info
61+
--output-file ${CMAKE_BINARY_DIR}/coverage.info
62+
--no-external
63+
--rc lcov_branch_coverage=1
64+
)
65+
execute_process(
66+
COMMAND genhtml --rc lcov_branch_coverage=1
67+
--branch-coverage
68+
--output-directory ${CMAKE_BINARY_DIR}/coverage
69+
${CMAKE_BINARY_DIR}/coverage.info
70+
)

0 commit comments

Comments
 (0)