hmon: add C++ interface to heartbeat monitor

src/health_monitoring_lib/BUILD

@@ -28,13 +28,15 @@ PROC_MACRO_DEPS = [
 CC_SOURCES = [
     "cpp/common.cpp",
     "cpp/deadline_monitor.cpp",
+    "cpp/heartbeat_monitor.cpp",
     "cpp/health_monitor.cpp",
 ]
 
 CC_HDRS = [
     "cpp/include/score/hm/common.h",
     "cpp/include/score/hm/tag.h",
     "cpp/include/score/hm/deadline/deadline_monitor.h",
+    "cpp/include/score/hm/heartbeat/heartbeat_monitor.h",
     "cpp/include/score/hm/health_monitor.h",
 ]
 

src/health_monitoring_lib/cpp/health_monitor.cpp

@@ -18,6 +18,7 @@ extern "C" {
 using namespace score::hm;
 using namespace score::hm::internal;
 using namespace score::hm::deadline;
+using namespace score::hm::heartbeat;
 
 // Functions below must match functions defined in `crate::ffi`.
 
@@ -30,9 +31,15 @@ FFICode health_monitor_builder_build(FFIHandle health_monitor_builder_handle,
 FFICode health_monitor_builder_add_deadline_monitor(FFIHandle health_monitor_builder_handle,
                                                     const MonitorTag* monitor_tag,
                                                     FFIHandle deadline_monitor_builder_handle);
+FFICode health_monitor_builder_add_heartbeat_monitor(FFIHandle health_monitor_builder_handle,
+                                                     const MonitorTag* monitor_tag,
+                                                     FFIHandle heartbeat_monitor_builder_handle);
 FFICode health_monitor_get_deadline_monitor(FFIHandle health_monitor_handle,
                                             const MonitorTag* monitor_tag,
                                             FFIHandle* deadline_monitor_handle_out);
+FFICode health_monitor_get_heartbeat_monitor(FFIHandle health_monitor_handle,
+                                             const MonitorTag* monitor_tag,
+                                             FFIHandle* heartbeat_monitor_handle_out);
 FFICode health_monitor_start(FFIHandle health_monitor_handle);
 FFICode health_monitor_destroy(FFIHandle health_monitor_handle);
 }
@@ -71,6 +78,20 @@ HealthMonitorBuilder HealthMonitorBuilder::add_deadline_monitor(const MonitorTag
     return std::move(*this);
 }
 
+HealthMonitorBuilder HealthMonitorBuilder::add_heartbeat_monitor(const MonitorTag& monitor_tag,
+                                                                 HeartbeatMonitorBuilder&& monitor) &&
+{
+    auto monitor_handle = monitor.drop_by_rust();
+    SCORE_LANGUAGE_FUTURECPP_PRECONDITION(monitor_handle.has_value());
+    SCORE_LANGUAGE_FUTURECPP_PRECONDITION(health_monitor_builder_handle_.as_rust_handle().has_value());
+
+    auto result{health_monitor_builder_add_heartbeat_monitor(
+        health_monitor_builder_handle_.as_rust_handle().value(), &monitor_tag, monitor_handle.value())};
+    SCORE_LANGUAGE_FUTURECPP_ASSERT(result == kSuccess);
+
+    return std::move(*this);
+}
+
 HealthMonitorBuilder HealthMonitorBuilder::with_internal_processing_cycle(std::chrono::milliseconds cycle_duration) &&
 {
     internal_processing_cycle_duration_ = cycle_duration;
@@ -122,6 +143,18 @@ score::cpp::expected<DeadlineMonitor, Error> HealthMonitor::get_deadline_monitor
     return score::cpp::expected<DeadlineMonitor, Error>(DeadlineMonitor{handle});
 }
 
+score::cpp::expected<HeartbeatMonitor, Error> HealthMonitor::get_heartbeat_monitor(const MonitorTag& monitor_tag)
+{
+    FFIHandle handle{nullptr};
+    auto result{health_monitor_get_heartbeat_monitor(health_monitor_, &monitor_tag, &handle)};
+    if (result != kSuccess)
+    {
+        return score::cpp::unexpected(static_cast<Error>(result));
+    }
+
+    return score::cpp::expected<HeartbeatMonitor, Error>(HeartbeatMonitor{handle});
+}
+
 void HealthMonitor::start()
 {
     auto result{health_monitor_start(health_monitor_)};

src/health_monitoring_lib/cpp/heartbeat_monitor.cpp

@@ -0,0 +1,57 @@
+/********************************************************************************
+ * Copyright (c) 2026 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Apache License Version 2.0 which is available at
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ ********************************************************************************/
+#include "score/hm/heartbeat/heartbeat_monitor.h"
+
+namespace {
+extern "C" {
+using namespace score::hm;
+using namespace score::hm::internal;
+using namespace score::hm::heartbeat;
+
+FFICode heartbeat_monitor_builder_create(uint32_t range_min_ms, uint32_t range_max_ms, FFIHandle* heartbeat_monitor_builder_handle_out);
+FFICode heartbeat_monitor_builder_destroy(FFIHandle heartbeat_monitor_builder_handle);
+FFICode heartbeat_monitor_destroy(FFIHandle heartbeat_monitor_builder_handle);
+FFICode heartbeat_monitor_heartbeat(FFIHandle heartbeat_monitor_builder_handle);
+}
+
+FFIHandle heartbeat_monitor_builder_create_wrapper(uint32_t range_min_ms, uint32_t range_max_ms)
+{
+    FFIHandle handle{nullptr};
+    auto result{heartbeat_monitor_builder_create(range_min_ms, range_max_ms, &handle)};
+    SCORE_LANGUAGE_FUTURECPP_ASSERT(result == kSuccess);
+    return handle;
+}
+
+}
+
+namespace score::hm::heartbeat
+{
+HeartbeatMonitorBuilder::HeartbeatMonitorBuilder(const TimeRange& range)
+    : monitor_builder_handle_{heartbeat_monitor_builder_create_wrapper(range.min_ms(), range.max_ms()),
+                              &heartbeat_monitor_builder_destroy}
+{
+}
+
+HeartbeatMonitor::HeartbeatMonitor(FFIHandle monitor_handle)
+    : monitor_handle_{monitor_handle, &heartbeat_monitor_destroy}
+{
+}
+
+void HeartbeatMonitor::heartbeat()
+{
+    auto monitor_handle{monitor_handle_.as_rust_handle()};
+    SCORE_LANGUAGE_FUTURECPP_PRECONDITION(monitor_handle.has_value());
+    SCORE_LANGUAGE_FUTURECPP_ASSERT(heartbeat_monitor_heartbeat(monitor_handle.value()) == kSuccess);
+}
+
+}  // namespace score::hm::heartbeat

src/health_monitoring_lib/cpp/include/score/hm/health_monitor.h

@@ -15,6 +15,7 @@
 
 #include <score/hm/common.h>
 #include <score/hm/deadline/deadline_monitor.h>
+#include <score/hm/heartbeat/heartbeat_monitor.h>
 #include <score/hm/tag.h>
 
 namespace score::hm
@@ -42,6 +43,10 @@ class HealthMonitorBuilder final
     HealthMonitorBuilder add_deadline_monitor(const MonitorTag& monitor_tag,
                                               deadline::DeadlineMonitorBuilder&& monitor) &&;
 
+    /// Adds a heartbeat monitor for a specific identifier tag.
+    HealthMonitorBuilder add_heartbeat_monitor(const MonitorTag& monitor_tag,
+                                               heartbeat::HeartbeatMonitorBuilder&& monitor) &&;
+
     /// Sets the cycle duration for supervisor API notifications.
     /// This duration determines how often the health monitor notifies the supervisor that the system is alive.
     HealthMonitorBuilder with_supervisor_api_cycle(std::chrono::milliseconds cycle_duration) &&;
@@ -72,6 +77,7 @@ class HealthMonitor final
     ~HealthMonitor();
 
     score::cpp::expected<deadline::DeadlineMonitor, Error> get_deadline_monitor(const MonitorTag& monitor_tag);
+    score::cpp::expected<heartbeat::HeartbeatMonitor, Error> get_heartbeat_monitor(const MonitorTag& monitor_tag);
 
     void start();
 

src/health_monitoring_lib/cpp/include/score/hm/heartbeat/heartbeat_monitor.h

@@ -0,0 +1,84 @@
+/********************************************************************************
+ * Copyright (c) 2026 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Apache License Version 2.0 which is available at
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ ********************************************************************************/
+#ifndef SCORE_HM_HEARTBEAT_HEARTBEAT_MONITOR_H
+#define SCORE_HM_HEARTBEAT_HEARTBEAT_MONITOR_H
+
+#include <score/expected.hpp>
+#include <score/hm/common.h>
+
+namespace score::hm
+{
+// Forward declaration
+class HealthMonitor;
+class HealthMonitorBuilder;
+}  // namespace score::hm
+
+namespace score::hm::heartbeat
+{
+// Forward declaration
+class HeartbeatMonitor;
+
+/// Builder for `HeartbeatMonitor`.
+class HeartbeatMonitorBuilder final : public internal::RustDroppable<HeartbeatMonitorBuilder>
+{
+  public:
+    /// Create a new `HeartbeatMonitorBuilder`.
+    ///
+    /// - `range` - time range between heartbeats.
+    HeartbeatMonitorBuilder(const TimeRange& range);
+
+    HeartbeatMonitorBuilder(const HeartbeatMonitorBuilder&) = delete;
+    HeartbeatMonitorBuilder& operator=(const HeartbeatMonitorBuilder&) = delete;
+
+    HeartbeatMonitorBuilder(HeartbeatMonitorBuilder&&) = default;
+    HeartbeatMonitorBuilder& operator=(HeartbeatMonitorBuilder&&) = delete;
+
+  protected:
+    std::optional<internal::FFIHandle> _drop_by_rust_impl()
+    {
+        return monitor_builder_handle_.drop_by_rust();
+    }
+
+  private:
+    internal::DroppableFFIHandle monitor_builder_handle_;
+
+    // Allow to hide drop_by_rust implementation
+    friend class internal::RustDroppable<HeartbeatMonitorBuilder>;
+
+    // Allow HealthMonitorBuilder to access drop_by_rust implementation
+    friend class ::score::hm::HealthMonitorBuilder;
+};
+
+class HeartbeatMonitor final
+{
+  public:
+    // Delete copy, allow move
+    HeartbeatMonitor(const HeartbeatMonitor&) = delete;
+    HeartbeatMonitor& operator=(const HeartbeatMonitor&) = delete;
+
+    HeartbeatMonitor(HeartbeatMonitor&& other) noexcept = default;
+    HeartbeatMonitor& operator=(HeartbeatMonitor&& other) noexcept = default;
+
+    void heartbeat();
+
+  private:
+    explicit HeartbeatMonitor(internal::FFIHandle monitor_handle);
+
+    // Only `HealthMonitor` is allowed to create `HeartbeatMonitor` instances.
+    friend class score::hm::HealthMonitor;
+    internal::DroppableFFIHandle monitor_handle_;
+};
+
+}  // namespace score::hm::heartbeat
+
+#endif  // SCORE_HM_HEARTBEAT_HEARTBEAT_MONITOR_H

src/health_monitoring_lib/cpp/tests/health_monitor_test.cpp

@@ -44,8 +44,14 @@ TEST_F(HealthMonitorTest, TestName)
             .add_deadline(DeadlineTag("deadline_2"),
                           TimeRange(std::chrono::milliseconds(100), std::chrono::milliseconds(200)));
 
+    // Setup heartbeat monitor construction.
+    const MonitorTag heartbeat_monitor_tag{"heartbeat_monitor"};
+    const TimeRange heartbeat_range{std::chrono::milliseconds{100}, std::chrono::milliseconds{200}};
+    auto heartbeat_monitor_builder = heartbeat::HeartbeatMonitorBuilder(heartbeat_range);
+
     auto hm = HealthMonitorBuilder()
                   .add_deadline_monitor(deadline_monitor_tag, std::move(deadline_monitor_builder))
+                  .add_heartbeat_monitor(heartbeat_monitor_tag, std::move(heartbeat_monitor_builder))
                   .with_internal_processing_cycle(std::chrono::milliseconds(50))
                   .with_supervisor_api_cycle(std::chrono::milliseconds(50))
                   .build();
@@ -62,9 +68,23 @@ TEST_F(HealthMonitorTest, TestName)
 
     auto deadline_mon = std::move(*deadline_monitor_res);
 
+    // Obtain heartbeat monitor from HMON.
+    auto heartbeat_monitor_res{hm.get_heartbeat_monitor(heartbeat_monitor_tag)};
+    EXPECT_TRUE(heartbeat_monitor_res.has_value());
+
+    {
+        // Try again to get the same monitor.
+        auto heartbeat_monitor_res{hm.get_heartbeat_monitor(heartbeat_monitor_tag)};
+        EXPECT_FALSE(heartbeat_monitor_res.has_value());
+    }
+
+    auto heartbeat_monitor{std::move(*heartbeat_monitor_res)};
+
     // Start HMON.
     hm.start();
 
+    heartbeat_monitor.heartbeat();
+
     auto deadline_res = deadline_mon.get_deadline(DeadlineTag("deadline_1"));
 
     {

src/health_monitoring_lib/rust/deadline/ffi.rs

@@ -81,10 +81,6 @@ pub extern "C" fn deadline_monitor_builder_add_deadline(
         return FFICode::NullParameter;
     }
 
-    if min_ms > max_ms {
-        return FFICode::InvalidArgument;
-    }
-
     // SAFETY:
     // Validity of the pointer is ensured.
     // `DeadlineTag` type must be compatible between C++ and Rust.
@@ -97,13 +93,14 @@ pub extern "C" fn deadline_monitor_builder_add_deadline(
     let mut deadline_monitor_builder =
         FFIBorrowed::new(unsafe { Box::from_raw(deadline_monitor_builder_handle as *mut DeadlineMonitorBuilder) });
 
-    deadline_monitor_builder.add_deadline_internal(
-        deadline_tag,
-        TimeRange::new(
-            Duration::from_millis(min_ms as u64),
-            Duration::from_millis(max_ms as u64),
-        ),
-    );
+    let range_min = Duration::from_millis(min_ms as u64);
+    let range_max = Duration::from_millis(max_ms as u64);
+    let range = match TimeRange::new_internal(range_min, range_max) {
+        Some(range) => range,
+        None => return FFICode::InvalidArgument,
+    };
+
+    deadline_monitor_builder.add_deadline_internal(deadline_tag, range);
 
     FFICode::Success
 }