action_client.hpp

Go to the documentation of this file.

// nros-cpp: Action client class
// Freestanding C++ — no exceptions, no STL required
 
#ifndef NROS_CPP_ACTION_CLIENT_HPP
#define NROS_CPP_ACTION_CLIENT_HPP
 
#include <cstdint>
#include <cstddef>
#include <string.h>
 
#include "nros/config.hpp"
#include "nros/result.hpp"
#include "nros/size_bound.hpp" // nros::rx_buffer_capacity<M> — the receive-buffer size
#include "nros/future.hpp"
#include "nros/stream.hpp"
// Issue 0796 — `CancelReturnCode` (the `action_msgs/srv/CancelGoal` RPC status
// `cancel_goal` resolves to) is declared beside its per-goal sibling
// `CancelResponse` in action_server.hpp, which is also where
// polling_action_server.hpp reaches for them.
#include "nros/action_server.hpp"
 
// Phase 118.D: FFI declarations sourced from cbindgen-generated
// `nros_cpp_ffi.h`. cbindgen renders Rust `*const [u8; 16]` /
// `*mut [u8; 16]` parameters as C++ pointer-to-array
// (`const uint8_t (*goal_id)[16]`); member-function bodies below
// take `goal_id` as a 16-byte array (decays to `uint8_t*`) and
// `reinterpret_cast` at the call site to bridge the two ABI
// equivalent shapes.
#include "nros_cpp_ffi.h"
 
extern "C" {
typedef void (*nros_cpp_action_client_goal_response_callback_t)(bool accepted,
                                                                const uint8_t goal_id[16],
                                                                void* ctx);
typedef void (*nros_cpp_action_client_feedback_callback_t)(const uint8_t goal_id[16],
                                                           const uint8_t* data, size_t len,
                                                           void* ctx);
typedef void (*nros_cpp_action_client_result_callback_t)(const uint8_t goal_id[16], int32_t status,
                                                         const uint8_t* data, size_t len,
                                                         void* ctx);
 
nros_cpp_ret_t nros_cpp_action_client_set_callbacks(
    void* handle, nros_cpp_action_client_goal_response_callback_t goal_response,
    nros_cpp_action_client_feedback_callback_t feedback,
    nros_cpp_action_client_result_callback_t result, void* context);
} // extern "C"
 
namespace nros {
 
template <typename A> class ActionClient {
  public:
    using GoalType = typename A::Goal;
    using ResultType = typename A::Result;
    using FeedbackType = typename A::Feedback;
 
    struct GoalAccept {
        uint8_t goal_id[16];
        bool accepted;
 
        // Receive-buffer size for `Future<GoalAccept>`; the payload is 17 bytes
        // (16-byte goal_id + 1 accepted byte), rounded up.
        static const size_t SERIALIZED_SIZE_MAX = 32;
 
        // Issue 0329 — the 17-byte wire layout is owned Rust-side
        // (`nros_cpp_action_goal_accept_decode`, beside its producer); the header
        // no longer hand-decodes it, so the two cannot drift.
        static int ffi_deserialize(const uint8_t* data, size_t len, GoalAccept* out) {
            if (!out) return -1;
            return nros_cpp_action_goal_accept_decode(data, len, &out->goal_id, &out->accepted) ==
                           NROS_CPP_RET_OK
                       ? 0
                       : -1;
        }
    };
 
    Result wait_for_action_server(uint32_t timeout_ms = 5000) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(nros_cpp_action_client_wait_for_action_server(storage_, timeout_ms));
    }
 
    Result send_goal(const GoalType& goal, uint8_t goal_id[16]) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
 
