An object payload that lives in native (Rust) heap until explicitly loaded.

Received objects normally carry a %MOQX.NativeBinary{} as their payload field instead of a plain Elixir binary. The bytes stay in C space unless one of two things happens:

1. Loaded into BEAM space — call load/1 to obtain a regular binary(). This is the only moment a copy occurs.

2. Passed to another NIF — hand the %MOQX.NativeBinary{} directly to MOQX.write_object/4 or MOQX.write_datagram/3. The NIF extracts the underlying Bytes pointer (O(1) Arc clone) without touching BEAM at all.

Example — zero-copy transcoding loop

def handle_info({:moqx_object, %MOQX.ObjectReceived{object: obj}}, state) do
  # obj.payload is %MOQX.NativeBinary{} — still on Rust heap
  :ok = MOQX.write_object(state.out_subgroup, obj.object_id, obj.payload)
  {:noreply, state}
end

Example — load for Elixir-side processing

def handle_info({:moqx_object, %MOQX.ObjectReceived{object: obj}}, state) do
  bytes = MOQX.NativeBinary.load(obj.payload)
  # bytes is now a regular Elixir binary
  {:noreply, state}
end

Memory note

The underlying bytes are reference-counted via Rust's Arc. Memory is freed when all references — including Elixir variables and in-flight NIF tasks — are dropped. BEAM's garbage collector does not account for this memory, so avoid accumulating large numbers of unreleased %MOQX.NativeBinary{} values.