Add trace events and remove Sonar (#24)

The Sonar integration keeps breaking because they automatically remove projects after a period of inactivity. It adds too little value for the effort required to keep it running, so I am removing it. Newer versions of Clang-Tidy approach Sonar in utility so we will be using only that for now. If the project sees active development in the future again, we may or may not reconsider this.

This PR incorporates the changes from #20.

---------

Co-authored-by: Scott Dixon <[email protected]>

Author: pavel-kirienko

.github/workflows/main.yml

@@ -1,7 +1,7 @@
 name: Main Workflow
 on: [push, pull_request]
 env:
-  LLVM_VERSION: 15
+  LLVM_VERSION: 19
 jobs:
   test:
     if: github.event_name == 'push'
@@ -39,78 +39,12 @@ jobs:
       - working-directory: ${{github.workspace}}/build
         run: make test
 
-  sonarcloud:
-    if: >
-      github.event_name == 'pull_request'                   ||
-      contains(github.ref, '/master')                       ||
-      contains(github.ref, '/release')                      ||
-      contains(github.event.head_commit.message, '#sonar')
-    runs-on: ubuntu-latest
-    env:
-      SONAR_SCANNER_VERSION: 5.0.1.3006
-      SONAR_SERVER_URL: "https://sonarcloud.io"
-      BUILD_WRAPPER_OUT_DIR: build_wrapper_output_directory
-      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
-      CC: gcc
-      CXX: g++
-    steps:
-    - uses: actions/checkout@v4
-      with:
-        fetch-depth: 0
-    - run: sudo apt install g++ g++-multilib gcc-multilib
-    - uses: actions/setup-java@v4
-      with:
-        java-version: 17
-        distribution: zulu
-    - uses: actions/cache@v4
-      with:
-        path: ~/.sonar/cache
-        key: ${{ runner.os }}-sonar
-        restore-keys: ${{ runner.os }}-sonar
-    - name: Download and set up sonar-scanner
-      env:
-        SONAR_SCANNER_DOWNLOAD_URL: https://binaries.sonarsource.com/Distribution/sonar-scanner-cli/sonar-scanner-cli-${{ env.SONAR_SCANNER_VERSION }}-linux.zip
-      run: |
-        mkdir -p $HOME/.sonar
-        curl -sSLo $HOME/.sonar/sonar-scanner.zip ${{ env.SONAR_SCANNER_DOWNLOAD_URL }}
-        unzip -o $HOME/.sonar/sonar-scanner.zip -d $HOME/.sonar/
-        echo "$HOME/.sonar/sonar-scanner-${{ env.SONAR_SCANNER_VERSION }}-linux/bin" >> $GITHUB_PATH
-    - name: Download and set up build-wrapper
-      env:
-        BUILD_WRAPPER_DOWNLOAD_URL: ${{ env.SONAR_SERVER_URL }}/static/cpp/build-wrapper-linux-x86.zip
-      run: |
-        curl -sSLo $HOME/.sonar/build-wrapper-linux-x86.zip ${{ env.BUILD_WRAPPER_DOWNLOAD_URL }}
-        unzip -o $HOME/.sonar/build-wrapper-linux-x86.zip -d $HOME/.sonar/
-        echo "$HOME/.sonar/build-wrapper-linux-x86" >> $GITHUB_PATH
-    # Pass NDEBUG to exclude assert() from coverage; see https://github.com/pavel-kirienko/o1heap/issues/9
-    - name: Run build-wrapper
-      run: |
-        cmake tests -DCMAKE_BUILD_TYPE=Debug -DNO_STATIC_ANALYSIS=1 -DCMAKE_C_FLAGS='-DNDEBUG=1'
-        build-wrapper-linux-x86-64 --out-dir ${{ env.BUILD_WRAPPER_OUT_DIR }} make all
-        make test
-        gcov --preserve-paths --long-file-names $(find CMakeFiles/test_general_cov.dir -name '*.gcno')
-        gcov --preserve-paths --long-file-names $(find CMakeFiles/test_private_cov.dir -name '*.gcno')
-    # https://community.sonarsource.com/t/analyzing-a-header-only-c-library/51468
-    - if: env.SONAR_TOKEN != ''
-      run: >
-        sonar-scanner
-        --define sonar.projectKey="pavel-kirienko_o1heap"
-        --define sonar.organization="pavel-kirienko"
-        --define sonar.sources="o1heap/"
-        --define sonar.sourceEncoding="UTF-8"
-        --define sonar.cfamily.gcov.reportsPath="."
-        --define sonar.cfamily.build-wrapper-output="${{ env.BUILD_WRAPPER_OUT_DIR }}"
-        --define sonar.host.url="${{ env.SONAR_SERVER_URL }}"
-        --define sonar.login=${{ secrets.SONAR_TOKEN }}
-        $([ -z "$GITHUB_BASE_REF" ] && echo "--define sonar.branch.name=${GITHUB_REF##*/}" || true)
-
   style_check:
     if: github.event_name == 'push'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: DoozyX/clang-format-lint-action@v0.15
+      - uses: DoozyX/clang-format-lint-action@v0.20
         with:
           source: './o1heap ./tests'
           exclude: './tests/catch'

README.md

@@ -1,10 +1,8 @@
 # O(1) heap
 
 [![Main Workflow](https://github.com/pavel-kirienko/o1heap/actions/workflows/main.yml/badge.svg)](https://github.com/pavel-kirienko/o1heap/actions/workflows/main.yml)
-[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=pavel-kirienko_o1heap&metric=reliability_rating)](https://sonarcloud.io/dashboard?id=pavel-kirienko_o1heap)
-[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=pavel-kirienko_o1heap&metric=coverage)](https://sonarcloud.io/dashboard?id=pavel-kirienko_o1heap)
 
-O1heap is a highly deterministic constant-complexity memory allocator designed for
+O1Heap is a highly deterministic constant-complexity memory allocator designed for
 hard real-time high-integrity embedded systems.
 The name stands for *O(1) heap*.
 
@@ -45,10 +43,10 @@ This implementation derives from or is based on the ideas presented in:
 - "Worst case fragmentation of first fit and best fit storage allocation strategies" -- J. M. Robson, 1975.
 
 This implementation does not make any non-trivial assumptions about the behavioral properties of the application.
-Per Herter [2014], it can be described as a *predictably bad allocator*:
+Per Herter \[2014], it can be described as a *predictably bad allocator*:
 
 > An allocator that provably performs close to its worst-case memory behavior which, in turn,
-> is better than the worst-case behavior of the allocators discussed [in Herter 2014],
+> is better than the worst-case behavior of the allocators discussed \[in Herter 2014],
 > but much worse than the memory consumption of these for normal programs without (mostly theoretical)
 > bad (de-)allocation sequences.
 
@@ -104,7 +102,7 @@ catastrophic fragmentation cannot occur.
 
 The above-defined theoretical worst-case upper bound H may be prohibitively high for some
 memory-constrained applications.
-It has been shown [Robson 1975] that under a typical workload,
+It has been shown \[Robson 1975] that under a typical workload,
 for a sufficiently high amount of memory available to the allocator which is less than $H$,
 the probability of a (de-)allocation sequence that results in catastrophic fragmentation is low.
 When combined with an acceptable failure probability and a set of adequate assumptions about the behaviors of
@@ -113,7 +111,7 @@ the heap while ensuring a sufficient degree of predictability and reliability.
 The methods of such optimization are outside the scope of this document;
 interested readers are advised to consult with the referred publications.
 
-Following some of the ideas from [Herter 2014], this implementation takes caching-related issues into consideration
+Following some of the ideas from \[Herter 2014], this implementation takes caching-related issues into consideration
 by choosing the most recently used memory fragments to minimize cache misses in the application.
 
 ### Implementation
@@ -238,6 +236,12 @@ If not overridden by the user, for some compilers `O1HEAP_CLZ(x)` will expand to
 For other compilers it will default to a slow software implementation,
 which is likely to significantly degrade the performance of the library.
 
+#### O1HEAP_TRACE
+
+This option is intended for advanced diagnostics and may be not useful in most applications.
+If defined and is nonzero, makes o1heap invoke `extern` trace functions (implemented in the application)
+on every allocation and deallocation. Please refer to `o1heap.h` for usage details.
+
 ## Development
 
 ### Dependencies
@@ -248,15 +252,6 @@ The following tools should be available locally to conduct library development:
 - An AMD64 machine.
 - (optional) Valgrind.
 
-### Conventions
-
-The codebase shall follow the [Zubax C/C++ Coding Conventions](https://kb.zubax.com/x/84Ah).
-Compliance is enforced through the following means:
-
-- Clang-Tidy -- invoked automatically while building the test suite.
-- Clang-Format -- invoked manually as `make format`; enforced in CI/CD automatically.
-- SonarCloud -- invoked by CI/CD automatically.
-
 ### Testing
 
 Please refer to the continuous integration configuration to see how to invoke the tests.
@@ -267,35 +262,33 @@ Update the version number macro in the header file and create a new git tag like
 
 ### MISRA compliance
 
-MISRA compliance is enforced with the help of the following tools:
+MISRA compliance is enforced with the help of:
 
 - Clang-Tidy -- invoked automatically during the normal build process.
-- SonarCloud -- invoked as part of the continuous integration build.
 
 Every intentional deviation shall be documented and justified in-place using the following notation,
 followed by the appropriate static analyser warning suppression statement:
 
 ```c
 // Intentional violation of MISRA: <valid reason here>
-// NOSONAR
-// NOLINT
+// NOLINT(*-specific-rule)
 ```
 
 The list of intentional deviations can be obtained by simply searching the codebase for the above comments.
 
-Do not suppress compliance warnings using the means provided by static analysis tools because such deviations
-are impossible to track at the source code level.
-An exception applies for the case of false-positive (invalid) warnings -- those should not be mentioned in the codebase.
-
 ## Further reading
 
 - [Timing-Predictable Memory Allocation In Hard Real-Time Systems](https://publikationen.sulb.uni-saarland.de/bitstream/20.500.11880/26614/1/diss.pdf), J. Herter, 2014.
 - [Worst case fragmentation of first fit and best fit storage allocation strategies](https://academic.oup.com/comjnl/article/20/3/242/751782), J. M. Robson, 1975.
 - [Dynamic Memory Allocation In SQLite](https://sqlite.org/malloc.html) -- on Robson proof and deterministic fragmentation.
-- *[Russian]* [Динамическая память в системах жёсткого реального времени](https://habr.com/ru/post/486650/) -- issues with dynamic memory allocation in modern embedded RTOS and related popular misconceptions.
+- [Динамическая память в системах жёсткого реального времени](https://habr.com/ru/post/486650/) -- issues with dynamic memory allocation in modern embedded RTOS and related popular misconceptions.
 
 ## Changelog
 
+### Next version WIP
+
+- Add optional trace events, enabled via the `O1HEAP_TRACE` build-time option.
+
 ### v2.1
 
 - Significantly accelerate (de-)allocation by replacing the naïve log2 implementation with fast CLZ intrinsics;

o1heap/o1heap.c

@@ -11,9 +11,11 @@
 // OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
 // OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 //
-// Copyright (c) 2020 Pavel Kirienko
+// Copyright (c) Pavel Kirienko
 // Authors: Pavel Kirienko <[email protected]>
 
+// ReSharper disable CppDFANullDereference
+
 #include "o1heap.h"
 #include <assert.h>
 #include <limits.h>
@@ -79,6 +81,20 @@ O1HEAP_PRIVATE uint_fast8_t O1HEAP_CLZ(const size_t x)
 }
 #endif
 
+/// If O1HEAP_TRACE is defined and is nonzero, trace tools can get events when o1heap memory is allocated or freed.
+/// The corresponding events are delivered by invoking extern functions o1heapTraceAllocate() etc, defined in the
+/// application. Please refer to the documentation for those functions for the additional information.
+#ifndef O1HEAP_TRACE
+#    define O1HEAP_TRACE 0
+#endif
+#if O1HEAP_TRACE
+#    define O1HEAP_TRACE_ALLOCATE(handle, pointer, size) o1heapTraceAllocate(handle, pointer, size)
+#    define O1HEAP_TRACE_FREE(handle, pointer, size) o1heapTraceFree(handle, pointer, size)
+#else
+#    define O1HEAP_TRACE_ALLOCATE(handle, pointer, size) (void) 0
+#    define O1HEAP_TRACE_FREE(handle, pointer, size) (void) 0
+#endif
+
 // ---------------------------------------- INTERNAL DEFINITIONS ----------------------------------------
 
 #if !defined(__STDC_VERSION__) || (__STDC_VERSION__ < 199901L)
@@ -365,8 +381,17 @@ void* o1heapAllocate(O1HeapInstance* const handle, const size_t amount)
             frag->header.used = true;
 
             out = ((char*) frag) + O1HEAP_ALIGNMENT;
+            O1HEAP_TRACE_ALLOCATE(handle, out, frag->header.size);
+        }
+        else
+        {
+            O1HEAP_TRACE_ALLOCATE(handle, out, amount);
         }
     }
+    else
+    {
+        O1HEAP_TRACE_ALLOCATE(handle, out, amount);
+    }
 
     // Update the diagnostics.
     if (O1HEAP_LIKELY(handle->diagnostics.peak_request_size < amount))
@@ -401,6 +426,8 @@ void o1heapFree(O1HeapInstance* const handle, void* const pointer)
         O1HEAP_ASSERT(frag->header.size <= handle->diagnostics.capacity);
         O1HEAP_ASSERT((frag->header.size % FRAGMENT_SIZE_MIN) == 0U);
 
+        O1HEAP_TRACE_FREE(handle, pointer, frag->header.size);
+
         // Even if we're going to drop the fragment later, mark it free anyway to prevent double-free.
         frag->header.used = false;
 

o1heap/o1heap.h

@@ -11,7 +11,7 @@
 // OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
 // OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 //
-// Copyright (c) 2020 Pavel Kirienko
+// Copyright (c) Pavel Kirienko
 // Authors: Pavel Kirienko <[email protected]>
 //
 // READ THE DOCUMENTATION IN README.md.
@@ -116,6 +116,19 @@ bool o1heapDoInvariantsHold(const O1HeapInstance* const handle);
 /// If the handle pointer is NULL, the behavior is undefined.
 O1HeapDiagnostics o1heapGetDiagnostics(const O1HeapInstance* const handle);
 
+/// Advanced diagnostic hooks; not used by default.
+/// If O1HEAP_TRACE is not defined or is zero, these functions should be left unimplemented.
+/// Iff O1HEAP_TRACE is defined and is nonzero, the library will emit trace events by invoking these functions,
+/// which are to be defined in the application (or linking will fail).
+///
+/// For allocations, note that if the allocated memory pointer is NULL, an allocation failure has occurred.
+/// In this case, the size reported is the number of bytes requested that the allocator could not provide.
+///
+/// When using the pointer provided via o1heapTraceFree(), the pointer memory must not be accessed.
+/// This pointer should only be used for its address.
+extern void o1heapTraceAllocate(O1HeapInstance* const handle, void* const allocated_memory, size_t size);
+extern void o1heapTraceFree(O1HeapInstance* const handle, void* const freed_memory, size_t size);
+
 #ifdef __cplusplus
 }
 #endif

tests/CMakeLists.txt

@@ -25,9 +25,9 @@ endif ()
 
 set(library_dir "${CMAKE_SOURCE_DIR}/../o1heap")
 
-# Use -DNO_STATIC_ANALYSIS=1 to suppress static analysis.
-# If not suppressed, the tools used here shall be available, otherwise the build will fail.
-if (NOT NO_STATIC_ANALYSIS)
+# clang-tidy
+set(DISABLE_CLANG_TIDY OFF CACHE BOOL "Do not use Clang-Tidy")
+if (NOT DISABLE_CLANG_TIDY)
     # clang-tidy (separate config files per directory)
     find_program(clang_tidy NAMES clang-tidy)
     if (NOT clang_tidy)
@@ -99,3 +99,4 @@ gen_test_matrix(
         test_general.cpp
         ""
 )
+gen_test("test_general_c11_x32_trc" "test_general.cpp" "O1HEAP_TRACE=1" c_std_11 "-m32" "-m32")

tests/test_general.cpp

@@ -603,3 +603,21 @@ TEST_CASE("General: invariant checker")
     dg.oom_count++;
     REQUIRE(heap->doInvariantsHold());
 }
+
+extern "C" void o1heapTraceAllocate(O1HeapInstance* const handle, void* const allocated_memory, size_t size)
+{
+    REQUIRE(handle != nullptr);
+    const auto* const h = reinterpret_cast<internal::O1HeapInstance*>(handle);
+    h->validate();
+    (void) allocated_memory;
+    (void) size;
+}
+
+extern "C" void o1heapTraceFree(O1HeapInstance* const handle, void* const freed_memory, size_t size)
+{
+    REQUIRE(handle != nullptr);
+    const auto* const h = reinterpret_cast<internal::O1HeapInstance*>(handle);
+    h->validate();
+    (void) freed_memory;
+    (void) size;
+}