feat(agnocastlib): Support ROS_TIME for create_timer

[Koichi98]

Description

Add support for RCL_ROS_TIME and RCL_SYSTEM_TIME clock types in create_timer. Previously, only RCL_STEADY_TIME was supported.

Background: use_sim_time and ros_time_is_active

When use_sim_time parameter is set to true, the node subscribes to the /clock topic for simulation time. However, ros_time_is_active() returns true only after the first /clock message is received. Before that, even with use_sim_time=true, the system uses wall clock time (ros_time_is_active() returns false).

This creates a dynamic transition:

• Before /clock received: ros_time_is_active() = false → use timer_fd (wall clock)
• After /clock received: ros_time_is_active() = true → use clock_eventfd (simulation time)

Implementation

Dual-fd Architecture for ROS_TIME Timers

For RCL_ROS_TIME timers, we use two file descriptors:

• timer_fd: timerfd for wall clock based timing (used when ros_time_is_active() = false)
• clock_eventfd: eventfd triggered by time jump callbacks (used when ros_time_is_active() = true)

Time Jump Handling

Registered time jump callbacks handle clock state transitions:

• RCL_ROS_TIME_ACTIVATED: Close timer_fd, switch to clock_eventfd
• RCL_ROS_TIME_DEACTIVATED: Recreate timer_fd, switch back to wall clock
• Forward/backward jumps: Adjust timer scheduling and wake up epoll if timer is ready

Thread Safety with Reader/Writer Lock

Time jump callbacks run in a dedicated clock executor thread, while timer events are handled in the main executor thread. To prevent race conditions when timer_fd is closed/recreated:

• std::shared_mutex fd_mutex protects timer_fd access
• shared_lock: Used for read operations (read(), epoll_ctl())
• unique_lock: Used for write operations (close(), create_timer_fd())

This ensures:

• Multiple readers can access timer_fd concurrently
• Writers have exclusive access during close/create operations
• No race between read() and close() on timer_fd

Clock Type Handling

• RCL_STEADY_TIME: Uses CLOCK_MONOTONIC timerfd
• RCL_SYSTEM_TIME: Uses CLOCK_REALTIME timerfd
• RCL_ROS_TIME: Uses CLOCK_REALTIME timerfd + clock_eventfd

Related links

How was this PR tested?

• Autoware (required)
• bash scripts/e2e_test_1to1_with_ros2sub (required)
• bash scripts/e2e_test_2to2 (required)
• kunit tests (required when modifying the kernel module)
• sample application

Notes for reviewers

Version Update Label (Required)

Please add exactly one of the following labels to this PR:

• need-major-update: User API breaking changes
• need-minor-update: Internal API breaking changes (heaphook/kmod/agnocastlib compatibility)
• need-patch-update: Bug fixes and other changes

Important notes:

• If you need need-major-update or need-minor-update, please include this in the PR title as well.
  • Example: fix(foo)[needs major version update]: bar or feat(baz)[needs minor version update]: qux
• After receiving approval from reviewers, add the run-build-test label. The PR can only be merged after the build tests pass.

See CONTRIBUTING.md for detailed versioning rules.