executor.hpp

Go to the documentation of this file.

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

 
#ifndef NROS_RCLCPP_EXECUTOR_HPP
#define NROS_RCLCPP_EXECUTOR_HPP
 
#include <cstdint>
#include <cstddef>
 
#include "rclcpp/result.hpp"
// phase-417 stage 3 — the refusal vocabulary (`NROS_RCLCPP_REFUSE_*`,
// `rclcpp::detail::refuse`, `rclcpp::detail::log_handle`) and the routed
// `NROS_LOG_*` family both live here. `log.hpp` includes nothing of ours but
// `std_detect.hpp`, so this cannot cycle.
#include "rclcpp/logging.hpp"
#include "rclcpp/detail/nros_cpp_config_generated.h"
 
#include "rclcpp/detail/nros_cpp_ffi.h"
 
// phase-427 W7 — `Node` is DEFINED in `rclcpp::` (RFC-0089: that namespace is
// the home), so the forward declaration has to be there too.
namespace rclcpp {
class Node;
// phase-515 P1 -- defined in `rclcpp.hpp`; `Executor::spin_until_future_complete`
// returns it. Opaque scoped-enum declaration, underlying type `int` as there.
enum class FutureReturnCode;
} // namespace rclcpp
 
namespace rclcpp {
 
// Forward declarations
class NodeBuilder;

using ShutdownCallback = void (*)(void* context);

class ShutdownCallbackHandle {
  public:
    ShutdownCallbackHandle() : value_(NROS_CPP_SHUTDOWN_CALLBACK_HANDLE_INVALID) {}

    explicit ShutdownCallbackHandle(nros_cpp_shutdown_callback_handle_t value) : value_(value) {}

    bool valid() const { return value_ != NROS_CPP_SHUTDOWN_CALLBACK_HANDLE_INVALID; }

    nros_cpp_shutdown_callback_handle_t value() const { return value_; }
 
  private:
    nros_cpp_shutdown_callback_handle_t value_;
};

class PreShutdownCallbackHandle : public ShutdownCallbackHandle {
  public:
    using ShutdownCallbackHandle::ShutdownCallbackHandle;
};

class OnShutdownCallbackHandle : public ShutdownCallbackHandle {
  public:
    using ShutdownCallbackHandle::ShutdownCallbackHandle;
};

class Executor {
  public:
    Executor() : storage_(), initialized_(false) {}

    static Result create(Executor& out, const char* locator = nullptr, uint8_t domain_id = 0) {
        return create(out, locator, domain_id, "nros_cpp");
    }

    static Result create(Executor& out, const char* locator, uint8_t domain_id,
                         const char* session_name) {
        // -3 = NROS_CPP_RET_INVALID_ARGUMENT (generated header).
        if (session_name == nullptr) {
            return Result(-3);
        }
        // Issue 1050 defect (3) — the same baked RMW selector `rclcpp::init()`
        // reads. Both spellings of "open the one session" must apply it, or the
        // bake means one thing on one path and nothing on the other — which is
        // how `BACKENDS` came to read as a declaration that decided nothing.
#ifdef NROS_ENTRY_RMW
        const char* rmw = NROS_ENTRY_RMW;
#else
        const char* rmw = nullptr;
#endif
        nros_cpp_ret_t ret =
            nros_cpp_init_rmw(rmw, locator, domain_id, session_name, nullptr, out.storage_);
        if (ret == 0) {
            out.initialized_ = true;
        }
        return Result(ret);
    }

    static Result create_with_rmw(Executor& out, const char* rmw, const char* locator = nullptr,
                                  uint8_t domain_id = 0, const char* session_name = "nros_cpp") {
        if (session_name == nullptr) {
            return Result(-3);
        }
        nros_cpp_ret_t ret =
            nros_cpp_init_rmw(rmw, locator, domain_id, session_name, nullptr, out.storage_);
        if (ret == 0) {
            out.initialized_ = true;
        }
        return Result(ret);
    }

    Result create_node(::rclcpp::Node& out, const char* name, const char* ns = nullptr);

    NodeBuilder node_builder(const char* name);

