3 files changed, 32 insertions, 6 deletions
diff --git a/src/nvim/event/loop.c b/src/nvim/event/loop.c
index 25701a1621..cc9088f776 100644
--- a/src/nvim/event/loop.c
+++ b/src/nvim/event/loop.c
@@ -59,7 +59,13 @@ void loop_poll_events(Loop *loop, int ms)
   multiqueue_process_events(loop->fast_events);
 }
 
-// Schedule an event from another thread
+/// Schedules an event from another thread.
+///
+/// @note Event is queued into `fast_events`, which is processed outside of the
+///       primary `events` queue by loop_poll_events(). For `main_loop`, that
+///       means `fast_events` is NOT processed in an "editor mode"
+///       (VimState.execute), so redraw and other side-effects are likely to be
+///       skipped.
 void loop_schedule(Loop *loop, Event event)
 {
   uv_mutex_lock(&loop->mutex);
diff --git a/src/nvim/event/loop.h b/src/nvim/event/loop.h
index e7d7bdd483..b0ddc59469 100644
--- a/src/nvim/event/loop.h
+++ b/src/nvim/event/loop.h
@@ -16,10 +16,28 @@ KLIST_INIT(WatcherPtr, WatcherPtr, _noop)
 
 typedef struct loop {
   uv_loop_t uv;
-  MultiQueue *events, *fast_events, *thread_events;
+  MultiQueue *events;
+  MultiQueue *thread_events;
+  // Immediate events:
+  //    "Events that should be processed after exiting uv_run() (to avoid
+  //    recursion), but before returning from loop_poll_events()."
+  //    502aee690c980fcb3cfcb3f211dcfad06103db46
+  // Practical consequence: these events are processed by
+  //    state_enter()..os_inchar()
+  // whereas "regular" (main_loop.events) events are processed by
+  //    state_enter()..VimState.execute()
+  // But state_enter()..os_inchar() can be "too early" if you want the event
+  // to trigger UI updates and other user-activity-related side-effects.
+  MultiQueue *fast_events;
+
+  // used by process/job-control subsystem
   klist_t(WatcherPtr) *children;
   uv_signal_t children_watcher;
-  uv_timer_t children_kill_timer, poll_timer;
+  uv_timer_t children_kill_timer;
+
+  // generic timer, used by loop_poll_events()
+  uv_timer_t poll_timer;
+
   size_t children_stop_requests;
   uv_async_t async;
   uv_mutex_t mutex;
diff --git a/src/nvim/state.c b/src/nvim/state.c
index 24248ec66c..4d9032b7a5 100644
--- a/src/nvim/state.c
+++ b/src/nvim/state.c
@@ -49,11 +49,13 @@ getkey:
       ui_flush();
       // Call `os_inchar` directly to block for events or user input without
       // consuming anything from `input_buffer`(os/input.c) or calling the
-      // mapping engine. If an event was put into the queue, we send K_EVENT
-      // directly.
+      // mapping engine.
       (void)os_inchar(NULL, 0, -1, 0);
       input_disable_events();
-      key = !multiqueue_empty(main_loop.events) ? K_EVENT : safe_vgetc();
+      // If an event was put into the queue, we send K_EVENT directly.
+      key = !multiqueue_empty(main_loop.events)
+            ? K_EVENT
+            : safe_vgetc();
     }
 
     if (key == K_EVENT) {