feat: timers API #480

mxgrey · 2025-05-14T15:19:11Z

This PR splits the timer.rs module out of #446 so it can be reviewed separately after #446 is merged.

Signed-off-by: Michael X. Grey <[email protected]>

mxgrey · 2025-06-29T15:17:18Z

@esteve This is embarrassing since I was vocally supportive of committing the cargo lockfiles, but now I'm thinking that might have been a mistake. I'm noticing two issues in practice:

Every run of colcon build seems to update the lockfiles. In fact a bunch of different tools that I use on a regular basis are triggering automatic updates of the lockfiles. It's creating a lot of unnecessary churn in the git history.
More crucially, I'm seeing this error happen in the minimum supported Rust compiler version CI. Essentially any new lockfiles that get generated and committed will be incompatible with the "Minimal" CI.

I've had to resort to manually deleting the Cargo.lock for the worker_demo, logging_demo, and now timer_demo examples each time I commit in order to get the Minimal CI to pass.

I'd suggest we remove the lockfiles from the git history or else this is going to cause a great deal of ongoing annoyance where everyone is constantly reverting lockfiles before committing 😞

Signed-off-by: Michael X. Grey <[email protected]>

mxgrey · 2025-06-29T15:47:40Z

@knmcguire Sorry to summon you into this random PR but it seems a new CI failure has popped up for Windows.

I have a feeling this is due to this recent PR in colcon-cargo, and we'll see this failure show up for the main branch on Tuesday during its weekly CI run.

knmcguire · 2025-06-30T07:09:30Z

Thanks for letting me know ! I don't get messages of the CI failures on windows so I was unaware of this. I'll dig into it and make a PR

The cargo lock did solve some things for the windows CI though so if that is removed we might need to deal with those failures, but let's see when it comes.

knmcguire · 2025-06-30T07:37:27Z

See this PR: #495

jhdcs

It looks very good for the most part! I just noticed some unsafe calls that didn't have Safety comments associated with them.

rclrs/src/timer.rs

knmcguire

Managed to get this demo to run on my machine (ubuntu on wsl2) 😄

I'm not comfortable to do a full indepth review yet... but I've added some thoughts.

knmcguire · 2025-07-17T09:21:56Z

examples/timer_demo/Cargo.toml

+name = "examples_timer_demo"
+version = "0.1.0"
+edition = "2021"
+


Maybe good to have a bin here so that we can run it through ROS2 command?

Is this what you had in mind?

Since the example is in src/main.rs, by default it will generate a binary with the same name as the package, examples_timer_demo. But I see in the other example packages there's a certain naming pattern for the binaries, so now I've copied that pattern here.

ahhh gotcha.

And yes exactly like that. naming consistency is good :)

knmcguire · 2025-07-17T09:28:23Z

examples/timer_demo/src/main.rs

+    let _timer = worker.create_timer_repeating(timer_period, move |count: &mut usize| {
+        *count += 1;
+        println!(
+            "Drinking 🧉 for the {}th time every {:?}.",


Works for me and is a nice example :)

Does ROS2 have an example like this actually? Not used in the tutorials right?

I guess the only nitpick would be, that all other python/cpp examples use create_timer()

See this reply.

knmcguire · 2025-07-17T09:30:25Z

rclrs/src/node.rs

        )
    }

+    /// Create a [`Timer`] with a repeating callback.


I was first confused on why there were some much commented out lines, but then I realized that this was for the documentation. Nice!

knmcguire · 2025-07-17T09:42:35Z

rclrs/src/timer.rs

+/// The executor needs to be [spinning][1] for a timer's callback to be triggered.
+///
+/// Timers can be created by a [`Node`] using one of these methods:
+/// - [`NodeState::create_timer_repeating`][2]


This goes a bit too deep for my knowledge I'm afraid. But are these timer naming's consistent with the api of rclcpp or rclpy ?

The naming is intentionally not the same because in rclrs we're introducing the concept of a one-shot timer, which is different from a repeating timer.

The type system of the Rust language makes a strong distinction between the traits FnMut() and FnOnce(). Repeating timers can use callbacks with the FnMut() trait but cannot use callbacks with the FnOnce() trait. One-shot timers are able to use callbacks with the FnOnce() trait, but we have to guarantee that the callback will only get triggered one time, and then after that the timer must be inert (not contain any callback).

Because of this we end up with three possible kinds of timers:

Repeating

One-shot

Inert

rclcpp and rclpy don't have this distinction because they have no concept of FnMut versus FnOnce, and I don't think they even support a concept of one-shot timer, although the subject has been discussed before.

