client.hpp

Go to the documentation of this file.

// nros-cpp: the DISPATCH service client
// Freestanding C++ -- no exceptions, no STL required

 
#ifndef NROS_RCLCPP_CLIENT_HPP
#define NROS_RCLCPP_CLIENT_HPP
 
#include <cstdint>
#include <cstddef>
 
#include "rclcpp/detail/callback_context.hpp" // phase-456 W3 — the handler IS the arena context
#include "rclcpp/client_handle.hpp"           // phase-456 W9 — what `Client<S>::SharedPtr` IS
#include "rclcpp/detail/config.hpp"
#include "rclcpp/detail/entity_name.hpp" // phase-444 — the one entity-name copy
#include "rclcpp/logging.hpp" // phase-417 stage 3 — NROS_RCLCPP_REFUSE_* + rclcpp::detail::refuse
#include "rclcpp/result.hpp"
#include "rclcpp/size_bound.hpp" // rclcpp::detail::buffer_bounds<M>::tx — the request scratch bound
 
#include "rclcpp/detail/nros_cpp_ffi.h"
#include "rclcpp/detail/driven_future.hpp" // issue 2055 — `Client<S>::SharedFuture`
 
// issue 1437 — `get_actual_qos()` returns a `rclcpp::QoS` BY VALUE from an
// inline body, so the complete type must be here, not only by the time
// `rclcpp/node.hpp` is pulled in below.
//
// AFTER `nros_cpp_ffi.h`, never before: `qos.hpp` defines the four
// `nros_cpp_qos_*_t` enums ITSELF under `#ifndef NROS_CPP_FFI_H`, so
// reaching it first makes the cbindgen header a REDEFINITION of all four.
#include "rclcpp/qos.hpp"
 
// Phase 189.M3.3.f — `nros_cpp_service_client_register` is excluded from
// cbindgen (its Rust signature uses `RawResponseCallback`, an external-crate
// type alias). Declare it locally with a matching fn-ptr typedef.
// (`nros_cpp_service_client_send_on_handle` takes no callback, so it comes from
// the cbindgen header.)
extern "C" {
typedef void (*nros_cpp_service_response_callback_t)(const uint8_t* data, size_t len, void* ctx);
 
nros_cpp_ret_t nros_cpp_service_client_register(const nros_cpp_node_t* node,
                                                const char* service_name, const char* type_name,
                                                const char* type_hash, nros_cpp_qos_t qos,
                                                nros_cpp_service_response_callback_t callback,
                                                void* context, uint8_t sched_context,
                                                size_t* out_handle_id);
} // extern "C"

namespace rclcpp {
class Node;
}
 
