eval: add wait()

closes #10362

runtime/doc/eval.txt

@@ -2427,6 +2427,8 @@ uniq({list} [, {func} [, {dict}]])
 values({dict})			List	values in {dict}
 virtcol({expr})			Number	screen column of cursor or mark
 visualmode([expr])		String	last visual mode used
+wait({timeout}, {condition}[, {interval}])
+				Number  Wait until {condition} is satisfied
 wildmenumode()			Number	whether 'wildmenu' mode is active
 win_findbuf({bufnr})		List	find windows containing {bufnr}
 win_getid([{win} [, {tab}]])	Number	get |window-ID| for {win} in {tab}
@@ -8858,6 +8860,25 @@ visualmode([expr])						*visualmode()*
 		a non-empty String, then the Visual mode will be cleared and
 		the old value is returned.  See |non-zero-arg|.
 
+wait({timeout}, {condition}[, {interval}])			*wait()*
+		Wait until {condition} is satisfied, where {condition} is a
+		|Funcref| or a |string| containing an expression.
+
+		{timeout} is the maximum number of milliseconds to wait,
+        -1 means forever.
+
+		By default, the condition is evaluated on user and internal
+		events. If {interval} is given, the condition is evaluated
+		every {interval} milliseconds in addition. This can be useful
+		to guarantee that the function returns when the condition is
+		satisfied even if the editor is idle.
+
+		Returns one of the following:
+			*  0 if the condition was satisfied before the timeout
+			* -1 if the timeout was exceeded
+			* -2 if the function was interrupted
+			* -3 if an error occurred
+
 wildmenumode()					*wildmenumode()*
 		Returns |TRUE| when the wildmenu is active and |FALSE|
 		otherwise.  See 'wildmenu' and 'wildmode'.

runtime/doc/usr_41.txt

@@ -959,6 +959,7 @@ Timers:						*timer-functions*
 	timer_stop()		stop a timer
 	timer_stopall()		stop all timers
 	timer_info()		get information about timers
+	wait()			wait for a condition
 
 Tags:						*tag-functions*
 	taglist()		get list of matching tags

src/nvim/eval.c

@@ -10892,6 +10892,89 @@ static void f_getwininfo(typval_T *argvars, typval_T *rettv, FunPtr fptr)
   }
 }
 
+// Dummy timer callback. Used by f_wait().
+static void dummy_timer_due_cb(TimeWatcher *tw, void *data)
+{
+  if (!uv_timer_get_repeat(&tw->uv)) {
+    time_watcher_start(tw, dummy_timer_due_cb, 0, 0);
+  }
+}
+
+// Dummy timer close callback. Used by f_wait().
+static void dummy_timer_close_cb(TimeWatcher *tw, void *data)
+{
+  multiqueue_free(tw->events);
+  xfree(tw);
+}
+
+/// "wait(timeout, condition[, interval])" function
+static void f_wait(typval_T *argvars, typval_T *rettv, FunPtr fptr)
+{
+  rettv->v_type = VAR_NUMBER;
+  rettv->vval.v_number = -1;
+
+  if (argvars[0].v_type != VAR_NUMBER) {
+    EMSG2(_(e_invarg2), "First argument of wait() must be a number");
+    return;
+  }
+
+  int timeout = argvars[0].vval.v_number;
+  typval_T expr = argvars[1];
+
+  int interval = -1;
+  typval_T *tv_interval = &argvars[2];
+
+  TimeWatcher *tw = NULL;
+
+  if (tv_interval->v_type == VAR_NUMBER) {
+    interval = tv_interval->vval.v_number;
+    if (interval < 0) {
+      EMSG2(_(e_invarg2),
+            "Third argument of wait() must be a non-negative number");
+      return;
+    }
+    // Start dummy timer
+    tw = xmalloc(sizeof(TimeWatcher));
+    time_watcher_init(&main_loop, tw, NULL);
+    tw->events = multiqueue_new_child(main_loop.events);
+    tw->blockable = true;
+    time_watcher_start(tw, dummy_timer_due_cb, interval, interval);
+  } else if (tv_interval->v_type != VAR_UNKNOWN) {
+    EMSG2(_(e_invarg2),
+          "Third argument of wait() must be a non-negative number");
+    return;
+  }
+
+  typval_T argv = TV_INITIAL_VALUE;
+  typval_T exprval = TV_INITIAL_VALUE;
+  bool error = false;
+  int save_called_emsg = called_emsg;
+  called_emsg = false;
+
+  LOOP_PROCESS_EVENTS_UNTIL(&main_loop, main_loop.events, timeout,
+                            eval_expr_typval(&expr, &argv, 0, &exprval) != OK
+                            || tv_get_number_chk(&exprval, &error)
+                            || called_emsg || error || got_int);
+
+  if (called_emsg || error) {
+    rettv->vval.v_number = -3;
+  } else if (got_int) {
+    got_int = false;
+    vgetc();
+    rettv->vval.v_number = -2;
+  } else if (tv_get_number_chk(&exprval, &error)) {
+    rettv->vval.v_number = 0;
+  }
+
+  called_emsg = save_called_emsg;
+
+  // Stop dummy timer
+  if (tw) {
+    time_watcher_stop(tw);
+    time_watcher_close(tw, dummy_timer_close_cb);
+  }
+}
+
 // "win_screenpos()" function
 static void f_win_screenpos(typval_T *argvars, typval_T *rettv, FunPtr fptr)
 {

src/nvim/eval.lua

@@ -366,6 +366,7 @@ return {
     values={args=1},
     virtcol={args=1},
     visualmode={args={0, 1}},
+    wait={args={2,3}},
     wildmenumode={},
     win_findbuf={args=1},
     win_getid={args={0,2}},