    Result spin_once(int32_t timeout_ms) {
        // FIRST, before the `initialized_` check: the defect is in the VALUE,
        // so it is knowable without a session and a caller must not have to
        // stand one up to be told (RFC-0089 §"Where the refusal fires"). It
        // used to be `timeout_ms.max(0)` Rust-side, which turned upstream's
        // "block forever" into a 0 ms poll with no diagnostic at all.
        //
        // `NROS_RCLCPP_SAY_REFUSED`, not the legacy `NROS_ERROR`: the legacy
        // sink is a no-op on every freestanding target, and a refusal nobody
        // can read on the targets nano-ros exists for is issue 1019 again. It
        // is also not the `"%s"` printf path, whose 256-byte buffer would cut
        // the message off before the alternative.
        if (timeout_ms < 0) {
            NROS_RCLCPP_SAY_REFUSED(NROS_RCLCPP_REFUSE_UNBOUNDED_SPIN_RUNTIME);
            return Result(ErrorCode::Unsupported);
        }
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(nros_cpp_spin_once(storage_, timeout_ms));
    }

    template <typename T = void> Result spin_once() {
        static_assert(::rclcpp::detail::refuse<T>::value, NROS_RCLCPP_REFUSE_UNBOUNDED_SPIN);
        return Result(ErrorCode::Unsupported);
    }

    Result spin_some(uint32_t max_ms = 0) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(nros_cpp_spin_some(storage_, max_ms));
    }

    Result spin_all(uint32_t max_duration_ms) {
        if (max_duration_ms == 0) return Result(ErrorCode::InvalidArgument);
        return spin_some(max_duration_ms);
    }

    template <typename Future>
    FutureReturnCode spin_until_future_complete(Future&& future, int32_t timeout_ms = -1);

    template <typename NodePtr> void add_node(const NodePtr& node, bool notify = true);

    template <typename NodePtr, typename T = void>
    void remove_node(const NodePtr& node, bool notify = true) {
        (void)node;
        (void)notify;
        static_assert(::rclcpp::detail::refuse<T>::value, NROS_RCLCPP_REFUSE_REMOVE_NODE);
    }

    template <typename NodePtr> Result spin_node_some(const NodePtr& node) {
        add_node(node);
        return spin_some();
    }

    template <typename NodePtr> Result spin_node_once(const NodePtr& node, int32_t timeout_ms) {
        add_node(node);
        return spin_once(timeout_ms);
    }