// ============================================================================
// `rclcpp::Client<S>` -- DEFINED here (RFC-0089: rclcpp:: is the home)
// ============================================================================
//
// phase-428: the definition moved from `nros::` to `rclcpp::` (the `nros::`
// alias went in phase-483 W1). The nested `SharedPtr` / `ConstSharedPtr` / `UniquePtr`
// aliases live on the class itself, so the rclcpp way of indexing types
// (`rclcpp::Client<S>::SharedPtr`) resolves with no wrapper in between.
namespace rclcpp {

template <typename S> class Client {
  public:
    using SharedPtr = ::rclcpp::ClientHandle<S>;
    using ConstSharedPtr = ::rclcpp::ClientHandle<S>;
    using UniquePtr = ::rclcpp::ClientHandle<S>;
 
    using RequestType = typename S::Request;
    using ResponseType = typename S::Response;
 
#if defined(NROS_CPP_HAS_STD_PROMISE) // hosted-family: shared-future-interop
    using SharedRequest = ::std::shared_ptr<RequestType>;
    using SharedResponse = ::std::shared_ptr<ResponseType>;
    using SharedFuture = ::rclcpp::detail::DrivenSharedFuture<SharedResponse>;
#endif

    using TypedResponseFn = void (*)(const ResponseType& response);

    Result async_send_request(const RequestType& req) {
        if (!initialized_) return Result(::rclcpp::ErrorCode::NotInitialized);
        uint8_t req_buf[::rclcpp::detail::buffer_bounds<RequestType>::tx];
        size_t req_len = 0;
        if (RequestType::ffi_serialize(&req, req_buf, sizeof(req_buf), &req_len) != 0) {
            return Result(::rclcpp::ErrorCode::Error);
        }
        return Result(
            nros_cpp_service_client_send_on_handle(executor_, handle_id_, req_buf, req_len));
    }

    bool is_valid() const { return initialized_; }

    const char* get_service_name() const { return initialized_ ? service_name_ : ""; }

    ::rclcpp::QoS get_request_publisher_actual_qos() const { return actual_qos_half(true); }

    ::rclcpp::QoS get_response_subscription_actual_qos() const { return actual_qos_half(false); }

    ::rclcpp::ResultOf<bool> service_is_ready() const {
        if (!initialized_)
            return ::rclcpp::ResultOf<bool>::error(::rclcpp::ErrorCode::NotInitialized);
        int32_t out = -1;
        nros_cpp_ret_t ret =
            nros_cpp_service_client_server_available(nullptr, executor_, handle_id_, &out);
        // A failed CALL and a backend that cannot ANSWER are different facts;
        // the retired `int` form reported both as `-1`. Keep them apart.
        if (ret != 0) return ::rclcpp::ResultOf<bool>::error(static_cast<::rclcpp::ErrorCode>(ret));
        if (out < 0) return ::rclcpp::ResultOf<bool>::error(::rclcpp::ErrorCode::Unsupported);
        return ::rclcpp::ResultOf<bool>::ok(out != 0);
    }

    Result wait_for_service(uint32_t timeout_ms) {
        if (!initialized_) return Result(::rclcpp::ErrorCode::NotInitialized);
        return Result(
            nros_cpp_service_client_wait_for_service(nullptr, executor_, handle_id_, timeout_ms));
    }

    template <typename T = void> Result wait_for_service() {
        static_assert(::rclcpp::detail::refuse<T>::value, NROS_RCLCPP_REFUSE_UNBOUNDED_WAIT);
        return Result(::rclcpp::ErrorCode::Unsupported);
    }
 
#ifdef NROS_CPP_HAS_STD_CHRONO // hosted-family: chrono-interop
    template <typename Rep, typename Period>
    Result wait_for_service(::std::chrono::duration<Rep, Period> timeout) {
        const int64_t ms = ::rclcpp::detail::chrono_wait_budget_ms(timeout);
        if (ms < 0) {
            NROS_RCLCPP_SAY_REFUSED(NROS_RCLCPP_REFUSE_UNBOUNDED_WAIT_RUNTIME);
            return Result(::rclcpp::ErrorCode::Unsupported);
        }
        return wait_for_service(static_cast<uint32_t>(ms));
    }
#endif // NROS_CPP_HAS_STD_CHRONO

    size_t handle_id() const { return handle_id_; }

    ~Client() { initialized_ = false; }
 
    // Move semantics (non-copyable). Bookkeeping only — there is no storage to
    // relocate, so `nros_cpp_service_client_relocate` is not called here.
    //
    // phase-456 W3 — a callback-style client is MOVABLE, and the warning that
    // used to stand here is gone with its subject. It said the arena holds
    // `this` as the response trampoline context; the arena holds the user's
    // HANDLER now, so nothing of the caller's is referenced after registration
    // and there is no pointer a move could leave stale. What survives the move
    // is `{executor_, handle_id_}`, which is what `async_send_request` needs and
    // all it needs.
    Client(Client&& other)
        : executor_(other.executor_), initialized_(other.initialized_),
          handle_id_(other.handle_id_), service_name_{} {
        ::rclcpp::detail::assign_entity_name(service_name_, other.service_name_);
        other.initialized_ = false;
    }
 
    Client& operator=(Client&& other) {
        if (this != &other) {
            executor_ = other.executor_;
            initialized_ = other.initialized_;
            handle_id_ = other.handle_id_;
            ::rclcpp::detail::assign_entity_name(service_name_, other.service_name_);
            other.initialized_ = false;
        }
        return *this;
    }

    Client() : executor_(nullptr), initialized_(false), service_name_{} {}
 
  private:
    Client(const Client&) = delete;
    Client& operator=(const Client&) = delete;
 
    friend class ::rclcpp::Node;

    static void response_trampoline(const uint8_t* data, size_t len, void* ctx) {
        const TypedResponseFn user_fn = ::rclcpp::detail::fn_from_context<TypedResponseFn>(ctx);
        if (user_fn == nullptr) return;
        ResponseType response;
        if (ResponseType::ffi_deserialize(data, len, &response) != 0) return;
        user_fn(response);
    }

    ::rclcpp::QoS actual_qos_half(bool request) const {
        nros_cpp_qos_t req{};
        nros_cpp_qos_t resp{};
        if (!initialized_) return ::rclcpp::detail::qos_all_unknown();
        if (nros_cpp_service_client_get_actual_qos(nullptr, executor_, handle_id_, &req, &resp) !=
            0) {
            return ::rclcpp::detail::qos_all_unknown();
        }
        return ::rclcpp::detail::qos_from_ffi(request ? req : resp);
    }
 
    // Callback-style BOOKKEEPING (Phase 189.M3.3.f). The handler itself is not
    // here — it lives in the arena (phase-456 W3) — and neither is the client,
    // so what remains is the caller's own record of a registration that refers
    // back to nothing of the caller's. `{executor_, handle_id_}` is also the
    // send road, which is why this object has a verb where `Service<S>` has
    // none.
    void* executor_;
    bool initialized_;
    size_t handle_id_ = static_cast<size_t>(-1);
    char service_name_[::rclcpp::SERVICE_NAME_MAX];
};
 
} // namespace rclcpp
 
