Neovim Core ↔ Lua Runtime: Synchronization of Terminal Output

Answer to the Core Question

At present Neovim’s core already offers the minimal non‑blocking path you need: vim.api.nvim_out_write() writes directly into the UI buffer and is flushed by the core’s rendering engine as soon as the event loop processes it. Exposing a new “async terminal API” would add a parallel I/O layer, increase the surface for race conditions, and break backward compatibility with existing plugins that rely on the traditional line‑buffered :term interface. Therefore, the recommended approach is to continue using the existing API and to trigger an explicit UI refresh when instant visibility is required.

Why out_write + redraw is Sufficient

• Both calls run on the same event loop; no extra thread is introduced.
• They preserve the semantics of :term – output still appears in a dedicated terminal buffer.
• They avoid the overhead of a full event‑driven terminal implementation.

Minimal Steps to Achieve Immediate Terminal Output

1. Write the text using vim.api.nvim_out_write('your text\n'). The trailing \n is required to move to the next line.
2. Immediately force a UI refresh: vim.api.nvim_command('redraw') (or redraw! to ignore lazyredraw).
3. If you are inside a job or a loop that emits many lines, batch the writes and call redraw only after a few hundred characters to keep performance acceptable.

Extending Lua for Terminal‑Output Callbacks

Lua can register callbacks for job output, which is often what you need when dealing with external processes in a terminal. Use vim.fn.jobstart() with the on_stdout and on_stderr options:

local job = vim.fn.jobstart('bash', {
  on_stdout = function(_, data)
    for _, line in ipairs(data) do
      vim.api.nvim_out_write(line .. '\n')
    end
  end,
  on_stderr = function(_, data)
    for _, line in ipairs(data) do
      vim.api.nvim_err_write('ERR: ' .. line .. '\n')
    end
  end,
})

The callbacks run in the same event loop, so they cannot interfere with the core’s processing. If you need to perform more expensive work, wrap the callback body in vim.schedule() to defer execution until after the current UI refresh.

Event‑Driven Pattern to Avoid Stalls

• Use job callbacks for all external I/O.
• Batch rapid writes: accumulate output in a Lua table, then call out_write once per batch.
• Trigger redraw only when a new UI line is required (e.g., after a prompt).
• Keep lazyredraw enabled for normal editing; use redraw! only in REPL‑like scenarios.

Diagnostic Detail Needed for Tailored Advice

Could you confirm whether you have lazyredraw set or if you run Neovim inside a terminal multiplexer (tmux, screen)? These settings affect when the UI actually flushes output and may change whether redraw! is necessary.