vim.uv event loop: bounding RPC latency when concurrent clients queue behind plugin callbacks

Answer

Slice the Lua work into small chunks and yield control back to the libuv event loop after each chunk using a zero-timeout vim.uv timer (or coroutine.yield inside a timer callback). This lets queued RPC callbacks, which run in the poll phase, execute before the next Lua chunk resumes, keeping RPC latency bounded and predictable.

Confirmed facts

• Neovim's main loop is single-threaded libuv; RPC requests are handled as libuv poll callbacks.
• Any Lua code that runs without yielding blocks the loop, delaying all pending poll callbacks, including RPC responses.
• vim.uv is the preferred alias for the libuv bindings in Neovim 0.10+; vim.loop remains available. Confirm the alias and deprecation status against your pinned release before relying on either name.

Likely explanation

When a plugin performs CPU-intensive work, the event loop stays occupied until the Lua function returns. By inserting a yield, the loop can advance to the poll phase where RPC callbacks are processed, then return to the next chunk.

Steps to implement chunked work

1. Choose a chunk size that fits a comfortable time budget (e.g., process 50 lines, or limit work to roughly 1 ms measured with vim.uv.hrtime).
2. Wrap each chunk in a function that, after finishing, starts a zero-timeout timer:

local function process_chunk(state)
    -- do one slice of work here
    if not state.done then
        local t = vim.uv.new_timer()
        t:start(0, 0, function()
            t:close()
            process_chunk(state) -- resume with next chunk
        end)
    end
end

1. Kick off the first chunk from your plugin's setup or timer-driven entry point.
2. Ensure any buffer mutations that must be atomic are performed only in the final chunk, or protected with a flag so concurrent RPC handlers see consistent state.

Fairness guarantees

• vim.schedule places a function at the end of the current loop turn; it does not yield. If the scheduled function is CPU-bound it still blocks the loop and offers no fairness relative to queued RPC callbacks.
• A vim.uv timer with a 0 ms timeout schedules its callback for the next loop turn, allowing the current poll phase (where RPC callbacks run) to finish first. This provides the needed fairness, though it is cooperative scheduling rather than a hard ordering guarantee.

Distinguishing starvation from slow request handling

Measure two intervals:

1. Client-side RPC round-trip time (RTT) using your RPC client's timestamps.
2. Server-side work duration for each Lua chunk, recorded with vim.uv.hrtime before and after the chunk.

If RPC RTT grows in step with the measured chunk duration while per-chunk work time stays flat, the delay is event-loop starvation. If RTT increases without a corresponding rise in chunk work time, the slowdown is genuine request handling. As a control, run the same workload as one unchunked block: latency spikes should match the total work duration, confirming the starvation effect.

Missing diagnostic detail

The starvation test requires instrumenting the plugin with vim.uv.hrtime around each chunk. If you cannot add such timestamps, the distinction cannot be made reliably; confirm whether you can instrument the plugin before tuning chunk sizes.