runtime_rpc_binding.h

Go to the documentation of this file.

#pragma once
 
// =============================================================================
// RuntimeRpcBinding -- non-template ErasedInvoker (FastLED #3246 / #3244 Tier 1A)
// =============================================================================
//
// Replaces per-signature `TypedRpcBinding<Sig>::invokeWithReturn` (~2.1 KB
// observed on LPC845 / AutoResearch) with a non-template invoke() body that
// dispatches through a tiny per-Sig trampoline plus a per-type ops table.
//
// Per-Sig cost goes from ~2 KB (full JsonArgConverter + TypeToJson +
// invokeImpl bodies emitted per signature) down to ~50-150 B (just the
// per-Sig trampoline). The shared dispatch lives in
// `runtime_rpc_binding.cpp.hpp`.
//
// Acceptance is in FastLED #3246: enabled on `!FL_PLATFORM_HAS_LARGE_MEMORY`
// targets via the compile-time fork in `Rpc::registerMethod`. Large-memory
// targets keep `TypedRpcBinding<Sig>` (faster -- no per-call heap, no
// indirect dispatch).
 
#include "fl/stl/json.h"
#include "fl/stl/tuple.h"
#include "fl/stl/function.h"
#include "fl/stl/string.h"
#include "fl/stl/vector.h"
#include "fl/stl/shared_ptr.h"
#include "fl/stl/type_traits.h"
#include "fl/stl/new.h"  // placement-new
#include "fl/stl/move.h"
#include "fl/stl/noexcept.h"
#include "fl/stl/stdint.h"
#include "fl/remote/rpc/type_conversion_result.h"
#include "fl/remote/rpc/json_to_type.h"   // JsonToType<T>, ConstCharPtrWrapper, ConstSpanWrapper  // IWYU pragma: keep
#include "fl/remote/rpc/type_to_json.h"   // detail::TypeToJson<T>  // IWYU pragma: keep
#include "fl/remote/rpc/json_arg_converter.h"  // rpc_storage_type
#include "fl/remote/rpc/rpc_invokers.h"   // detail::ErasedInvoker
 
namespace fl {
namespace detail {
 
// =============================================================================
// RpcTypeOps -- per-type operations table
// =============================================================================
//
// One `static const RpcTypeOps` is emitted per unique storage type used
// across all RPC signatures (shared, not per-Sig). All cross-type behavior
// in `RuntimeRpcBinding::invoke` indirects through this table.
 
struct RpcTypeOps {
    fl::size storage_size;
    fl::size storage_align;
    void (*default_construct)(void* p);
    void (*destroy)(void* p);
    TypeConversionResult (*decode)(const json& src, void* dst);
    json (*encode)(const void* src);
};
 
// Helper that emits one `static const RpcTypeOps` per concrete storage type
// `T`. Requires that `JsonToType<T>` and `TypeToJson<T>` specializations
// exist for `T` (which is exactly the set of RPC-supported types today).
template <typename T>
struct RpcTypeOpsFor {
    static void default_construct_(void* p) FL_NO_EXCEPT { new (p) T(); }
    static void destroy_(void* p) FL_NO_EXCEPT { static_cast<T*>(p)->~T(); }
 
    static TypeConversionResult decode_(const json& src, void* dst) FL_NO_EXCEPT {
        fl::tuple<T, TypeConversionResult> tup = JsonToType<T>::convert(src);
        *static_cast<T*>(dst) = fl::move(fl::get<0>(tup));
        return fl::get<1>(tup);
    }
    static json encode_(const void* src) FL_NO_EXCEPT {
        return TypeToJson<T>::convert(*static_cast<const T*>(src));
    }
 