        uint8_t buf[::nros::detail::buffer_bounds<GoalType>::tx];
        size_t len = 0;
        if (GoalType::ffi_serialize(&goal, buf, sizeof(buf), &len) != 0) {
            return Result(ErrorCode::Error);
        }
        return Result(nros_cpp_action_client_send_goal(storage_, buf, len,
                                                       reinterpret_cast<uint8_t(*)[16]>(goal_id)));
    }
 
    Result get_result(const uint8_t goal_id[16], ResultType& result) {
        return get_result_sized<::nros::rx_buffer_capacity<ResultType>::value>(goal_id, result);
    }
 
    template <size_t Cap> Result get_result_sized(const uint8_t goal_id[16], ResultType& result) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
 
        uint8_t buf[Cap];
        size_t len = 0;
        nros_cpp_ret_t ret = nros_cpp_action_client_get_result(
            storage_, executor_, reinterpret_cast<const uint8_t(*)[16]>(goal_id), buf, sizeof(buf),
            &len);
        if (ret != 0) return Result(ret);
 
        if (ResultType::ffi_deserialize(buf, len, &result) != 0) {
            return Result(ErrorCode::Error);
        }
        return Result::success();
    }
 
    // =================================================================
    // Future-based API — non-blocking, polled via Future<T>
    // =================================================================
 
    Future<GoalAccept> send_goal_future(const GoalType& goal) {
        if (!initialized_) return Future<GoalAccept>();
 
        uint8_t buf[::nros::detail::buffer_bounds<GoalType>::tx];
        size_t len = 0;
        if (GoalType::ffi_serialize(&goal, buf, sizeof(buf), &len) != 0) {
            return Future<GoalAccept>();
        }
 
        uint8_t goal_id[16];
        nros_cpp_ret_t ret = nros_cpp_action_client_send_goal_async(
            storage_, buf, len, reinterpret_cast<uint8_t(*)[16]>(goal_id));
        if (ret != 0) return Future<GoalAccept>();
 
        return Future<GoalAccept>(storage_, &nros_cpp_action_client_try_recv_goal_response,
                                  0 // slot 0 (single outstanding goal request)
        );
    }
 
    Future<ResultType> get_result_future(const uint8_t goal_id[16]) {
        return get_result_future_sized<::nros::rx_buffer_capacity<ResultType>::value>(goal_id);
    }
 
    template <size_t Cap>
    Future<ResultType, Cap> get_result_future_sized(const uint8_t goal_id[16]) {
        using Fut = Future<ResultType, Cap>;
        if (!initialized_) return Fut();
 
        nros_cpp_ret_t ret = nros_cpp_action_client_get_result_async(
            storage_, reinterpret_cast<const uint8_t(*)[16]>(goal_id));
        if (ret != 0) return Fut();
 
        return Fut(storage_, &nros_cpp_action_client_try_recv_result,
                   0 // slot 0 (single outstanding result request)
        );
    }
 
    Result try_recv_feedback(FeedbackType& feedback) {
        return try_recv_feedback_sized<::nros::rx_buffer_capacity<FeedbackType>::value>(feedback);
    }
 
    template <size_t Cap> Result try_recv_feedback_sized(FeedbackType& feedback) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
 
        uint8_t buf[Cap];
        size_t len = 0;
        nros_cpp_ret_t ret =
            nros_cpp_action_client_try_recv_feedback(storage_, buf, sizeof(buf), &len);
        if (ret != 0) return Result(ret);
        if (len == 0) return Result(ErrorCode::TryAgain);
        if (FeedbackType::ffi_deserialize(buf, len, &feedback) != 0) {
            return Result(ErrorCode::Error);
        }
        return Result::success();
    }
 
    Stream<FeedbackType>& feedback_stream() {
        if (initialized_ && !feedback_stream_.is_valid()) {
            feedback_stream_.bind(storage_, &nros_cpp_action_client_try_recv_feedback);
        }
        return feedback_stream_;
    }
 
    const Stream<FeedbackType>& feedback_stream() const { return feedback_stream_; }
 
    // =================================================================
    // Async (non-blocking) API — callbacks invoked during spin_once()
    // =================================================================
 
    struct SendGoalOptions {
        void (*goal_response)(bool accepted, const uint8_t goal_id[16], void* ctx);
        void (*feedback)(const uint8_t goal_id[16], const uint8_t* data, size_t len, void* ctx);
        void (*result)(const uint8_t goal_id[16], int32_t status, const uint8_t* data, size_t len,
                       void* ctx);
        void* context;
 
        SendGoalOptions() : goal_response(0), feedback(0), result(0), context(0) {}
    };
 
    Result send_goal_async(const GoalType& goal, uint8_t goal_id[16]) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
 
        uint8_t buf[::nros::detail::buffer_bounds<GoalType>::tx];
        size_t len = 0;
        if (GoalType::ffi_serialize(&goal, buf, sizeof(buf), &len) != 0) {
            return Result(ErrorCode::Error);
        }
        return Result(nros_cpp_action_client_send_goal_async(
            storage_, buf, len, reinterpret_cast<uint8_t(*)[16]>(goal_id)));
    }
 
    Result cancel_goal(const uint8_t goal_id[16]) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(nros_cpp_action_client_cancel_goal(
            storage_, reinterpret_cast<const uint8_t(*)[16]>(goal_id)));
    }
 
    Result try_recv_cancel_response(CancelReturnCode& out) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        int8_t code = 0;
        nros_cpp_ret_t ret = nros_cpp_action_client_try_recv_cancel_response(storage_, &code);
        if (ret != 0) return Result(ret);
        out = static_cast<CancelReturnCode>(code);
        return Result::success();
    }
 
    Result get_result_async(const uint8_t goal_id[16]) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(nros_cpp_action_client_get_result_async(
            storage_, reinterpret_cast<const uint8_t(*)[16]>(goal_id)));
    }
 
    Result set_callbacks(const SendGoalOptions& options) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(nros_cpp_action_client_set_callbacks(
            storage_, options.goal_response, options.feedback, options.result, options.context));
    }
 
    void poll() {
        if (!initialized_) return;
        nros_cpp_action_client_poll(storage_);
    }
 
    bool is_valid() const { return initialized_; }
 
    ~ActionClient() {
        if (initialized_) {
            nros_cpp_action_client_destroy(storage_);
            initialized_ = false;
        }
        feedback_stream_ = Stream<FeedbackType>();
    }
 
    // Move semantics (non-copyable). Relocation goes through the
    // `nros_cpp_action_client_relocate` runtime call (Phase 84.C1).
    // The feedback stream is rebound to the new storage afterwards.
    ActionClient(ActionClient&& other)
        : executor_(other.executor_), initialized_(other.initialized_) {
        if (other.initialized_) {
            nros_cpp_action_client_relocate(other.storage_, storage_);
            other.initialized_ = false;
        }
        other.feedback_stream_ = Stream<FeedbackType>();
    }
 
    ActionClient& operator=(ActionClient&& other) {
        if (this != &other) {
            if (initialized_) {
                nros_cpp_action_client_destroy(storage_);
                feedback_stream_ = Stream<FeedbackType>();
            }
            executor_ = other.executor_;
            initialized_ = other.initialized_;
            if (other.initialized_) {
                nros_cpp_action_client_relocate(other.storage_, storage_);
                other.initialized_ = false;
            }
            other.feedback_stream_ = Stream<FeedbackType>();
        }
        return *this;
    }
 
    ActionClient() : executor_(nullptr), initialized_(false) {}
 
  private:
    ActionClient(const ActionClient&) = delete;
    ActionClient& operator=(const ActionClient&) = delete;
 
    friend class Node;
 
    alignas(8) uint8_t storage_[NROS_CPP_ACTION_CLIENT_STORAGE_SIZE];
    void* executor_; // Stashed executor handle (Phase 82) for blocking helpers
    bool initialized_;
    Stream<FeedbackType> feedback_stream_;
    // Phase 87.6: action name buffer moved C++-side.
    char action_name_[256] = {};
};
 
} // namespace nros
 
// Phase 84.G8: out-of-line definition of Node::create_action_client<A>().
#include "nros/node.hpp"
 
namespace nros {
 
template <typename A>
Result Node::create_action_client(ActionClient<A>& out, const char* action_name, const QoS& qos) {
    if (!initialized_) return Result(ErrorCode::NotInitialized);
    nros_cpp_qos_t ffi_qos = detail::qos_to_ffi(qos);
    nros_cpp_ret_t ret = nros_cpp_action_client_create(&handle_, action_name, A::TYPE_NAME,
                                                       A::Goal::TYPE_HASH, ffi_qos, out.storage_);
    if (ret == 0) {
        // Phase 87.6: action_name buffer lives C++-side now.
        size_t name_len = 0;
        while (action_name[name_len] != '\0' && name_len + 1 < sizeof(out.action_name_)) {
            out.action_name_[name_len] = action_name[name_len];
            ++name_len;
        }
        out.action_name_[name_len] = '\0';
        out.executor_ = executor_handle_;
        out.initialized_ = true;
    }
    return Result(ret);
}
 
} // namespace nros
 
#endif // NROS_CPP_ACTION_CLIENT_HPP