client.hpp

Go to the documentation of this file.

// nros-cpp: Service client class
// Freestanding C++ -- no exceptions, no STL required
 
#ifndef NROS_CPP_CLIENT_HPP
#define NROS_CPP_CLIENT_HPP
 
#include <cstdint>
#include <cstddef>
 
#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_cpp_ffi.h"
 
// 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 nros {
 
template <typename S> class Client {
  public:
    using RequestType = typename S::Request;
    using ResponseType = typename S::Response;
 
    using TypedResponseFn = void (*)(const ResponseType& response);
    using TypedResponseFnWithCtx = void (*)(const ResponseType& response, void* ctx);
 
    Future<ResponseType> send_request(const RequestType& req) {
        return send_request_sized<::nros::rx_buffer_capacity<ResponseType>::value>(req);
    }
 
    template <size_t RespCap>
    Future<ResponseType, RespCap> send_request_sized(const RequestType& req) {
        using Fut = Future<ResponseType, RespCap>;
        if (!initialized_) return Fut();
 
        uint8_t req_buf[::nros::detail::buffer_bounds<RequestType>::tx];
        size_t req_len = 0;
        if (RequestType::ffi_serialize(&req, req_buf, sizeof(req_buf), &req_len) != 0) {
            return Fut();
        }
 
        nros_cpp_ret_t ret = nros_cpp_service_client_send_request(storage_, req_buf, req_len);
        if (ret != 0) return Fut();
 
        return Fut(storage_, &nros_cpp_service_client_take_response,
                   0 // slot 0 (single outstanding request)
        );
    }
 
    Result call(const RequestType& req, ResponseType& resp, uint32_t timeout_ms = 5000) {
        return call_sized<::nros::rx_buffer_capacity<ResponseType>::value>(req, resp, timeout_ms);
    }
 
    template <size_t RespCap>
    Result call_sized(const RequestType& req, ResponseType& resp, uint32_t timeout_ms = 5000) {
        if (!initialized_ || !executor_) return Result(ErrorCode::NotInitialized);
        auto fut = send_request_sized<RespCap>(req);
        return fut.wait(executor_, timeout_ms, resp);
    }
 
    Result call_polling(const RequestType& req, ResponseType& resp, uint32_t timeout_ms = 100) {
        return call_polling_sized<::nros::rx_buffer_capacity<ResponseType>::value>(req, resp,
                                                                                   timeout_ms);
    }
 
    template <size_t RespCap>
    Result call_polling_sized(const RequestType& req, ResponseType& resp,
                              uint32_t timeout_ms = 100) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        uint8_t req_buf[::nros::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(ErrorCode::Error);
        }
        uint8_t resp_buf[RespCap];
        size_t resp_len = 0;
        nros_cpp_ret_t ret = nros_cpp_service_client_call_raw(
            storage_, req_buf, req_len, resp_buf, sizeof(resp_buf), &resp_len, timeout_ms);
        if (ret != 0) return Result(ret);
        if (resp_len == 0) return Result(ErrorCode::Timeout);
        if (ResponseType::ffi_deserialize(resp_buf, resp_len, &resp) != 0) {
            return Result(ErrorCode::Error);
        }
        return Result::success();
    }
 
    bool is_valid() const { return initialized_; }
 
    Expected<bool> service_is_ready() const {
        if (!initialized_) return Expected<bool>::error(ErrorCode::NotInitialized);
        int out = -1;
        nros_cpp_ret_t ret =
            nros_cpp_service_client_server_available(const_cast<uint8_t*>(storage_), &out);
        // A failed CALL and a backend that cannot ANSWER are different facts,
        // and the old `int` form reported both as `-1`. Keep them apart.
        if (ret != 0) return Expected<bool>::error(static_cast<ErrorCode>(ret));
        if (out < 0) return Expected<bool>::error(ErrorCode::Unsupported);
        return Expected<bool>::ok(out != 0);
    }
 
    [[deprecated("Client::server_available is deprecated; use "
                 "Client::service_is_ready, which returns Expected<bool>")]] int
    server_available() const {
        auto r = service_is_ready();
        if (!r.ok()) return -1;
        return r.value() ? 1 : 0;
    }
 
    Result wait_for_service(uint32_t timeout_ms = 5000) {
        if (!initialized_) return Result(ErrorCode::NotInitialized);
        return Result(nros_cpp_service_client_wait_for_service(storage_, executor_, timeout_ms));
    }
 
    Result async_send_request(const RequestType& req) {
        if (!initialized_ || !callback_mode_) return Result(ErrorCode::NotInitialized);
        uint8_t req_buf[::nros::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(ErrorCode::Error);
        }
        return Result(
            nros_cpp_service_client_send_on_handle(executor_, handle_id_, req_buf, req_len));
    }
 
    size_t handle_id() const { return handle_id_; }
 
    ~Client() {
        if (initialized_ && !callback_mode_) {
            nros_cpp_service_client_destroy(storage_);
        }
        initialized_ = false;
    }
 
    // Move semantics (non-copyable). Future-style relocation goes through the
    // `nros_cpp_service_client_relocate` runtime call (Phase 84.C1). A
    // callback-style client must NOT be moved after register — the arena holds
    // `this` as the response trampoline context (M3.3.f).
    Client(Client&& other)
        : executor_(other.executor_), initialized_(other.initialized_), user_fn_(other.user_fn_),
          user_fn_ctx_(other.user_fn_ctx_), user_ctx_(other.user_ctx_),
          handle_id_(other.handle_id_), callback_mode_(other.callback_mode_) {
        if (other.initialized_ && !other.callback_mode_) {
            nros_cpp_service_client_relocate(other.storage_, storage_);
        }
        other.initialized_ = false;
    }
 
    Client& operator=(Client&& other) {
        if (this != &other) {
            if (initialized_ && !callback_mode_) {
                nros_cpp_service_client_destroy(storage_);
            }
            executor_ = other.executor_;
            initialized_ = other.initialized_;
            user_fn_ = other.user_fn_;
            user_fn_ctx_ = other.user_fn_ctx_;
            user_ctx_ = other.user_ctx_;
            handle_id_ = other.handle_id_;
            callback_mode_ = other.callback_mode_;
            if (other.initialized_ && !other.callback_mode_) {
                nros_cpp_service_client_relocate(other.storage_, storage_);
            }
            other.initialized_ = false;
        }
        return *this;
    }
 
    Client() : storage_(), executor_(nullptr), initialized_(false) {}
 
  private:
    Client(const Client&) = delete;
    Client& operator=(const Client&) = delete;
 
    friend class Node;
 
    static void response_trampoline(const uint8_t* data, size_t len, void* ctx) {
        auto* self = static_cast<Client*>(ctx);
        if (self == nullptr) return;
        ResponseType response;
        if (ResponseType::ffi_deserialize(data, len, &response) != 0) return;
        if (self->user_fn_ != nullptr) {
            self->user_fn_(response);
        } else if (self->user_fn_ctx_ != nullptr) {
            self->user_fn_ctx_(response, self->user_ctx_);
        }
    }
 
    alignas(8) uint8_t storage_[NROS_SERVICE_CLIENT_SIZE];
    void* executor_;
    bool initialized_;
    // Callback-style state (Phase 189.M3.3.f); unused in future mode.
    TypedResponseFn user_fn_ = nullptr;
    TypedResponseFnWithCtx user_fn_ctx_ = nullptr;
    void* user_ctx_ = nullptr;
    size_t handle_id_ = static_cast<size_t>(-1);
    bool callback_mode_ = false;
};
 
} // namespace nros
 