    static const RpcTypeOps* ops() FL_NO_EXCEPT {
        static const RpcTypeOps kOps = {
            sizeof(T), alignof(T),
            &default_construct_,
            &destroy_,
            &decode_,
            &encode_,
        };
        return &kOps;
    }
};
 
// Void return: no storage / encode / decode. Caller (RuntimeRpcBinding)
// branches on a null `mResultType`.
template <>
struct RpcTypeOpsFor<void> {
    static const RpcTypeOps* ops() FL_NO_EXCEPT { return nullptr; }
};
 
// =============================================================================
// RpcTrampolineFn -- per-Sig trampoline signature
// =============================================================================
//
// Generated by `makeRuntimeRpcBinding<R(Args...)>`. Body is ~50-100 B:
//   1) Cast `user_fn` to `fl::function<R(Args...)>*`.
//   2) Cast each `arg_slots[i]` to the matching storage type and forward.
//   3) Place the return value into `result_slot` (if non-null).
//
// All decode/encode/lifetime work happens outside the trampoline, in
// `RuntimeRpcBinding::invoke`, so there is no per-Sig copy of that code.
 
using RpcTrampolineFn = void (*)(void* user_fn,
                                 void* result_slot,
                                 void* const* arg_slots);
 
// Per-Sig user-fn destroyer (deletes the heap-allocated `fl::function<Sig>`).
using RpcDestroyFn = void (*)(void* user_fn);
 
namespace runtime_rpc {
 
// =============================================================================
// TrampolineHelper -- emits per-Sig trampoline + destroy bodies
// =============================================================================
 
template <typename R, typename... Args>
struct TrampolineHelper {
    using FunctionType = fl::function<R(Args...)>;
 
    template <fl::size... Is>
    static R invoke_(FunctionType& fn, void* const* arg_slots, index_sequence<Is...>) FL_NO_EXCEPT {
        // Each slot stores a `rpc_storage_type<Args>::type` value;
        // implicit conversion (ConstCharPtrWrapper -> const char*,
        // ConstSpanWrapper<T> -> span<const T>) yields the original Args.
        return fn(*static_cast<typename rpc_storage_type<Args>::type*>(arg_slots[Is])...);
    }
 
    static void trampoline(void* user_fn, void* result_slot, void* const* arg_slots) FL_NO_EXCEPT {
        FunctionType& fn = *static_cast<FunctionType*>(user_fn);
        R value = invoke_(fn, arg_slots, make_index_sequence<sizeof...(Args)>{});
        if (result_slot) {
            *static_cast<R*>(result_slot) = fl::move(value);
        }
    }
 
    static void destroy(void* user_fn) FL_NO_EXCEPT {
        delete static_cast<FunctionType*>(user_fn);  // ok bare allocation
    }
};
 
// Void-return specialization.
template <typename... Args>
struct TrampolineHelper<void, Args...> {
    using FunctionType = fl::function<void(Args...)>;
 
    template <fl::size... Is>
    static void invoke_(FunctionType& fn, void* const* arg_slots, index_sequence<Is...>) FL_NO_EXCEPT {
        fn(*static_cast<typename rpc_storage_type<Args>::type*>(arg_slots[Is])...);
    }
 
    static void trampoline(void* user_fn, void* result_slot, void* const* arg_slots) FL_NO_EXCEPT {
        (void)result_slot;
        FunctionType& fn = *static_cast<FunctionType*>(user_fn);
        invoke_(fn, arg_slots, make_index_sequence<sizeof...(Args)>{});
    }
 
