Add rcl_timer_set_on_reset_callback() support (#1348)

This PR adds support for the ROS 2 `rcl_timer_set_on_reset_callback()` API to rclnodejs, enabling users to register callbacks that are invoked when a timer is reset. The implementation provides both JavaScript and TypeScript APIs with corresponding native C++ bindings.

**Key Changes:**
- Added `setOnResetCallback()` and `clearOnResetCallback()` methods to the Timer class
- Implemented native C++ bindings using ThreadSafeFunction for cross-thread callback invocation
- Added comprehensive test coverage for the new callback functionality

Fix: #1330

Author: minggangw

lib/timer.js

@@ -105,6 +105,35 @@ class Timer {
     return rclnodejs.getTimerPeriod(this._handle);
   }
 
+  /**
+   * Set the on reset callback.
+   * @param {function} callback - The callback to be called when the timer is reset.
+   * @return {undefined}
+   */
+  setOnResetCallback(callback) {
+    if (DistroUtils.getDistroId() <= DistroUtils.getDistroId('humble')) {
+      console.warn(
+        'setOnResetCallback is not supported by this version of ROS 2'
+      );
+      return;
+    }
+    rclnodejs.setTimerOnResetCallback(this._handle, callback);
+  }
+
+  /**
+   * Clear the on reset callback.
+   * @return {undefined}
+   */
+  clearOnResetCallback() {
+    if (DistroUtils.getDistroId() <= DistroUtils.getDistroId('humble')) {
+      console.warn(
+        'clearOnResetCallback is not supported by this version of ROS 2'
+      );
+      return;
+    }
+    rclnodejs.clearTimerOnResetCallback(this._handle);
+  }
+
   /**
    * Call a timer and starts counting again, retrieves actual and expected call time.
    * @return {object} - The timer information.

src/rcl_timer_bindings.cpp

@@ -17,12 +17,48 @@
 #include <rcl/error_handling.h>
 #include <rcl/rcl.h>
 
+#include <memory>
+#include <mutex>
+#include <unordered_map>
+
 #include "macros.h"
 #include "rcl_handle.h"
 #include "rcl_utilities.h"
 
 namespace rclnodejs {
 
+struct TimerContext {
+  Napi::ThreadSafeFunction on_reset_callback;
+};
+
+static std::unordered_map<rcl_timer_t*, std::shared_ptr<TimerContext>>
+    g_timer_contexts;
+static std::mutex g_timer_contexts_mutex;
+
+void TimerOnResetCallbackTrampoline(const void* user_data,
+                                    size_t number_of_events) {
+  const rcl_timer_t* timer = static_cast<const rcl_timer_t*>(user_data);
+  std::shared_ptr<TimerContext> context;
+
+  {
+    std::lock_guard<std::mutex> lock(g_timer_contexts_mutex);
+    auto it = g_timer_contexts.find(const_cast<rcl_timer_t*>(timer));
+    if (it != g_timer_contexts.end()) {
+      context = it->second;
+    }
+  }
+
+  if (context) {
+    auto callback = [](Napi::Env env, Napi::Function js_callback,
+                       size_t* events) {
+      js_callback.Call({Napi::Number::New(env, *events)});
+      delete events;
+    };
+    size_t* events_ptr = new size_t(number_of_events);
+    context->on_reset_callback.BlockingCall(events_ptr, callback);
+  }
+}
+
 Napi::Value CreateTimer(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
 
@@ -61,6 +97,27 @@ Napi::Value CreateTimer(const Napi::CallbackInfo& info) {
   auto js_obj =
       RclHandle::NewInstance(env, timer, clock_handle, [env](void* ptr) {
         rcl_timer_t* timer = reinterpret_cast<rcl_timer_t*>(ptr);
+
+#if ROS_VERSION > 2205
+        // Clear the callback first to prevent any new callbacks from being
+        // triggered
+        rcl_timer_set_on_reset_callback(timer, nullptr, nullptr);
+#endif
+
+        std::shared_ptr<TimerContext> context;
+        {
+          std::lock_guard<std::mutex> lock(g_timer_contexts_mutex);
+          auto it = g_timer_contexts.find(timer);
+          if (it != g_timer_contexts.end()) {
+            context = it->second;
+            g_timer_contexts.erase(it);
+          }
+        }
+
+        if (context) {
+          context->on_reset_callback.Release();
+        }
+
         rcl_ret_t ret = rcl_timer_fini(timer);
         free(ptr);
         THROW_ERROR_IF_NOT_EQUAL_NO_RETURN(RCL_RET_OK, ret,
@@ -215,6 +272,60 @@ Napi::Value CallTimerWithInfo(const Napi::CallbackInfo& info) {
                  Napi::BigInt::New(env, call_info.actual_call_time));
   return timer_info;
 }
+
+Napi::Value SetTimerOnResetCallback(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  RclHandle* timer_handle = RclHandle::Unwrap(info[0].As<Napi::Object>());
+  rcl_timer_t* timer = reinterpret_cast<rcl_timer_t*>(timer_handle->ptr());
+
+  if (!info[1].IsFunction()) {
+    Napi::TypeError::New(env, "Callback must be a function")
+        .ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+
+  Napi::Function callback = info[1].As<Napi::Function>();
+
+  std::lock_guard<std::mutex> lock(g_timer_contexts_mutex);
+  std::shared_ptr<TimerContext> context;
+  auto it = g_timer_contexts.find(timer);
+  if (it == g_timer_contexts.end()) {
+    context = std::make_shared<TimerContext>();
+    g_timer_contexts[timer] = context;
+  } else {
+    context = it->second;
+    context->on_reset_callback.Release();
+  }
+
+  context->on_reset_callback = Napi::ThreadSafeFunction::New(
+      env, callback, "TimerOnResetCallback", 0, 1);
+
+  THROW_ERROR_IF_NOT_EQUAL(RCL_RET_OK,
+                           rcl_timer_set_on_reset_callback(
+                               timer, TimerOnResetCallbackTrampoline, timer),
+                           rcl_get_error_string().str);
+
+  return env.Undefined();
+}
+
+Napi::Value ClearTimerOnResetCallback(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  RclHandle* timer_handle = RclHandle::Unwrap(info[0].As<Napi::Object>());
+  rcl_timer_t* timer = reinterpret_cast<rcl_timer_t*>(timer_handle->ptr());
+
+  std::lock_guard<std::mutex> lock(g_timer_contexts_mutex);
+  auto it = g_timer_contexts.find(timer);
+  if (it != g_timer_contexts.end()) {
+    it->second->on_reset_callback.Release();
+    g_timer_contexts.erase(it);
+  }
+
+  THROW_ERROR_IF_NOT_EQUAL(
+      RCL_RET_OK, rcl_timer_set_on_reset_callback(timer, nullptr, nullptr),
+      rcl_get_error_string().str);
+
+  return env.Undefined();
+}
 #endif
 
 Napi::Object InitTimerBindings(Napi::Env env, Napi::Object exports) {
@@ -231,6 +342,10 @@ Napi::Object InitTimerBindings(Napi::Env env, Napi::Object exports) {
   exports.Set("changeTimerPeriod", Napi::Function::New(env, ChangeTimerPeriod));
   exports.Set("getTimerPeriod", Napi::Function::New(env, GetTimerPeriod));
 #if ROS_VERSION > 2205  // 2205 == Humble
+  exports.Set("setTimerOnResetCallback",
+              Napi::Function::New(env, SetTimerOnResetCallback));
+  exports.Set("clearTimerOnResetCallback",
+              Napi::Function::New(env, ClearTimerOnResetCallback));
   exports.Set("callTimerWithInfo", Napi::Function::New(env, CallTimerWithInfo));
 #endif
   return exports;

test/test-timer.js

@@ -166,5 +166,64 @@ describe('rclnodejs Timer class testing', function () {
       timer.cancel();
       done();
     });
+
+    it('timer.setOnResetCallback', function (done) {
+      if (DistroUtils.getDistroId() <= DistroUtils.getDistroId('humble')) {
+        this.skip();
+        return;
+      }
+      var timer = node.createTimer(TIMER_INTERVAL, function () {});
+      var called = false;
+      timer.setOnResetCallback(function (events) {
+        assert.strictEqual(typeof events, 'number');
+        assert.ok(events >= 0);
+        called = true;
+      });
+      timer.reset();
+
+      setTimeout(() => {
+        assert.ok(called);
+        timer.cancel();
+        done();
+      }, 100);
+
+      rclnodejs.spin(node);
+    });
+
+    it('timer.clearOnResetCallback', function (done) {
+      if (DistroUtils.getDistroId() <= DistroUtils.getDistroId('humble')) {
+        this.skip();
+        return;
+      }
+      var timer = node.createTimer(TIMER_INTERVAL, function () {});
+      var called = false;
+      timer.setOnResetCallback(function (events) {
+        assert.strictEqual(typeof events, 'number');
+        assert.ok(events >= 0);
+        called = true;
+      });
+      timer.clearOnResetCallback();
+      timer.reset();
+
+      setTimeout(() => {
+        assert.ok(!called);
+        timer.cancel();
+        done();
+      }, 100);
+
+      rclnodejs.spin(node);
+    });
+
+    it('timer callback should be called repeatedly', function (done) {
+      let count = 0;
+      const timer = node.createTimer(TIMER_INTERVAL, () => {
+        count++;
+        if (count >= 3) {
+          timer.cancel();
+          done();
+        }
+      });
+      rclnodejs.spin(node);
+    });
   });
 });

test/types/index.test-d.ts

@@ -289,6 +289,8 @@ expectType<boolean>(timer.isCanceled());
 expectType<void>(timer.cancel());
 expectType<void>(timer.changeTimerPeriod(BigInt(100000)));
 expectType<bigint>(timer.timerPeriod());
+expectType<void>(timer.setOnResetCallback((_events: number) => {}));
+expectType<void>(timer.clearOnResetCallback());
 expectType<object>(timer.callTimerWithInfo());
 
 // ---- Rate ----

types/timer.d.ts

@@ -58,6 +58,17 @@ declare module 'rclnodejs' {
      */
     timerPeriod(): bigint;
 
+    /**
+     * Set the on reset callback.
+     * @param callback - The callback to be called when the timer is reset.
+     */
+    setOnResetCallback(callback: (events: number) => void): void;
+
+    /**
+     * Clear the on reset callback.
+     */
+    clearOnResetCallback(): void;
+
     /**
      * Call a timer and starts counting again, retrieves actual and expected call time.
      * @return - The timer information.