In my mind this is the kind of divergence that is expected between the client libraries of different languages, in order to reflect differences in what those languages offer.

aha.... yes

In hindsight I can indeed see quite differences between the c++ and python tutorials as there are some differences with that as well. Then focusing on api naming consistency shouldn't be the goal as long as it is feature complete.

thanks for the explanation! I missed/forgot this.

Signed-off-by: Michael X. Grey <[email protected]>

mxgrey · 2025-07-17T12:18:17Z

@jhdcs thanks for noticing the absence of safety comments. I've added them in via a589997

Signed-off-by: Michael X. Grey <[email protected]>

mxgrey · 2025-07-17T15:12:29Z

CI is currently failing because of an upstream issue which is fixed by ros2-rust/rosidl_runtime_rs#13

Co-authored-by: Agustin Alba Chicar <[email protected]> Co-authored-by: Jesús Silva <[email protected]> Signed-off-by: Agustin Alba Chicar <[email protected]> Signed-off-by: Jesús Silva <[email protected]> Signed-off-by: Michael X. Grey <[email protected]>

mxgrey · 2025-07-18T08:38:13Z

When I did a squash merge to resolve merge conflicts from #446, I lost the commit history from #440 which this PR was based off of.

I've added 775b170 which should prompt GitHub to credit @agalbachicar and @JesusSilvaUtrera when this PR gets squash-merged, but I would appreciate if whichever maintainer merges this PR can double-check that the final commit message includes

Co-authored-by: Agustin Alba Chicar <[email protected]>
Co-authored-by: Jesús Silva <[email protected]>

rclrs/src/timer/timer_options.rs

luca-della-vedova · 2025-07-23T09:45:51Z

rclrs/src/timer.rs

+    pub(crate) fn create<'a>(
+        period: Duration,
+        clock: Clock,
+        callback: AnyTimerCallback<Scope>,
+        commands: &Arc<WorkerCommands>,
+        context: &ContextHandle,
+    ) -> Result<Arc<Self>, RclrsError> {


I wonder if there is any risk for odd behavior here when a user decides to create a timer with the NodeClock?

Specifically, because we keep an Arc to the underlying rcl_clock that is wrapped by both Timers and Clocks, if a user was to create a Timer with the Node clock it would be kept alive even after the Node is destroyed.
This is possibly desirable for steady clocks, but there is an odd edge case if the Clock is using RosTime when use_sim_time:=true.
Since RosTime is updated through a /clock subscription but the Node has been destroyed, I suspect the Timer silently won't be updated anymore, making it effectively useless.
I don't have a clear solution for this (maybe making the ownership to the Node's clock Weak and offering an API to know whether the underlying clock still exists? But this is also not great) so I'm curious to know what you think

One simple solution would be to add a node: Node or node: Arc<NodeHandle> field to the Timer struct so that the node is guaranteed to remain valid for as long as the Timer is valid.

OTOH if a Timer is meant to use the Node's clock and the Node gets dropped, it kind of makes logical sense that the Timer simply stops being triggered since the Node no longer has time. But it's probably not the behavior that a user expects.

IIRC we are only allowing Timers to be created through Nodes, so I see nothing wrong with adding the node field like most other primitives have to express that dependency.

I've given TimerState a dependency on Node when using NodeTime: 2e2dce0

Signed-off-by: Michael X. Grey <[email protected]>

esteve · 2025-08-21T15:30:26Z

@mxgrey sorry it took so long, can you fix the conflicts? Now that rclrs 0.5.0 is out, we can merge this soon. Thanks.

Signed-off-by: Michael X. Grey <[email protected]>

mxgrey · 2025-08-22T16:45:09Z

@esteve no worries, merge conflicts are fixed!

rclrs/src/node.rs

Signed-off-by: Michael X. Grey <[email protected]>

esteve

@mxgrey thanks!

esteve · 2025-10-12T09:49:11Z

@jhdcs I hope it's ok with you, I'll merge this PR. Given the US government shutdown, that @jhdcs can't work on ros2-rust during the shutdown, and that @mxgrey has addressed @jhdcs 's feedback, I'll go ahead and merge this PR.

Thanks @mxgrey for the great work, and @jhdcs @knmcguire @luca-della-vedova for their reviews.

mxgrey mentioned this pull request May 14, 2025

Async Workers #446

Merged

Fix merge conflicts with main

2d20c4e

Signed-off-by: Michael X. Grey <[email protected]>

mxgrey force-pushed the worker_with_timers branch from a2af202 to 2d20c4e Compare June 29, 2025 06:16

mxgrey added 6 commits June 29, 2025 15:55

