From 3ea10077534cb1dcb1597ffcf85e601fa0c0e27b Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Mon, 13 Mar 2017 15:02:37 +0100
Subject: api: nvim_get_mode()
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Asynchronous API functions are served immediately, which means pending
input could change the state of Nvim shortly after an async API function
result is returned.

nvim_get_mode() is different:
  - If RPCs are known to be blocked, it responds immediately (without
    flushing the input/event queue)
  - else it is handled just-in-time before waiting for input, after
    pending input was processed. This makes the result more reliable
    (but not perfect).

Internally this is handled as a special case, but _semantically_ nothing
has changed: API users never know when input flushes, so this internal
special-case doesn't violate that. As far as API users are concerned,
nvim_get_mode() is just another asynchronous API function.

In all cases nvim_get_mode() never blocks for more than the time it
takes to flush the input/event queue (~µs).

Note: This doesn't address #6166; nvim_get_mode() will provoke #6166 if
e.g. `d` is operator-pending.

Closes #6159
---
 src/nvim/api/vim.c | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

(limited to 'src/nvim/api')

diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index da00fbc6e3..7c57a5b456 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -11,6 +11,7 @@
 
 #include "nvim/api/vim.h"
 #include "nvim/ascii.h"
+#include "nvim/log.h"
 #include "nvim/api/private/helpers.h"
 #include "nvim/api/private/defs.h"
 #include "nvim/api/buffer.h"
@@ -27,6 +28,7 @@
 #include "nvim/eval.h"
 #include "nvim/eval/typval.h"
 #include "nvim/option.h"
+#include "nvim/state.h"
 #include "nvim/syntax.h"
 #include "nvim/getchar.h"
 #include "nvim/os/input.h"
@@ -701,6 +703,25 @@ Dictionary nvim_get_color_map(void)
 }
 
 
+/// Gets the current mode.
+/// mode:     Mode string. |mode()|
+/// blocking: true if Nvim is waiting for input.
+///
+/// @returns Dictionary { "mode": String, "blocking": Boolean }
+Dictionary nvim_get_mode(void)
+  FUNC_API_SINCE(2) FUNC_API_ASYNC
+{
+  Dictionary rv = ARRAY_DICT_INIT;
+  char *modestr = get_mode();
+  bool blocked = input_blocking();
+  ILOG("blocked=%d", blocked);
+
+  PUT(rv, "mode", STRING_OBJ(cstr_as_string(modestr)));
+  PUT(rv, "blocking", BOOLEAN_OBJ(blocked));
+
+  return rv;
+}
+
 Array nvim_get_api_info(uint64_t channel_id)
     FUNC_API_SINCE(1) FUNC_API_ASYNC FUNC_API_NOEVAL
 {
-- 
cgit