    Result ping(int32_t timeout_ms) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(nros_cpp_executor_ping(storage_, timeout_ms));
    }

    Result get_node_names(nros_cpp_node_visit_fn visit, void* ctx) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(nros_cpp_executor_get_node_names(storage_, visit, ctx));
    }

    Result get_topic_names_and_types(nros_cpp_names_and_types_visit_fn visit, void* ctx) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(nros_cpp_executor_get_topic_names_and_types(storage_, visit, ctx));
    }

    Result get_service_names_and_types(nros_cpp_names_and_types_visit_fn visit, void* ctx) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(nros_cpp_executor_get_service_names_and_types(storage_, visit, ctx));
    }

    Result count_publishers(const char* topic_name, size_t* out_count) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(nros_cpp_executor_count_publishers(storage_, topic_name, out_count));
    }

    Result count_subscribers(const char* topic_name, size_t* out_count) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(nros_cpp_executor_count_subscribers(storage_, topic_name, out_count));
    }

    Result count_clients(const char* service_name, size_t* out_count) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(nros_cpp_executor_count_clients(storage_, service_name, out_count));
    }

    Result count_services(const char* service_name, size_t* out_count) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(nros_cpp_executor_count_services(storage_, service_name, out_count));
    }

    Result get_publisher_names_and_types_by_node(const char* node_name, const char* node_namespace,
                                                 nros_cpp_names_and_types_visit_fn visit,
                                                 void* ctx) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(nros_cpp_executor_get_publisher_names_and_types_by_node(
            storage_, node_name, node_namespace, visit, ctx));
    }

    Result get_subscription_names_and_types_by_node(const char* node_name,
                                                    const char* node_namespace,
                                                    nros_cpp_names_and_types_visit_fn visit,
                                                    void* ctx) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(nros_cpp_executor_get_subscription_names_and_types_by_node(
            storage_, node_name, node_namespace, visit, ctx));
    }

    Result get_service_names_and_types_by_node(const char* node_name, const char* node_namespace,
                                               nros_cpp_names_and_types_visit_fn visit, void* ctx) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(nros_cpp_executor_get_service_names_and_types_by_node(
            storage_, node_name, node_namespace, visit, ctx));
    }

    Result get_client_names_and_types_by_node(const char* node_name, const char* node_namespace,
                                              nros_cpp_names_and_types_visit_fn visit, void* ctx) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(nros_cpp_executor_get_client_names_and_types_by_node(
            storage_, node_name, node_namespace, visit, ctx));
    }

    Result get_publishers_info_by_topic(const char* topic_name,
                                        nros_cpp_endpoint_info_visit_fn visit, void* ctx) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(
            nros_cpp_executor_get_publishers_info_by_topic(storage_, topic_name, visit, ctx));
    }

    Result get_subscriptions_info_by_topic(const char* topic_name,
                                           nros_cpp_endpoint_info_visit_fn visit, void* ctx) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(
            nros_cpp_executor_get_subscriptions_info_by_topic(storage_, topic_name, visit, ctx));
    }

    Result spin(int32_t poll_ms = 10) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(nros_cpp_spin(storage_, poll_ms));
    }

    Result cancel() {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(nros_cpp_executor_cancel(storage_));
    }

    bool is_spinning() const {
        return nros_cpp_executor_is_spinning(const_cast<uint8_t*>(storage_));
    }

    Result spin_for(uint32_t duration_ms, int32_t poll_ms = 10) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        // Issue 0329 — the wall-clock budgeted loop (Phase 118.C: iteration-count
        // budgeting collapses when `spin_once` returns early on a signaled
        // condvar) now lives once, Rust-side, in `nros_cpp_spin_for`; forward to
        // it so this and `rclcpp::spin()` share one implementation.
        return Result(nros_cpp_spin_for(storage_, duration_ms, poll_ms));
    }

    bool ok() const { return initialized_; }

    void* handle() { return storage_; }

    Result add_pre_shutdown_callback(ShutdownCallback callback, void* context = nullptr,
                                     PreShutdownCallbackHandle* out = nullptr) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        nros_cpp_shutdown_callback_handle_t raw = NROS_CPP_SHUTDOWN_CALLBACK_HANDLE_INVALID;
        nros_cpp_ret_t ret = nros_cpp_add_pre_shutdown_callback(storage_, callback, context, &raw);
        if (out != nullptr) *out = PreShutdownCallbackHandle(raw);
        return Result(ret);
    }

    Result add_on_shutdown_callback(ShutdownCallback callback, void* context = nullptr,
                                    OnShutdownCallbackHandle* out = nullptr) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        nros_cpp_shutdown_callback_handle_t raw = NROS_CPP_SHUTDOWN_CALLBACK_HANDLE_INVALID;
        nros_cpp_ret_t ret = nros_cpp_add_on_shutdown_callback(storage_, callback, context, &raw);
        if (out != nullptr) *out = OnShutdownCallbackHandle(raw);
        return Result(ret);
    }

    bool remove_pre_shutdown_callback(PreShutdownCallbackHandle handle) {
        if (!initialized_) return false;
        return nros_cpp_remove_pre_shutdown_callback(storage_, handle.value()) == 0;
    }

    bool remove_on_shutdown_callback(OnShutdownCallbackHandle handle) {
        if (!initialized_) return false;
        return nros_cpp_remove_on_shutdown_callback(storage_, handle.value()) == 0;
    }

    Result shutdown() {
        if (!initialized_) return Result::success();
        nros_cpp_ret_t ret = nros_cpp_fini(storage_);
        initialized_ = false;
        return Result(ret);
    }

    ~Executor() {
        if (initialized_) {
            nros_cpp_fini(storage_);
            initialized_ = false;
        }
    }
 
    // Move semantics (non-copyable)
    Executor(Executor&& other) : initialized_(other.initialized_) {
        for (unsigned i = 0; i < sizeof(storage_); ++i) {
            storage_[i] = other.storage_[i];
            other.storage_[i] = 0;
        }
        other.initialized_ = false;
    }
 
    Executor& operator=(Executor&& other) {
        if (this != &other) {
            if (initialized_) {
                nros_cpp_fini(storage_);
            }
            for (unsigned i = 0; i < sizeof(storage_); ++i) {
                storage_[i] = other.storage_[i];
                other.storage_[i] = 0;
            }
            initialized_ = other.initialized_;
            other.initialized_ = false;
        }
        return *this;
    }
 
  private:
    Executor(const Executor&) = delete;
    Executor& operator=(const Executor&) = delete;
 
    alignas(8) uint8_t storage_[NROS_CPP_EXECUTOR_STORAGE_SIZE];
    bool initialized_;
};
 
} // namespace rclcpp
 
#endif // NROS_RCLCPP_EXECUTOR_HPP