    static void destroy(void* user_fn) FL_NO_EXCEPT {
        delete static_cast<FunctionType*>(user_fn);  // ok bare allocation
    }
};
 
// Per-Sig static arg-type table. Owning storage for the
// `const RpcTypeOps* const*` pointer handed to RuntimeRpcBinding. Lives in
// `.rodata` (one entry per Sig, ~8 B per arg). For zero-arg signatures the
// `mArgTypes` pointer is unused so the array is sized to 1 with a nullptr
// entry to keep ISO C++ happy (no zero-sized array).
template <typename... Args>
struct ArgTypesTable {
    static const RpcTypeOps* const* table() FL_NO_EXCEPT {
        static const RpcTypeOps* const kTable[] = {
            RpcTypeOpsFor<typename rpc_storage_type<Args>::type>::ops()...
        };
        return kTable;
    }
};
 
template <>
struct ArgTypesTable<> {
    static const RpcTypeOps* const* table() FL_NO_EXCEPT {
        // 0-arg signatures pass `arg_count == 0`; the table is never
        // dereferenced, but we still need a valid (non-null) pointer.
        static const RpcTypeOps* const kTable[1] = { nullptr };
        return kTable;
    }
};
 
} // namespace runtime_rpc
 
// =============================================================================
// RuntimeRpcBinding -- non-template ErasedInvoker
// =============================================================================
//
// All decode/encode/alloc/destroy/dispatch logic lives in one non-template
// `invoke` body (in `runtime_rpc_binding.cpp.hpp`). Per-Sig instantiation
// tax is bounded to:
//   * The per-Sig trampoline (50-150 B)
//   * The per-Sig destroy fn (~10 B)
//   * The per-Sig arg_types table (8 B * argc, in .rodata)
//   * The per-T RpcTypeOps entries (~32 B per unique type, *shared* across Sigs)
 
class RuntimeRpcBinding final : public ErasedInvoker {
public:
    RuntimeRpcBinding(void* user_fn,
                      RpcTrampolineFn trampoline,
                      RpcDestroyFn destroy_user_fn,
                      const RpcTypeOps* const* arg_types,
                      fl::size arg_count,
                      const RpcTypeOps* result_type) FL_NO_EXCEPT
        : mUserFn(user_fn),
          mTrampoline(trampoline),
          mDestroyUserFn(destroy_user_fn),
          mArgTypes(arg_types),
          mArgCount(arg_count),
          mResultType(result_type) {}
 
    ~RuntimeRpcBinding() FL_NO_EXCEPT override {
        if (mUserFn && mDestroyUserFn) mDestroyUserFn(mUserFn);
    }
 
    RuntimeRpcBinding(const RuntimeRpcBinding&) FL_NO_EXCEPT = delete;
    RuntimeRpcBinding& operator=(const RuntimeRpcBinding&) FL_NO_EXCEPT = delete;
 
    fl::tuple<TypeConversionResult, json> invoke(const json& jsonArgs) FL_NO_EXCEPT override;
 
private:
    void* mUserFn;
    RpcTrampolineFn mTrampoline;
    RpcDestroyFn mDestroyUserFn;
    const RpcTypeOps* const* mArgTypes;
    fl::size mArgCount;
    const RpcTypeOps* mResultType;  // nullptr for void
};
 
// =============================================================================
// makeRuntimeRpcBinding<Sig> -- per-Sig construction helper
// =============================================================================
//
// One emission per unique signature, but the work is *light*: just a heap
// allocation for the captured fl::function and pointer-stamping into the
// new RuntimeRpcBinding. The expensive per-Sig template tax (~2 KB of
// invokeWithReturn body) is gone.
 
template <typename R, typename... Args>
fl::shared_ptr<RuntimeRpcBinding> makeRuntimeRpcBinding(fl::function<R(Args...)> fn) FL_NO_EXCEPT {
    using Helper = runtime_rpc::TrampolineHelper<R, Args...>;
    using FunctionType = fl::function<R(Args...)>;
    // user_fn is owned by the RuntimeRpcBinding via mDestroyUserFn (see Helper::destroy).
    FunctionType* user_fn = new FunctionType(fl::move(fn));  // ok bare allocation
    return fl::make_shared<RuntimeRpcBinding>(
        static_cast<void*>(user_fn),
        &Helper::trampoline,
        &Helper::destroy,
        runtime_rpc::ArgTypesTable<Args...>::table(),
        sizeof...(Args),
        RpcTypeOpsFor<R>::ops()
    );
}
 
} // namespace detail
} // namespace fl