[thomasmoore16]

rcl: Allow specifying an initial timer trigger time

Branch: timer-initial-call-time (this repo: ros2/rcl)
Companion PR: ros2/rclcpp#3270 — "Add AlignedTimer and AlignedWallTimer for start-time and phase-aligned timers" (built on top of this change)

Summary

rcl_timer_init2 always computes a timer's first trigger time as now() + period. There is no way to ask for a timer that fires immediately, after a custom initial delay, or at a specific phase-aligned point in time without extra caller-side bookkeeping.

This adds rcl_timer_init_with_start_time, which takes an explicit initial_call_time (absolute rcl_time_point_value_t) alongside period, and updates rcl_timer_reset so timers initialized with rcl_timer_init_with_start_time preserve their schedule phase across cancel / reset cycles.

Changes

• rcl_timer_init_with_start_time(timer, clock, context, initial_call_time, period, callback, allocator, autostart): New entry point that seeds next_call_time directly with initial_call_time (an initial time in the past makes the timer ready immediately) and marks the timer as phase-aligned (impl.aligned = true).
• Single-clock-read shared _rcl_timer_init_impl: Both rcl_timer_init2 (aligned = false) and rcl_timer_init_with_start_time (aligned = true) read the clock once and pass now to _rcl_timer_init_impl, keeping last_call_time and next_call_time consistent on a single clock reading.
• Phase-preserving rcl_timer_reset for aligned timers:
  • For timers initialized via rcl_timer_init2, rcl_timer_reset continues to recompute next_call_time = now + period (unchanged).
  • For timers initialized via rcl_timer_init_with_start_time, rcl_timer_reset leaves next_call_time unchanged if still in the future, or advances it by whole period multiples past now (with checked int64_t saturation to avoid signed overflow) if overdue, while un-canceling the timer.
• New tests in rcl/test/rcl/test_timer.cpp:
  • test_timer_init_with_start_time_with_invalid_arguments
  • test_timer_init_with_start_time_honors_future_initial_call_time
  • test_timer_init_with_start_time_with_past_initial_call_time_is_ready
  • test_aligned_timer_reset_does_not_advance_if_not_yet_due
  • test_aligned_timer_reset_catches_up_if_overdue
  • test_aligned_timer_reset_uncancels_and_preserves_phase
  • test_timer_init2_reads_clock_exactly_once
  • test_timer_init_with_start_time_reads_clock_exactly_once
  • test_aligned_timer_reset_saturates_instead_of_overflowing

Compatibility

Purely additive — no existing public signatures change, and rcl_timer_init2 / rcl_timer_reset behavior is unchanged for every existing caller.

Testing

Built and tested against rolling in a ros:rolling-ros-base container via colcon build / colcon test (test_timer and all ament_lint_auto linters: uncrustify, cpplint, cppcheck, copyright, lint_cmake, xmllint), as well as together with ros2/rclcpp#3270.

Landing order

Prerequisite for companion PR ros2/rclcpp#3270 (AlignedTimer / AlignedWallTimer), which calls rcl_timer_init_with_start_time. Please land this PR first, or coordinate merges.

[fujitatomoya]

@jmachowinski we talked about this at ROSCon, and you have an another idea to address this. friendly ping.

[tcm0116]

@fujitatomoya - based on the conversation in ros2/rclcpp#3270, it sounds like there's an agreed path forward. I've pushed a small update to align this PR with the changes to rclcpp.

Note that I am no longer with my previous company, so I'm shifting over to using my personal account to wrap up these PRs. Feel free to re-assign the PR to this account.