// Phase 84.G8: out-of-line definition of Node::create_client<S>().
#include "rclcpp/node.hpp"
 
namespace rclcpp {
 
// Phase 189.M3.3.f — callback-style (arena-registered) client. The arena owns
// the client AND the response handler, and dispatches it during spin_once;
// requests go through `async_send_request`, which needs only `out`'s own
// `{executor_, handle_id_}`. `options.sched_context` is functional.
} // namespace rclcpp
 
namespace rclcpp {
template <typename S, typename F, typename>
Result Node::create_client(Client<S>& out, const char* service_name, F callback,
                           const ::rclcpp::QoS& qos, const ::rclcpp::ClientOptions& options) {
    if (!initialized_) return Result(::rclcpp::ErrorCode::NotInitialized);
    nros_cpp_qos_t ffi_qos = ::rclcpp::detail::qos_to_ffi(qos);
 
    // The user handler becomes the ARENA's context (phase-456 W3); the
    // conversion is still the compile error for a non-convertible `F`.
    const typename Client<S>::TypedResponseFn user_fn =
        typename Client<S>::TypedResponseFn(callback);
 
    uint8_t sched = (options.sched_context == ::rclcpp::SCHED_CONTEXT_UNSET)
                        ? 0u
                        : static_cast<uint8_t>(options.sched_context);
    size_t handle = static_cast<size_t>(-1);
    nros_cpp_ret_t ret = nros_cpp_service_client_register(
        &handle_, service_name, S::TYPE_NAME, S::Request::TYPE_HASH, ffi_qos,
        reinterpret_cast<nros_cpp_service_response_callback_t>(&Client<S>::response_trampoline),
        ::rclcpp::detail::fn_to_context(user_fn), sched, &handle);
    if (ret == 0) {
        out.executor_ = executor_handle_;
        out.handle_id_ = handle;
        // phase-444 — see `rclcpp::PollClient`'s overload, which does the same.
        ::rclcpp::detail::assign_entity_name(out.service_name_, service_name);
        out.initialized_ = true;
    }
    return Result(ret);
}
} // namespace rclcpp
 
namespace rclcpp {} // namespace rclcpp
 
#endif // NROS_RCLCPP_CLIENT_HPP