// Phase 84.G8: out-of-line definition of Node::create_client<S>().
#include "nros/node.hpp"
 
namespace nros {
 
template <typename S>
Result Node::create_client(Client<S>& out, const char* service_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_service_client_create(
        &handle_, service_name, S::TYPE_NAME, S::Request::TYPE_HASH, ffi_qos, out.storage_);
    if (ret == 0) {
        out.executor_ = executor_handle_;
        out.initialized_ = true;
    }
    return Result(ret);
}
 
// Phase 189.M3.3.f — callback-style (arena-registered) client. The arena owns
// the client + dispatches `out`'s response handler during spin_once; requests
// go through `async_send_request`. `options.sched_context` is functional.
template <typename S, typename F, typename>
Result Node::create_client(Client<S>& out, const char* service_name, F callback, const QoS& qos,
                           const ClientOptions& options) {
    if (!initialized_) return Result(ErrorCode::NotInitialized);
    nros_cpp_qos_t ffi_qos = detail::qos_to_ffi(qos);
 
    out.user_fn_ = typename Client<S>::TypedResponseFn(callback);
    out.user_fn_ctx_ = nullptr;
    out.user_ctx_ = nullptr;
 
    uint8_t sched = (options.sched_context == 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),
        &out, sched, &handle);
    if (ret == 0) {
        out.executor_ = executor_handle_;
        out.handle_id_ = handle;
        out.callback_mode_ = true;
        out.initialized_ = true;
    }
    return Result(ret);
}
 
} // namespace nros
 
#endif // NROS_CPP_CLIENT_HPP