executor.hpp

Go to the documentation of this file.

// nros-cpp: Executor class
// Freestanding C++ — no exceptions, no STL required
 
#ifndef NROS_CPP_EXECUTOR_HPP
#define NROS_CPP_EXECUTOR_HPP
 
#include <cstdint>
#include <cstddef>
 
#include "nros/result.hpp"
#include "nros/nros_cpp_config_generated.h"
 
#include "nros_cpp_ffi.h"
 
namespace nros {
 
// Forward declarations
class Node;
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 `nros::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(Node& out, const char* name, const char* ns = nullptr);
 
    NodeBuilder node_builder(const char* name);
 
    Result spin_once(int32_t timeout_ms = 10) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(nros_cpp_spin_once(storage_, 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 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);
        Result last = Result::success();
        while (initialized_) {
            last = Result(nros_cpp_spin_once(storage_, poll_ms));
            if (!last.ok()) return last;
        }
        return last;
    }
 
    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 `nros::spin()` share one implementation.
        return Result(nros_cpp_spin_for(storage_, duration_ms, poll_ms));
    }
 
    [[deprecated("bounded spin is now `spin_for(duration_ms, poll_ms)`; "
                 "`spin()` blocks until shutdown, matching rclcpp (issue 0338)")]] Result
    spin(uint32_t duration_ms, int32_t poll_ms) {
        return spin_for(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 nros
 
#endif // NROS_CPP_EXECUTOR_HPP