fn_handle.hpp

// core/include/nk/value/fn_handle.hpp
//
// nk::FnHandle — the canonical MATLAB-style callback type used by
// the numerical-library API for any function that takes a
// user-supplied function handle (fzero, integral, fminsearch,
// cellfun, structfun, …).
//
// Signature mirrors what MATLAB function handles are at the engine
// boundary: variadic Value inputs, caller-allocated Value outputs.
// `outs.size()` plays the role of MATLAB's `nargout`.
//
// Library-side example:
//   Value fzero(FnHandle fn, double x0, mr);
//
// User-side (C++):
//   auto root = fzero(
//       [](auto args, auto outs, auto *mr) {
//           double x = args[0].toScalar();
//           outs[0] = Value::scalar(x*x - 2.0, mr);  // honour caller mr
//       },
//       /*x0=*/1.0, mr);
//
// Engine-adapter side (toolboxes/optim/src/local/fzero.cpp):
//   void fzero_reg(args, nargout, outs, ctx) {
//       auto handle = args[0];
//       auto cb = [&ctx, &handle](Span<const Value> a, Span<Value> o,
//                                 std::pmr::memory_resource * /*mr*/) {
//           // Engine allocates results; library caller absorbs them
//           // via move-assign into o, so mr is unused on this side.
//           auto r = ctx.engine->callFunctionHandleMulti(handle, a, o.size());
//           for (size_t i = 0; i < o.size() && i < r.size(); ++i)
//               o[i] = std::move(r[i]);
//       };
//       outs[0] = fzero(cb, args[1], ctx.engine->resource());
//   }
 
#pragma once
 
#include <memory_resource>
 
#include <nk/value/function_ref.hpp>
#include <nk/value/span.hpp>
#include <nk/value/value.hpp>
 
namespace nk {

using FnHandle = function_ref<void(Span<const Value>           args,
                                    Span<Value>                 outs,
                                    std::pmr::memory_resource * mr)>;
 
} // namespace nk