timer.hpp

Go to the documentation of this file.

// nros-cpp: Timer class
// Freestanding C++ — no exceptions, no STL required

 
#ifndef NROS_RCLCPP_TIMER_HPP
#define NROS_RCLCPP_TIMER_HPP
 
#include <cstdint>
#include <cstddef>
 
#include "rclcpp/result.hpp"
#include "rclcpp/detail/hosted_block.hpp"
// phase-417 G6 — `time_until_trigger()` returns `rclcpp::Duration`, so this
// header NAMES it and must be includable first (the rule `qos.hpp` states for
// the same dependency). `duration.hpp` includes nothing of ours.
#include "rclcpp/duration.hpp"
 
// phase-476 W2 — nothing in this header is hosted-only any more: the pointer
// aliases name `TimerHandle` rather than `std::shared_ptr`, and the callable
// lives in the executor arena rather than a `std::function` cell. So it
// includes no capability probe.
 
#include "rclcpp/detail/nros_cpp_ffi.h"
// issue 1975 -- `get_clock()` returns the clock the timer runs on. AFTER
// `nros_cpp_ffi.h`, the order `node.hpp` already includes the two in.
#include "rclcpp/clock.hpp"
// issue 1974 -- `TimerInfoCallbackType` is an `InplaceFn`.
#include "rclcpp/inplace_fn.hpp"
 
// phase-427 W7 — `Node` is DEFINED in `rclcpp::` (RFC-0089: that namespace is
// the home). The friend declaration below is qualified, and a qualified friend
// names an existing entity rather than introducing one, so the name has to be
// declared first, in `rclcpp::`.
namespace rclcpp {
class Node;
}
 