Update documentation of timers

c9c2127

Signed-off-by: Michael X. Grey <[email protected]>

Fix compatibility with kilted and rolling

7ad4ece

Signed-off-by: Michael X. Grey <[email protected]>

Fix typo

802925b

Signed-off-by: Michael X. Grey <[email protected]>

Remove Cargo.lock for timers demo

f24b978

Signed-off-by: Michael X. Grey <[email protected]>

Fix example package names

9b6b1d1

Signed-off-by: Michael X. Grey <[email protected]>

Fix name of timer demo

73b34b3

Signed-off-by: Michael X. Grey <[email protected]>

Fix name of parameter demo

030f59c

Signed-off-by: Michael X. Grey <[email protected]>

mxgrey mentioned this pull request Jun 30, 2025

upgrade colcon-cargo in pixi.toml for windows CI #495

Merged

Merge remote-tracking branch 'origin/main' into worker_with_timers

82f4da6

jhdcs requested changes Jul 15, 2025

View reviewed changes

knmcguire reviewed Jul 17, 2025

View reviewed changes

Add safety comments

a589997

Signed-off-by: Michael X. Grey <[email protected]>

mxgrey added 2 commits July 17, 2025 20:26

Add an explicit binary name for timer demo

a4fa5cb

Signed-off-by: Michael X. Grey <[email protected]>

Restore unsafe tag to Send trait

35fa24a

Signed-off-by: Michael X. Grey <[email protected]>

luca-della-vedova reviewed Jul 23, 2025

View reviewed changes

mxgrey added 4 commits August 11, 2025 20:50

Add safety comment

771920d

Signed-off-by: Michael X. Grey <[email protected]>

Finish sentence

2780db7

Signed-off-by: Michael X. Grey <[email protected]>

Timers have a dependency on Node when using NodeTime

2e2dce0

Signed-off-by: Michael X. Grey <[email protected]>

Merge remote-tracking branch 'origin/main' into worker_with_timers

421784b

Signed-off-by: Michael X. Grey <[email protected]>

mxgrey mentioned this pull request Aug 11, 2025

Basic Timer implementation #440

Closed

1 task

mxgrey added 2 commits August 23, 2025 00:32

Merge remote-tracking branch 'origin/main' into worker_with_timers

01cb7f5

Signed-off-by: Michael X. Grey <[email protected]>

Move timer_demo to examples repo

9acf2ad

Signed-off-by: Michael X. Grey <[email protected]>

esteve requested changes Aug 24, 2025

View reviewed changes

rclrs/src/node.rs Show resolved Hide resolved

rclrs/src/node.rs Show resolved Hide resolved

rclrs/src/node.rs Outdated Show resolved Hide resolved

esteve changed the title ~~Timers~~ feat!: timers API Aug 24, 2025

esteve changed the title ~~feat!: timers API~~ feat: timers API Aug 24, 2025

balthasarschuess mentioned this pull request Aug 27, 2025

Feature request: Clock Jump Callbacks #524

Open

mxgrey added 2 commits October 8, 2025 20:13

Expand on timer docs

52238cf

Signed-off-by: Michael X. Grey <[email protected]>

trigger change

5338574

Signed-off-by: Michael X. Grey <[email protected]>

mxgrey requested review from esteve and jhdcs October 8, 2025 14:45

esteve approved these changes Oct 12, 2025

View reviewed changes

esteve merged commit 3c5839e into ros2-rust:main Oct 12, 2025
9 checks passed

ros2-rust-release-plz bot mentioned this pull request Oct 12, 2025

chore: release v0.5.2 #527

Open

mxgrey deleted the worker_with_timers branch October 12, 2025 09:55

feat: timers API #480

feat: timers API #480

Uh oh!

Conversation

mxgrey commented May 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mxgrey commented Jun 29, 2025

Uh oh!

mxgrey commented Jun 29, 2025

Uh oh!

knmcguire commented Jun 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

knmcguire commented Jun 30, 2025

Uh oh!

jhdcs left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

knmcguire left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mxgrey commented Jul 17, 2025

Uh oh!

mxgrey commented Jul 17, 2025

Uh oh!

mxgrey commented Jul 18, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mxgrey Aug 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

esteve commented Aug 21, 2025

Uh oh!

mxgrey commented Aug 22, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

esteve left a comment

Choose a reason for hiding this comment

Uh oh!

esteve commented Oct 12, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

mxgrey commented May 14, 2025 •

edited

Loading

knmcguire commented Jun 30, 2025 •

edited

Loading

mxgrey Aug 10, 2025 •

edited

Loading