feat: add core foundation benchmarking support

CMakeLists.txt

@@ -22,6 +22,7 @@ include(CTest)
 include(cmake/LaghuCapabilities.cmake)
 include(cmake/LaghuDependencyDag.cmake)
 include(cmake/LaghuApiBoundaries.cmake)
+include(cmake/LaghuBenchmarks.cmake)
 include(cmake/LaghuDependencies.cmake)
 include(cmake/LaghuFeatures.cmake)
 include(cmake/LaghuFuzzing.cmake)
@@ -44,6 +45,7 @@ laghu_configure_dependency_registry()
 laghu_configure_dependency_modes()
 laghu_configure_capability_header()
 laghu_configure_build_identity()
+laghu_configure_benchmarks()
 
 add_library(laghu_core STATIC
   src/core/clocks.cpp
@@ -104,6 +106,8 @@ if(CMAKE_CXX_COMPILER_ID MATCHES "Clang")
     PROPERTIES COMPILE_OPTIONS -Wno-unsafe-buffer-usage)
 endif()
 
+laghu_add_benchmark_targets()
+
 laghu_declare_subsystem_graph()
 laghu_configure_api_boundaries()
 laghu_apply_first_party_contract(laghu_os)
@@ -305,6 +309,7 @@ set_property(TARGET visibility_negative_fixture PROPERTY CXX_VISIBILITY_PRESET h
 set_property(TARGET visibility_negative_fixture PROPERTY VISIBILITY_INLINES_HIDDEN YES)
 
 laghu_add_validation_tests()
+laghu_add_benchmark_validation_tests()
 laghu_add_static_analysis_validation_tests()
 laghu_add_static_analysis_target()
 laghu_add_install_layout_test()
@@ -326,6 +331,7 @@ set(laghu_verify_targets
   laghu_core_shared_offsets_test laghu_core_mapped_regions_test
   laghu_core_binary_envelope_test laghu_core_digest_primitives_test
   laghu_os_iovec_translation_test laghu_test_support laghu_test_faults laghu_test_time_entropy
+  laghu_benchmark_metrics_test laghu_benchmark_workload_counters_test
   laghu_test_time_entropy_test laghu_test_support_fixtures_test
   laghu_test_support_runner_contract_test laghu_test_fault_injection_test laghu
   laghu_capability_header_parity laghu_visibility_probe visibility_negative_fixture)

bench/core_foundation.cpp

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+#include <cstdint>
+
+#include <laghu/core/checked_arithmetic.hpp>
+
+#include <laghu/benchmark/internal/workload.hpp>
+
+std::uint64_t laghu::benchmark::internal::run_core_foundation(
+    std::uint64_t seed, WorkloadCounters& counters) noexcept {
+  std::uint64_t state = seed;
+  for (std::uint64_t iteration = 0U; iteration < core_foundation_operations_per_interval;
+       ++iteration) {
+    const auto incremented = laghu::core::checked_add(state, std::uint64_t{0x9e3779b9U});
+    if (!incremented.has_value()) {
+      return state;
+    }
+    state = *incremented ^ (state >> 13U);
+  }
+  // The foundation workload deliberately performs no allocation or Laghu OS
+  // operation. It records no events, so the caller reports these metrics as
+  // uninstrumented rather than inferring them from host metrics.
+  static_cast<void>(counters);
+  return state;
+}

bench/private/laghu/benchmark/internal/metrics.hpp

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+#pragma once
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <span>
+
+namespace laghu::benchmark::internal {
+
+struct Percentiles final {
+  std::uint64_t p50{};
+  std::uint64_t p95{};
+  std::uint64_t p99{};
+  std::uint64_t p999{};
+};
+
+[[nodiscard]] constexpr std::size_t nearest_rank_index(std::size_t sample_count,
+                                                         std::uint64_t per_mille) noexcept {
+  if (sample_count == 0U || per_mille == 0U || per_mille > 1000U) {
+    return 0U;
+  }
+  const std::size_t numerator = sample_count * static_cast<std::size_t>(per_mille);
+  return (numerator + 999U) / 1000U - 1U;
+}
+
+template <std::size_t Capacity>
+[[nodiscard]] bool summarize_percentiles(std::array<std::uint64_t, Capacity>& samples,
+                                         std::size_t count, Percentiles& output) noexcept {
+  if (count == 0U || count > Capacity) {
+    return false;
+  }
+  for (std::size_t left = 0U; left < count; ++left) {
+    std::size_t minimum = left;
+    for (std::size_t right = left + 1U; right < count; ++right) {
+      if (samples[right] < samples[minimum]) {
+        minimum = right;
+      }
+    }
+    const std::uint64_t value = samples[left];
+    samples[left] = samples[minimum];
+    samples[minimum] = value;
+  }
+  output = Percentiles{
+      samples[nearest_rank_index(count, 500U)],
+      samples[nearest_rank_index(count, 950U)],
+      samples[nearest_rank_index(count, 990U)],
+      samples[nearest_rank_index(count, 999U)],
+  };
+  return true;
+}
+
+}  // namespace laghu::benchmark::internal

bench/private/laghu/benchmark/internal/workload.hpp

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+#pragma once
+
+#include <cstdint>
+#include <limits>
+
+namespace laghu::benchmark::internal {
+
+class WorkloadCounters final {
+ public:
+  [[nodiscard]] bool record_allocation_events(std::uint64_t count = 1U) noexcept {
+    return record(allocation_count_, allocation_instrumented_, count);
+  }
+
+  [[nodiscard]] bool record_laghu_syscall_events(std::uint64_t count = 1U) noexcept {
+    return record(laghu_syscall_count_, laghu_syscall_instrumented_, count);
+  }
+
+  [[nodiscard]] bool allocation_instrumented() const noexcept { return allocation_instrumented_; }
+  [[nodiscard]] bool laghu_syscall_instrumented() const noexcept {
+    return laghu_syscall_instrumented_;
+  }
+  [[nodiscard]] std::uint64_t allocation_count() const noexcept { return allocation_count_; }
+  [[nodiscard]] std::uint64_t laghu_syscall_count() const noexcept { return laghu_syscall_count_; }
+
+ private:
+  [[nodiscard]] static bool record(std::uint64_t& total, bool& instrumented,
+                                   std::uint64_t count) noexcept {
+    if (count == 0U) {
+      return true;
+    }
+    if (count > std::numeric_limits<std::uint64_t>::max() - total) {
+      return false;
+    }
+    total += count;
+    instrumented = true;
+    return true;
+  }
+
+  std::uint64_t allocation_count_{};
+  std::uint64_t laghu_syscall_count_{};
+  bool allocation_instrumented_{};
+  bool laghu_syscall_instrumented_{};
+};
+
+inline constexpr std::uint64_t core_foundation_operations_per_interval = 4096U;
+
+[[nodiscard]] std::uint64_t run_core_foundation(std::uint64_t seed,
+                                                WorkloadCounters& counters) noexcept;
+
+}  // namespace laghu::benchmark::internal