rclcpp::Timer Class Reference

#include <timer.hpp>

Public Types
using	ConstSharedPtr = ::rclcpp::TimerHandle
	Timer::ConstSharedPtr — the same handle; see SharedPtr.
using	SharedPtr = ::rclcpp::TimerHandle
using	UniquePtr = ::rclcpp::TimerHandle

Public Member Functions
void	attach_closure_block (detail::HostedBlockBase *block)
Result	cancel ()
bool	is_canceled () const
	Check if the timer is cancelled.
bool	is_ready () const
bool	is_valid () const
	Check if the timer is initialized and valid.
Timer &	operator= (Timer &&other)
Result	reset ()
Duration	time_until_trigger () const
	Timer ()
	Timer (Timer &&other)
	~Timer ()
	Destructor — cancels the timer.

Friends
class	::rclcpp::Node

Detailed Description

Repeating or one-shot timer registered with the executor.

Timers fire during spin_once() when their period has elapsed. The callback is a C function pointer with a user context.

Usage:

void on_timer(void* ctx) { /* periodic work *‍/ }
 
rclcpp::Timer timer;
RCLCPP_TRY(node.create_wall_timer(timer, 1000, on_timer));  // 1000ms period
// timer fires during rclcpp::spin_once()
timer.cancel();
timer.reset();  // restart from zero

Member Typedef Documentation

ConstSharedPtr

using rclcpp::Timer::ConstSharedPtr = ::rclcpp::TimerHandle

Timer::ConstSharedPtr — the same handle; see SharedPtr.

SharedPtr

using rclcpp::Timer::SharedPtr = ::rclcpp::TimerHandle

Timer::SharedPtr — how a timer member is declared: rclcpp::Timer::SharedPtr timer_; (or rclcpp::TimerBase::SharedPtr, the alias below).

phase-476 W2 — a [TimerHandle], not a std::shared_ptr<Timer>, and UNCONDITIONAL: the timer's callable lives in the executor arena, so the C++ side owns nothing a smart pointer could hold, and a freestanding target gets the ported spelling too. See TimerHandle for what differs from a shared_ptr (it does not own the timer; .reset() releases it).

UniquePtr

using rclcpp::Timer::UniquePtr = ::rclcpp::TimerHandle

Timer::UniquePtr — the same handle; see SharedPtr. Upstream's is a sole owner. This one owns nothing, like the other two spellings.

Constructor & Destructor Documentation

~Timer()

rclcpp::Timer::~Timer ( )

inline

Destructor — cancels the timer.

Timer() [1/2]

rclcpp::Timer::Timer ( Timer &&  other )

inline

Timer() [2/2]

rclcpp::Timer::Timer ( )

inline

Default constructor — creates an uninitialized timer. Use Node::create_wall_timer() to initialize.

Member Function Documentation

attach_closure_block()

void rclcpp::Timer::attach_closure_block ( detail::HostedBlockBase *  block )

inline

cancel()

Result rclcpp::Timer::cancel ( )

inline

Cancel the timer. It stops firing but remains in the executor. Use reset() to restart it.

is_canceled()

bool rclcpp::Timer::is_canceled ( ) const

inline

Check if the timer is cancelled.

is_ready()

bool rclcpp::Timer::is_ready ( ) const

inline

Would this timer fire on the next spin_once() pass? — rclcpp's TimerBase::is_ready().

phase-417 G6. The answer is the EXECUTOR's, read from the arena entry the timer is registered in: a cancelled timer is never ready, a fired one-shot is never ready again, and otherwise elapsed >= period. That is arena::timer_try_process's own guard rather than a second opinion about it — a readiness answer that can disagree with the dispatcher is worse than no answer.

An uninitialized timer answers false: it is registered with no executor, so nobody will dispatch it.

is_valid()

bool rclcpp::Timer::is_valid ( ) const

inline

Check if the timer is initialized and valid.

operator=()

Timer & rclcpp::Timer::operator= ( Timer &&  other )

inline

reset()

Result rclcpp::Timer::reset ( )

inline

Reset the timer (restart from zero elapsed time). If cancelled, this also un-cancels it.

time_until_trigger()

Duration rclcpp::Timer::time_until_trigger ( ) const

inline

Time until this timer next fires — NEGATIVE when it is overdue. rclcpp's TimerBase::time_until_trigger().

phase-417 G6. Two deliberate differences from rclcpp, both recorded on the ledger row:

• upstream returns std::chrono::nanoseconds; this returns [rclcpp::Duration], because this header is freestanding and <chrono> is not reachable from every target it serves (issue 0112). The UNIT is the same — d.nanoseconds() is upstream's count.
• the arena's timer accounting is MICROSECOND-based (issue #505), so the nanosecond value is a microsecond quantity scaled by 1000. The unit is rclcpp's; the resolution is ours.

A wall timer answers on the platform steady clock; a timer created with create_timer(clock, …) answers on its own clock.

Duration() (zero) for an uninitialized timer or one the executor does not know. That collides with "fires exactly now", which is why [is_valid] is the question to ask first — the C surface spends a return code on the distinction (rcl_timer_get_time_until_next_call answers RCL_RET_NOT_INIT) and a Duration-returning accessor has no room for one.

Friends And Related Symbol Documentation

::rclcpp::Node

friend class ::rclcpp::Node

friend

---

The documentation for this class was generated from the following file:

• include/rclcpp/timer.hpp