qos.hpp

Go to the documentation of this file.

// nros-cpp: QoS (Quality of Service) profiles
// Freestanding C++ — no STL required
 
#ifndef NROS_CPP_QOS_HPP
#define NROS_CPP_QOS_HPP
 
#include <stdint.h>
 
// Phase 379 W5 — the deadline / lifespan / lease accessors take and return
// `nros::Duration`, so this header names it. `nros.hpp` includes `qos.hpp`
// before `duration.hpp`, so the dependency is spelled HERE rather than left to
// the umbrella's ordering: a header that names a type must be able to be
// included first.
#include "nros/duration.hpp"
 
// FFI struct definition — mirrors `nros_cpp_qos_t` in
// nros_cpp_ffi.h. Phase 118.D: guarded by `NROS_CPP_FFI_H`. If
// `nros_cpp_ffi.h` was included earlier (it sets that guard), the
// canonical types are already in scope; otherwise emit local
// definitions so this header stays self-contained for callers that
// don't pull the cbindgen header directly.
//
// The FIELD names below are ABI. `deadline_ms` / `lifespan_ms` /
// `liveliness_lease_ms` are `uint32_t` milliseconds and are mirrored again in
// `nros/component.h` (issue 0160, gated by `check-ffi-struct-mirrors`). The
// `_ms` suffix on a `QoS` METHOD was renamed in phase-379 W5; the suffix on a
// STRUCT FIELD was not, and must not be — the C ABI carries milliseconds.
#ifndef NROS_CPP_FFI_H
extern "C" {
enum nros_cpp_qos_reliability_t {
    NROS_CPP_QOS_RELIABLE = 0,
    NROS_CPP_QOS_BEST_EFFORT = 1,
};
enum nros_cpp_qos_durability_t {
    NROS_CPP_QOS_VOLATILE = 0,
    NROS_CPP_QOS_TRANSIENT_LOCAL = 1,
};
enum nros_cpp_qos_history_t {
    NROS_CPP_QOS_KEEP_LAST = 0,
    NROS_CPP_QOS_KEEP_ALL = 1,
};
enum nros_cpp_qos_liveliness_t {
    NROS_CPP_QOS_LIVELINESS_NONE = 0,
    NROS_CPP_QOS_LIVELINESS_AUTOMATIC = 1,
    NROS_CPP_QOS_LIVELINESS_MANUAL_BY_TOPIC = 2,
    NROS_CPP_QOS_LIVELINESS_MANUAL_BY_NODE = 3,
};
struct nros_cpp_qos_t {
    enum nros_cpp_qos_reliability_t reliability;
    enum nros_cpp_qos_durability_t durability;
    enum nros_cpp_qos_history_t history;
    enum nros_cpp_qos_liveliness_t liveliness_kind;
    int depth;
    uint32_t deadline_ms;
    uint32_t lifespan_ms;
    uint32_t liveliness_lease_ms;
    uint8_t avoid_ros_namespace_conventions;
    uint8_t tx_express;
};
}
#endif // NROS_CPP_FFI_H
 
namespace nros {
 
// -- Policy enums (phase 379 W5) ------------------------------------------
//
// At NAMESPACE scope and public, under rclcpp's names, because that is where a
// ported node looks for them (`rclcpp::ReliabilityPolicy`, `qos.hpp:34-58`).
// Three of these were PRIVATE members of `QoS` until phase-379 W5, which is why
// the getters had to hand back `int` — a public getter cannot name a private
// type. Ledger: `cpp:ReliabilityPolicy` and its three siblings.
//
// Two deliberate differences from rclcpp survive the rename, both ledgered:
//   * no `SystemDefault` — it means "defer to the middleware" and there is
//     none to defer to; the backend is linked at build time (RFC-0036).
//   * no `Unknown` — it is a discovery artefact for a policy read off a remote
//     endpoint, and we do no dynamic discovery.
//
// These are UNSCOPED enums, not rclcpp's `enum class`. Both spellings work as a
// result: `nros::Reliable` (ours, historical) and `nros::ReliabilityPolicy::
// Reliable` (rclcpp's). Switching to `enum class` would break the first and is
// its own decision, which no ledger row makes — see the qos.json rows.
 
enum ReliabilityPolicy {
    Reliable = 0,
    BestEffort = 1,
};
 
enum DurabilityPolicy {
    Volatile = 0,
    TransientLocal = 1,
};
 
enum HistoryPolicy {
    KeepLast = 0,
    KeepAll = 1,
};
 
enum LivelinessPolicy {
    LivelinessNone = 0,
    LivelinessAutomatic = 1,
    LivelinessManualByTopic = 2,
    LivelinessManualByNode = 3,
};
 
class QoS;
 
namespace detail {
 
constexpr uint32_t qos_window_ms(const Duration& d) {
    return d.nanoseconds() <= 0
               ? 0u
               : (d.nanoseconds() > static_cast<int64_t>(UINT32_MAX) * 1000000
                      ? UINT32_MAX
                      : static_cast<uint32_t>((d.nanoseconds() + 999999) / 1000000));
}
 
constexpr Duration qos_window_duration(uint32_t ms) {
    return Duration::from_nanoseconds(static_cast<int64_t>(ms) * 1000000);
}
 
} // namespace detail
 
class QoS {
  public:
    using Liveliness [[deprecated("QoS::Liveliness is deprecated; use nros::LivelinessPolicy")]] =
        LivelinessPolicy;
 
