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;
}
 
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 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 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