Merge pull request #10382 from abdelhakeem/waituntil

eval: add wait()

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,83 @@ 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)
+{
+}
+
+// Dummy timer close callback. Used by f_wait().
+static void dummy_timer_close_cb(TimeWatcher *tw, void *data)
+{
+  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_invargval), "1");
+    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_invargval), "3");
+      return;
+    }
+    // Start dummy timer
+    tw = xmalloc(sizeof(TimeWatcher));
+    time_watcher_init(&main_loop, tw, NULL);
+    tw->events = 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_invargval), "3");
+    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}},

test/functional/eval/wait_spec.lua

@@ -0,0 +1,78 @@
+local helpers = require('test.functional.helpers')(after_each)
+local call = helpers.call
+local clear = helpers.clear
+local command = helpers.command
+local eval = helpers.eval
+local eq = helpers.eq
+local expect_err = helpers.expect_err
+local feed = helpers.feed
+local feed_command = helpers.feed_command
+local next_msg = helpers.next_msg
+local nvim = helpers.nvim
+local source = helpers.source
+
+before_each(function()
+  clear()
+  local channel = nvim('get_api_info')[1]
+  nvim('set_var', 'channel', channel)
+end)
+
+describe('wait()', function()
+  it('waits and returns 0 when condition is satisfied', function()
+    source([[
+    let g:_awake = 0
+    call timer_start(100, { -> nvim_command('let g:_awake = 1') })
+    ]])
+    eq(0, eval('g:_awake'))
+    eq(0, eval('wait(1500, { -> g:_awake })'))
+    eq(1, eval('g:_awake'))
+
+    eq(0, eval('wait(0, 1)'))
+  end)
+
+  it('returns -1 on timeout', function()
+    eq(-1, eval('wait(0, 0)'))
+    eq(-1, eval('wait(50, 0)'))
+  end)
+
+  it('returns -2 when interrupted', function()
+    feed_command('call rpcnotify(g:channel, "ready") | '..
+                 'call rpcnotify(g:channel, "wait", wait(-1, 0))')
+    eq({'notification', 'ready', {}}, next_msg())
+    feed('<c-c>')
+    eq({'notification', 'wait', {-2}}, next_msg())
+  end)
+
+  it('returns -3 on error', function()
+    command('silent! let ret = wait(-1, "error")')
+    eq(-3, eval('ret'))
+    command('let ret = 0 | silent! let ret = wait(-1, { -> error })')
+    eq(-3, eval('ret'))
+  end)
+
+  it('evaluates the condition on given interval', function()
+    source([[
+    function Count()
+      let g:counter += 1
+      return g:counter
+    endfunction
+    ]])
+
+    nvim('set_var', 'counter', 0)
+    eq(-1, call('wait', 20, 'Count() >= 5'))
+
+    nvim('set_var', 'counter', 0)
+    eq(0, call('wait', 1000, 'Count() >= 5', 5))
+    eq(5, nvim('get_var', 'counter'))
+  end)
+
+  it('errors out on invalid timeout value', function()
+    expect_err('Invalid value for argument', call, 'wait', '', 1)
+  end)
+
+  it('errors out on invalid interval', function()
+    expect_err('Invalid value for argument', call, 'wait', 0, 1, -1)
+    expect_err('Invalid value for argument', call, 'wait', 0, 1, 0)
+    expect_err('Invalid value for argument', call, 'wait', 0, 1, '')
+  end)
+end)