    // The four liveliness enumerators were reachable as `QoS::Liveliness*`
    // while the enum was a member. They still are, deprecated, so no source
    // that named one stops compiling. The enumerator SPELLING did not change —
    // only its scope — so `nros::LivelinessAutomatic` is the live name.
    [[deprecated("QoS::LivelinessNone is deprecated; use "
                 "nros::LivelinessNone")]] static constexpr LivelinessPolicy LivelinessNone =
        ::nros::LivelinessNone;
    [[deprecated(
        "QoS::LivelinessAutomatic is deprecated; use "
        "nros::LivelinessAutomatic")]] static constexpr LivelinessPolicy LivelinessAutomatic =
        ::nros::LivelinessAutomatic;
    [[deprecated("QoS::LivelinessManualByTopic is deprecated; use "
                 "nros::LivelinessManualByTopic")]] static constexpr LivelinessPolicy
        LivelinessManualByTopic = ::nros::LivelinessManualByTopic;
    [[deprecated(
        "QoS::LivelinessManualByNode is deprecated; use "
        "nros::LivelinessManualByNode")]] static constexpr LivelinessPolicy LivelinessManualByNode =
        ::nros::LivelinessManualByNode;
 
    constexpr QoS()
        : reliability_(Reliable), durability_(Volatile), history_(KeepLast),
          liveliness_(::nros::LivelinessAutomatic), depth_(10), deadline_ms_(0), lifespan_ms_(0),
          liveliness_lease_ms_(0), avoid_ros_namespace_conventions_(0), tx_express_(0) {}
 
    explicit constexpr QoS(int depth) : QoS() { depth_ = depth; }
 
    // -- Chainable setters (match rclcpp fluent API) --
 
    constexpr QoS& reliable() {
        reliability_ = Reliable;
        return *this;
    }
 
    constexpr QoS& best_effort() {
        reliability_ = BestEffort;
        return *this;
    }
 
    constexpr QoS& transient_local() {
        durability_ = TransientLocal;
        return *this;
    }
 
    constexpr QoS& durability_volatile() {
        durability_ = Volatile;
        return *this;
    }
 
    constexpr QoS& keep_last(int depth) {
        history_ = KeepLast;
        depth_ = depth;
        return *this;
    }
 
    constexpr QoS& keep_all() {
        history_ = KeepAll;
        return *this;
    }
 
    constexpr QoS& deadline(const Duration& d) {
        deadline_ms_ = detail::qos_window_ms(d);
        return *this;
    }
 
    constexpr QoS& lifespan(const Duration& d) {
        lifespan_ms_ = detail::qos_window_ms(d);
        return *this;
    }
 
    constexpr QoS& liveliness(LivelinessPolicy kind) {
        liveliness_ = kind;
        return *this;
    }
 
    constexpr QoS& liveliness_lease_duration(const Duration& d) {
        liveliness_lease_ms_ = detail::qos_window_ms(d);
        return *this;
    }
 
    constexpr QoS& avoid_ros_namespace_conventions(bool on) {
        avoid_ros_namespace_conventions_ = on ? 1 : 0;
        return *this;
    }
 
    constexpr QoS& tx_express(bool on) {
        tx_express_ = on ? 1 : 0;
        return *this;
    }
 
    // -- Deprecated millisecond setters (phase 379 W5) --
 
    [[deprecated("QoS::deadline_ms(uint32_t) is deprecated; use "
                 "QoS::deadline(nros::Duration)")]] constexpr QoS&
    deadline_ms(uint32_t ms) {
        deadline_ms_ = ms;
        return *this;
    }
 
    [[deprecated("QoS::lifespan_ms(uint32_t) is deprecated; use "
                 "QoS::lifespan(nros::Duration)")]] constexpr QoS&
    lifespan_ms(uint32_t ms) {
        lifespan_ms_ = ms;
        return *this;
    }
 
