Add mechanism to validate code example

.github/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
  cmake -S test -B build/ \
  -G "Unix Makefiles" \
  -DCMAKE_BUILD_TYPE=Debug \
- -DBUILD_CLONE_SUBMODULES=ON \
+ -DBUILD_UNIT_TESTS=ON \
  -DCMAKE_C_FLAGS='--coverage -Wall -Wextra -Werror'
  make -C build/ all
  - name: Test
@@ -35,6 +35,15 @@ jobs:
  uses: FreeRTOS/CI-CD-Github-Actions/coverage-cop@main
  with:
  path: ./build/coverage.info
+ build-code-example:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Clone This Repo
+ uses: actions/checkout@v2
+ - name: Build code example
+ run: |
+ cmake -S test -b Build -DBUILD_CODE_EXAMPLE=ON
+ make -C build code_example_posix -j8
  complexity:
  runs-on: ubuntu-latest
  steps:

docs/doxygen/code_examples/backoff_algorithm_posix.c

@@ -0,0 +1,84 @@
+#include "backoff_algorithm.h"
+#include <stdlib.h>
+#include <string.h>
+#include <netdb.h>
+#include <unistd.h>
+#include <time.h>
+
+/* The maximum number of retries for the example code. */
+#define RETRY_MAX_ATTEMPTS ( 5U )
+
+/* The maximum back-off delay (in milliseconds) for between retries in the example. */
+#define RETRY_MAX_BACKOFF_DELAY_MS ( 5000U )
+
+/* The base back-off delay (in milliseconds) for retry configuration in the example. */
+#define RETRY_BACKOFF_BASE_MS ( 500U )
+
+int main()
+{
+ /* @[code_example_backoffalgorithm_initializeparams] */
+ /* Variables used in this example. */
+ BackoffAlgorithmStatus_t retryStatus = BackoffAlgorithmSuccess;
+ BackoffAlgorithmContext_t retryParams;
+ char serverAddress[] = "amazon.com";
+ uint16_t nextRetryBackoff = 0;
+
+ /* Initialize reconnect attempts and interval. */
+ BackoffAlgorithm_InitializeParams( &retryParams,
+ RETRY_BACKOFF_BASE_MS,
+ RETRY_MAX_BACKOFF_DELAY_MS,
+ RETRY_MAX_ATTEMPTS );
+ /* @[code_example_backoffalgorithm_initializeparams] */
+
+ int32_t dnsStatus = -1;
+ struct addrinfo hints;
+ struct addrinfo ** pListHead = NULL;
+ struct timespec tp;
+
+ /* Add hints to retrieve only TCP sockets in getaddrinfo. */
+ ( void ) memset( &hints, 0, sizeof( hints ) );
+
+ /* Address family of either IPv4 or IPv6. */
+ hints.ai_family = AF_UNSPEC;
+ /* TCP Socket. */
+ hints.ai_socktype = ( int32_t ) SOCK_STREAM;
+ hints.ai_protocol = IPPROTO_TCP;
+
+ /* @[code_example_backoffalgorithm_getnextbackoff] */
+
+ /* Seed the pseudo random number generator used in this example (with call to
+ * rand() function provided by ISO C standard library) for use in backoff period
+ * calculation when retrying failed DNS resolution. */
+
+ /* Get current time to seed pseudo random number generator. */
+ ( void ) clock_gettime( CLOCK_REALTIME, &tp );
+ /* Seed pseudo random number generator with seconds. */
+ srand( tp.tv_sec );
+
+ do
+ {
+ /* Perform a DNS lookup on the given host name. */
+ dnsStatus = getaddrinfo( serverAddress, NULL, &hints, pListHead );
+
+ /* Retry if DNS resolution query failed. */
+ if( dnsStatus != 0 )
+ {
+ /* Generate a random number and get back-off value (in milliseconds) for the next retry.
+ * Note: It is recommended to use a random number generator that is seeded with
+ * device-specific entropy source so that backoff calculation across devices is different
+ * and possibility of network collision between devices attempting retries can be avoided.
+ *
+ * For the simplicity of this code example, the pseudo random number generator, rand()
+ * function is used. */
+ retryStatus = BackoffAlgorithm_GetNextBackoff( &retryParams, rand(), &nextRetryBackoff );
+
+ /* Wait for the calculated backoff period before the next retry attempt of querying DNS.
+ * As usleep() takes nanoseconds as the parameter, we multiply the backoff period by 1000. */
+ ( void ) usleep( nextRetryBackoff * 1000U );
+ }
+ } while( ( dnsStatus != 0 ) && ( retryStatus != BackoffAlgorithmRetriesExhausted ) );
+
+ /* @[code_example_backoffalgorithm_getnextbackoff] */
+
+ return dnsStatus;
+}

docs/doxygen/config.doxyfile

@@ -797,7 +797,7 @@ EXCLUDE_SYMLINKS = NO
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH = source/include docs/doxygen/include
+EXAMPLE_PATH = source/include docs/doxygen/include docs/doxygen/code_examples
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and

docs/doxygen/pages.dox

@@ -61,19 +61,34 @@ every path of execution and achieve 100% branch coverage.
 </p>
 */
 
+/**
+@page backoff_algorithm_example Code Example of backoffAlgorithm API
+@brief Example POSIX application of retrying DNS resolution operation with exponential backoff-and-jitter with the backoffAlgorithm library.
+
+@include backoff_algorithm_posix.c 
+ */
+
 /**
 @page backoff_algorithm_functions Functions
 @brief Primary functions of the backoffAlgorithm library:<br><br>
 @subpage define_backoffalgorithm_initializeparams <br>
 @subpage define_backoffalgorithm_getnextbackoff <br>
 
+<b>For a code example </b> of using backoffAlgorithm library for retrying operation with exponential back-off and jitter, refer to @ref backoff_algorithm_example.
+
 @page define_backoffalgorithm_initializeparams BackoffAlgorithm_InitializeParams
 @snippet backoff_algorithm.h define_backoffalgorithm_initializeparams
 @copydoc BackoffAlgorithm_InitializeParams
 
+From the @ref backoff_algorithm_example, following is the part relevant to the @ref BackoffAlgorithm_InitializeParams API.
+@snippet backoff_algorithm_posix.c code_example_backoffalgorithm_initializeparams
+
 @page define_backoffalgorithm_getnextbackoff BackoffAlgorithm_GetNextBackoff
-@snippet backoff_algorithm.h define_backoffalgorithm_getnextbackoff
 @copydoc BackoffAlgorithm_GetNextBackoff
+
+From the @ref backoff_algorithm_example, following is the part relevant to the @ref BackoffAlgorithm_GetNextBackoff API.
+@snippet backoff_algorithm_posix.c code_example_backoffalgorithm_getnextbackoff
+
 */
 
 <!-- We do not use doxygen ALIASes here because there have been issues in the past versions with "^^" newlines within the alias definition. -->