namespace rclcpp {
 
class Timer;
 
namespace detail {
inline ClockValuePtr timer_clock(void* executor, size_t handle_id) {
    uint8_t clock_type = static_cast<uint8_t>(RCL_CLOCK_UNINITIALIZED);
    if (executor == nullptr ||
        nros_cpp_timer_get_clock_type(executor, handle_id, &clock_type) != NROS_CPP_RET_OK) {
        clock_type = static_cast<uint8_t>(RCL_CLOCK_UNINITIALIZED);
    }
    return ClockValuePtr(static_cast<rcl_clock_type_t>(clock_type));
}
} // namespace detail

class TimerOps {
  public:
#if defined(NROS_CPP_STD) // hosted-family: ported-publish
    ::rclcpp::detail::StatementResult cancel() {
#else
    Result cancel() {
#endif
        return Result(nros_cpp_timer_cancel(executor_, handle_id_));
    }

#if defined(NROS_CPP_STD) // hosted-family: ported-publish
    ::rclcpp::detail::StatementResult reset() {
#else
    Result reset() {
#endif
        return Result(nros_cpp_timer_reset(executor_, handle_id_));
    }

    bool is_canceled() const {
        return executor_ == nullptr || nros_cpp_timer_is_canceled(executor_, handle_id_);
    }

    bool is_ready() const {
        return executor_ != nullptr && nros_cpp_timer_is_ready(executor_, handle_id_);
    }

    Duration time_until_trigger() const {
        int64_t ns = 0;
        if (executor_ == nullptr ||
            nros_cpp_timer_time_until_next_call_ns(executor_, handle_id_, &ns) != NROS_CPP_RET_OK) {
            return Duration();
        }
        return Duration::from_nanoseconds(ns);
    }

    detail::ClockValuePtr get_clock() const { return detail::timer_clock(executor_, handle_id_); }
 
  protected:
    constexpr TimerOps(void* executor, size_t handle_id)
        : executor_(executor), handle_id_(handle_id) {}
 
    void* executor_;
    size_t handle_id_;
};

class TimerHandle : private TimerOps {
  public:
    using element_type = ::rclcpp::Timer;
 
    constexpr TimerHandle() : TimerOps(nullptr, 0) {}
    constexpr TimerHandle(decltype(nullptr)) : TimerOps(nullptr, 0) {}
    constexpr TimerHandle(void* executor, size_t handle_id) : TimerOps(executor, handle_id) {}

    explicit constexpr operator bool() const { return executor_ != nullptr; }

    TimerOps* operator->() { return this; }
    const TimerOps* operator->() const { return this; }

    void reset() {
        if (executor_ != nullptr) {
            (void)nros_cpp_timer_release(executor_, handle_id_);
        }
        executor_ = nullptr;
        handle_id_ = 0;
    }

    constexpr size_t handle_id() const { return handle_id_; }
 
    friend constexpr bool operator==(const TimerHandle& a, const TimerHandle& b) {
        return a.executor_ == b.executor_ && a.handle_id_ == b.handle_id_;
    }
    friend constexpr bool operator!=(const TimerHandle& a, const TimerHandle& b) {
        return !(a == b);
    }
    friend constexpr bool operator==(const TimerHandle& a, decltype(nullptr)) {
        return a.executor_ == nullptr;
    }
    friend constexpr bool operator!=(const TimerHandle& a, decltype(nullptr)) {
        return a.executor_ != nullptr;
    }
    friend constexpr bool operator==(decltype(nullptr), const TimerHandle& a) {
        return a.executor_ == nullptr;
    }
    friend constexpr bool operator!=(decltype(nullptr), const TimerHandle& a) {
        return a.executor_ != nullptr;
    }
};

class Timer {
  public:
    using SharedPtr = ::rclcpp::TimerHandle;
    using ConstSharedPtr = ::rclcpp::TimerHandle;
    using UniquePtr = ::rclcpp::TimerHandle;

#if defined(NROS_CPP_STD) // hosted-family: ported-publish
    ::rclcpp::detail::StatementResult cancel() {
#else
    Result cancel() {
#endif
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(nros_cpp_timer_cancel(executor_, handle_id_));
    }

#if defined(NROS_CPP_STD) // hosted-family: ported-publish
    ::rclcpp::detail::StatementResult reset() {
#else
    Result reset() {
#endif
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(nros_cpp_timer_reset(executor_, handle_id_));
    }

    bool is_canceled() const {
        if (!initialized_) return true;
        return nros_cpp_timer_is_canceled(executor_, handle_id_);
    }

    bool is_ready() const {
        if (!initialized_) return false;
        return nros_cpp_timer_is_ready(executor_, handle_id_);
    }

    Duration time_until_trigger() const {
        if (!initialized_) return Duration();
        int64_t ns = 0;
        if (nros_cpp_timer_time_until_next_call_ns(executor_, handle_id_, &ns) != NROS_CPP_RET_OK) {
            return Duration();
        }
        return Duration::from_nanoseconds(ns);
    }

    detail::ClockValuePtr get_clock() const {
        return detail::timer_clock(initialized_ ? executor_ : nullptr, handle_id_);
    }

    bool is_valid() const { return initialized_; }

    ~Timer() {
        if (initialized_) {
            nros_cpp_timer_cancel(executor_, handle_id_);
            initialized_ = false;
        }
        // The closure block (if any) is freed here; the runtime no longer
        // holds a raw pointer into it because we cancelled above.
        detail::destroy_hosted_block(closure_);
    }
 
    // Move semantics (non-copyable)
    Timer(Timer&& other)
        : executor_(other.executor_), handle_id_(other.handle_id_),
          initialized_(other.initialized_), closure_(other.closure_) {
        other.executor_ = nullptr;
        other.initialized_ = false;
        other.closure_ = nullptr;
    }
 
    Timer& operator=(Timer&& other) {
        if (this != &other) {
            if (initialized_) {
                nros_cpp_timer_cancel(executor_, handle_id_);
            }
            executor_ = other.executor_;
            handle_id_ = other.handle_id_;
            initialized_ = other.initialized_;
            detail::destroy_hosted_block(closure_);
            closure_ = other.closure_;
            other.executor_ = nullptr;
            other.initialized_ = false;
            other.closure_ = nullptr;
        }
        return *this;
    }

    Timer() : executor_(nullptr), handle_id_(0), initialized_(false), closure_(nullptr) {}

    void attach_closure_block(detail::HostedBlockBase* block) {
        detail::destroy_hosted_block(closure_);
        closure_ = block;
    }
 
  private:
    Timer(const Timer&) = delete;
    Timer& operator=(const Timer&) = delete;
 
    friend class ::rclcpp::Node;
 
    void* executor_;
    size_t handle_id_;
    bool initialized_;

    void* closure_;
};
 
} // namespace rclcpp
 
// ============================================================================
// rclcpp::Timer — FLAT. No `TimerBase`, no hierarchy (phase-430 W7 ruling)
// ============================================================================
//
// RFC-0089 §"Timer, studied against RTOS semantics" decided this and the tree
// disagreed with it: phase-417 W1.a had landed `class TimerBase` with a virtual
// destructor and `detail::WallTimer : TimerBase` under it — exactly the
// hierarchy the RFC refused. phase-430 W7 called for a ruling either way. The
// ruling is DELETE, and it is argued from the executor's dispatch:
//
//   1. THE VTABLE HAS NO CALLER. The only virtual member was `~TimerBase()`,
//      and there is no virtual call through a `TimerBase*` anywhere in the
//      tree — there cannot be. The executor's callback slot is
//      `nros_cpp_timer_callback_t`, a raw `void(*)(void*)`, and dispatch goes
//      through the STATIC `detail::WallTimer::trampoline`. The executor never
//      holds a C++ timer object, so it never needs a type-erased base. Even
//      the destructor's virtuality was dead: the cell is built with
//      `std::make_shared<detail::WallTimer>()`, so the control block already
//      records the CONCRETE deleter and destruction through a base pointer was
//      correct without it. A vtable no dispatch uses is cost with no caller,
//      which is what clause 1 of the governing principle refuses.
//
//   2. THE NAME PROMISES CHILDREN WE REFUSE TO HAVE. `WallTimer` and
//      `GenericTimer` are upstream's siblings under `TimerBase`, and both stay
//      absent by decision: the clock axis is a RUNTIME FIELD on the flat timer
//      plus a second VERB (`create_timer(clock, …)` beside `create_wall_timer`),
//      never a type parameter — phase-425 landed ROS time in exactly that
//      shape. A base whose one leaf is `detail::`-private advertises a taxonomy
//      the header itself refuses two paragraphs later.
//
//   3. THE FLAT SHAPE IS A STRICTLY BETTER KEEP-ALIVE. `create_wall_timer`
//      returned `std::shared_ptr<::rclcpp::Timer>` aliased onto a private cell,
//      as `create_subscription` did. Since phase-476 W2 both return a two-word
//      handle and there is no cell: the callable is in the executor arena.
//
// The migration cost is one mechanical rename the compiler demands:
// `rclcpp::TimerBase::SharedPtr timer_;` becomes `rclcpp::Timer::SharedPtr
// timer_;`. That is the compile-or-conform rule working as designed, and it is
// what the RFC calls the honest outcome — we do not have the hierarchy, so we
// do not take the name for it. Zero non-test call sites in this tree used it.
//
// `rclcpp::Timer` is an ours-only name in upstream's namespace (RFC-0089
// §"Settled: `nros::` is phased out entirely"), so it carries a ledger row with
// `disposition: extension` and the collision gate watches for `rclcpp::Timer`
// appearing in the recorded upstream surface.
//
// ADOPT-BOUNDED, and both halves of the envelope come with the executor:
//
//   * PERIOD RESOLUTION IS ONE MILLISECOND. `nros_cpp_timer_create` takes a
//     `uint64_t period_ms`, so `create_wall_timer(500us, …)` truncates to 0 and
//     fires every spin. Activations land on spin boundaries either way, so the
//     achievable cadence was already the spin period — the truncation only
//     makes the floor explicit.
//   * MISSED DEADLINES CATCH UP, where rcl's DROP. `TimerState::fire` keeps the
//     overshoot (`elapsed_ms -= period_ms`, `nros-node/src/timer.rs:298`), so
//     after a stall the callback runs once per `spin_once` until the backlog is
//     drained and the mean cadence is preserved. `rcl_timer_call` instead skips
//     whole missed periods and re-phases onto the grid, firing once. Closing
//     the gap means a missed-deadline POLICY on the executor's timer —
//     Rust-side work, not a loop re-added here (issue 1041).
//
// phase-417 — ONE DISPATCH PATH. `create_wall_timer` registers an EXECUTOR
// timer via `rclcpp::Node::create_wall_timer` (`node.hpp`), so the period
// arithmetic, the missed-deadline policy and the clock are the executor's,
// Rust-side. Until this landed, `WallTimer` carried its own
// `std::chrono::steady_clock` deadline and a `Node::pump()` fired it from
// `rclcpp::spin` / `spin_some` ONLY. Scheduling in the wrapper is
// RFC-0019/RFC-0020 violation class 2. Do not reintroduce a second dispatch
// loop.
 
namespace rclcpp {

using TimerBase = ::rclcpp::Timer;

struct TimerInfo {
    Time expected_call_time;
    Time actual_call_time;
};

using TimerInfoCallbackType = InplaceFn<void(const TimerInfo&)>;
 
// phase-476 W2 deleted `detail::WallTimer`, the heap cell (a `std::function`
// plus an `rclcpp::Timer`) that gave a capturing timer callback a stable address
// and that the node kept alive through ~~`owned_entities`~~. The callable now lives
// in the executor arena (`nros_cpp_timer_create_capturing`), destroyed when the
// timer is released, and the returned handle is two words.
 
} // namespace rclcpp
 
#endif // NROS_RCLCPP_TIMER_HPP