    [[deprecated("QoS::liveliness_lease_ms(uint32_t) is deprecated; use "
                 "QoS::liveliness_lease_duration(nros::Duration)")]] constexpr QoS&
    liveliness_lease_ms(uint32_t ms) {
        liveliness_lease_ms_ = ms;
        return *this;
    }
 
    // -- Predefined profiles (match rclcpp named constructors) --
 
    static constexpr QoS default_profile() { return QoS(); }
 
    static constexpr QoS sensor_data() { return QoS().best_effort().keep_last(5); }
 
    static constexpr QoS services() { return QoS().reliable(); }
 
    // -- Accessors --
 
    constexpr ReliabilityPolicy reliability() const { return reliability_; }
    constexpr DurabilityPolicy durability() const { return durability_; }
    constexpr HistoryPolicy history() const { return history_; }
    constexpr LivelinessPolicy liveliness() const { return liveliness_; }
    constexpr int depth() const { return depth_; }
    constexpr Duration deadline() const { return detail::qos_window_duration(deadline_ms_); }
    constexpr Duration lifespan() const { return detail::qos_window_duration(lifespan_ms_); }
    constexpr Duration liveliness_lease_duration() const {
        return detail::qos_window_duration(liveliness_lease_ms_);
    }
    constexpr bool avoid_ros_namespace_conventions() const {
        return avoid_ros_namespace_conventions_ != 0;
    }
    constexpr bool tx_express() const { return tx_express_ != 0; }
 
    // -- Deprecated accessors (phase 379 W5) --
    //
    // The `_raw()` four existed only because their enums were private; the
    // `_ms()` three only because C++ had no `Duration`. Both reasons are gone.
 
    [[deprecated("QoS::reliability_raw() is deprecated; use QoS::reliability()")]] constexpr int
    reliability_raw() const {
        return static_cast<int>(reliability_);
    }
    [[deprecated("QoS::durability_raw() is deprecated; use QoS::durability()")]] constexpr int
    durability_raw() const {
        return static_cast<int>(durability_);
    }
    [[deprecated("QoS::history_raw() is deprecated; use QoS::history()")]] constexpr int
    history_raw() const {
        return static_cast<int>(history_);
    }
    [[deprecated("QoS::liveliness_raw() is deprecated; use QoS::liveliness()")]] constexpr int
    liveliness_raw() const {
        return static_cast<int>(liveliness_);
    }
    [[deprecated("QoS::deadline_ms() is deprecated; use QoS::deadline()")]] constexpr uint32_t
    deadline_ms() const {
        return deadline_ms_;
    }
    [[deprecated("QoS::lifespan_ms() is deprecated; use QoS::lifespan()")]] constexpr uint32_t
    lifespan_ms() const {
        return lifespan_ms_;
    }
    [[deprecated("QoS::liveliness_lease_ms() is deprecated; use "
                 "QoS::liveliness_lease_duration()")]] constexpr uint32_t
    liveliness_lease_ms() const {
        return liveliness_lease_ms_;
    }
 
  private:
    // The private members keep their `_ms_` spelling: they hold exactly what
    // the C ABI carries (`uint32_t` milliseconds), and renaming them would say
    // the storage changed when only the accessors did.
    ReliabilityPolicy reliability_;
    DurabilityPolicy durability_;
    HistoryPolicy history_;
    LivelinessPolicy liveliness_;
    int depth_;
    uint32_t deadline_ms_;
    uint32_t lifespan_ms_;
    uint32_t liveliness_lease_ms_;
    uint8_t avoid_ros_namespace_conventions_;
    uint8_t tx_express_;
};
 
namespace detail {
 
constexpr nros_cpp_qos_t qos_to_ffi(const QoS& qos) {
    nros_cpp_qos_t f{};
    f.reliability = static_cast<nros_cpp_qos_reliability_t>(qos.reliability());
    f.durability = static_cast<nros_cpp_qos_durability_t>(qos.durability());
    f.history = static_cast<nros_cpp_qos_history_t>(qos.history());
    f.liveliness_kind = static_cast<nros_cpp_qos_liveliness_t>(qos.liveliness());
    f.depth = qos.depth();
    // The FFI FIELDS are milliseconds and keep their `_ms` names; only the
    // accessors changed. `qos_window_ms` is the exact inverse of the
    // `Duration` the getter built, so this round-trip loses nothing.
    f.deadline_ms = qos_window_ms(qos.deadline());
    f.lifespan_ms = qos_window_ms(qos.lifespan());
    f.liveliness_lease_ms = qos_window_ms(qos.liveliness_lease_duration());
    f.avoid_ros_namespace_conventions = qos.avoid_ros_namespace_conventions() ? 1 : 0;
    f.tx_express = qos.tx_express() ? 1 : 0;
    return f;
}
 
} // namespace detail
 
} // namespace nros
 
#endif // NROS_CPP_QOS_HPP