Make separate functions to start/stop live updates

runtime/doc/msgpack_rpc.txt

@@ -258,24 +258,24 @@ specific buffer. For example, in python >
 	import sys, neovim
 	nvim = neovim.attach('stdio')
 	bufnr = sys.argv[1]
-	nvim.buffers[bufnr].live_updates(True)
+	nvim.buffers[bufnr].live_updates_start(True)
 
-After the `"nvim_buf_live_updates"` method is called, neovim will send a
+After the `"nvim_buf_live_updates_start"` method is called with Argument `"True"`,
-series of notifications containing the entire buffer's contents and any
+neovim will send a series of notifications containing the entire buffer's
-subsequent changes. The buffer's contents are sent via notifications because
+contents and any subsequent changes. The buffer's contents are sent via
-if you were to use the other API methods to retrieve the buffer contents, the
+notifications because if you were to use the other API methods to retrieve the
-buffer could be changed again before you turn on live updates. This can cause
+buffer contents, the buffer could be changed again before you turn on live
-a delay if your plugin activates live updates for a very large buffer, but it
+updates. This can cause a delay if your plugin activates live updates for a
-is the the most efficient way to maintain a copy of the entire buffer's
+very large buffer, but it is the the most efficient way to maintain a copy of
-contents inside your plugin.
+the entire buffer's contents inside your plugin.
 
 						      *live-updates-disabling*
 Turning Off~
 
-You can use `"nvim_buf_live_updates"` with an argument of `False` to turn off
+You can use `"nvim_buf_live_updates_stop"` to turn off notifications. One
-notifications. One final notification will be sent to indicate that live
+final notification will be sent to indicate that live updates are no longer
-updates are no longer active for the specified buffer. Alternatively, you can
+active for the specified buffer. Alternatively, you can just close the
-just close the channel.
+channel.
 
 						    *live-updates-limitations*
 Limitations~

src/nvim/api/buffer.c

@@ -78,15 +78,14 @@ String buffer_get_line(Buffer buffer, Integer index, Error *err)
 
 /// Activate live updates from this buffer to the current channel.
 ///
-///
 /// @param buffer The buffer handle
-/// @param enabled True turns on live updates, False turns them off.
+/// @param send_buffer Set to true if the initial notification should contain
+///        the whole buffer
 /// @param[out] err Details of an error that may have occurred
 /// @return False when live updates couldn't be enabled because the buffer isn't
 ///         loaded; otherwise True.
-Boolean nvim_buf_live_updates(uint64_t channel_id,
+Boolean nvim_buf_live_updates_start(uint64_t channel_id,
                               Buffer buffer,
-                              Boolean enabled,
                               Boolean send_buffer,
                               Error *err)
   FUNC_API_SINCE(4) FUNC_API_REMOTE_ONLY
@@ -97,8 +96,25 @@ Boolean nvim_buf_live_updates(uint64_t channel_id,
     return false;
   }
 
-  if (enabled) {
+  return liveupdate_register(buf, channel_id, send_buffer);
-    return liveupdate_register(buf, channel_id, send_buffer);
+
+}
+//
+/// Deactivate live updates from this buffer to the current channel.
+///
+/// @param buffer The buffer handle
+/// @param[out] err Details of an error that may have occurred
+/// @return False when live updates couldn't be disabled because the buffer
+///         isn't loaded; otherwise True.
+Boolean nvim_buf_live_updates_stop(uint64_t channel_id,
+                              Buffer buffer,
+                              Error *err)
+  FUNC_API_SINCE(4) FUNC_API_REMOTE_ONLY
+{
+  buf_T *buf = find_buffer_by_handle(buffer, err);
+
+  if (!buf) {
+    return false;
   }
 
   liveupdate_unregister(buf, channel_id);

test/functional/api/liveupdate_spec.lua

@@ -39,7 +39,7 @@ function open(activate, lines)
   -- turn on live updates, ensure that the LiveUpdateStart messages
   -- arrive as expectected
   if activate then
-    ok(buffer('live_updates', b, true, true))
+    ok(buffer('live_updates_start', b, true))
     expectn('LiveUpdateStart', {b, tick, lines, false})
   end
 
@@ -47,12 +47,12 @@ function open(activate, lines)
 end
 
 function reopen(buf, expectedlines)
-  ok(buffer('live_updates', buf, false, true))
+  ok(buffer('live_updates_stop', buf))
   expectn('LiveUpdateEnd', {buf})
   -- for some reason the :edit! increments tick by 2
   command('edit!')
   local tick = eval('b:changedtick')
-  ok(buffer('live_updates', buf, true, true))
+  ok(buffer('live_updates_start', buf, true))
   expectn('LiveUpdateStart', {buf, tick, origlines, false})
   command('normal! gg')
   return tick
@@ -161,20 +161,20 @@ describe('liveupdate', function()
     command('enew')
     local tick = eval('b:changedtick')
     b2 = nvim('get_current_buf')
-    ok(buffer('live_updates', b2, true, true))
+    ok(buffer('live_updates_start', b2, true))
     expectn('LiveUpdateStart', {b2, tick, {""}, false})
     eval('append(0, ["new line 1"])')
     tick = tick + 1
     expectn('LiveUpdate', {b2, tick, 0, 0, {'new line 1'}})
 
     -- turn off live updates manually
-    buffer('live_updates', b2, false, true)
+    buffer('live_updates_stop', b2)
     expectn('LiveUpdateEnd', {b2})
 
     -- add multiple lines to a blank file
     command('enew!')
     b3 = nvim('get_current_buf')
-    ok(buffer('live_updates', b3, true, true))
+    ok(buffer('live_updates_start', b3, true))
     tick = eval('b:changedtick')
     expectn('LiveUpdateStart', {b3, tick, {""}, false})
     eval('append(0, ["new line 1", "new line 2", "new line 3"])')
@@ -267,7 +267,7 @@ describe('liveupdate', function()
     tick = 2
     expectn('LiveUpdateEnd', {b})
     bnew = nvim('get_current_buf')
-    ok(buffer('live_updates', bnew, true, true))
+    ok(buffer('live_updates_start', bnew, true))
     expectn('LiveUpdateStart', {bnew, tick, {''}, false})
     sendkeys('i')
     sendkeys('h')
@@ -440,21 +440,21 @@ describe('liveupdate', function()
     local b, tick = editoriginal(false)
 
     -- turn on live updates many times
-    ok(buffer('live_updates', b, true, true))
+    ok(buffer('live_updates_start', b, true))
-    ok(buffer('live_updates', b, true, true))
+    ok(buffer('live_updates_start', b, true))
-    ok(buffer('live_updates', b, true, true))
+    ok(buffer('live_updates_start', b, true))
-    ok(buffer('live_updates', b, true, true))
+    ok(buffer('live_updates_start', b, true))
-    ok(buffer('live_updates', b, true, true))
+    ok(buffer('live_updates_start', b, true))
     expectn('LiveUpdateStart', {b, tick, origlines, false})
     eval('rpcnotify('..channel..', "Hello There")')
     expectn('Hello There', {})
 
     -- turn live updates off many times
-    ok(buffer('live_updates', b, false, true))
+    ok(buffer('live_updates_stop', b))
-    ok(buffer('live_updates', b, false, true))
+    ok(buffer('live_updates_stop', b))
-    ok(buffer('live_updates', b, false, true))
+    ok(buffer('live_updates_stop', b))
-    ok(buffer('live_updates', b, false, true))
+    ok(buffer('live_updates_stop', b))
-    ok(buffer('live_updates', b, false, true))
+    ok(buffer('live_updates_stop', b))
     expectn('LiveUpdateEnd', {b})
     eval('rpcnotify('..channel..', "Hello Again")')
     expectn('Hello Again', {})
@@ -493,9 +493,9 @@ describe('liveupdate', function()
     local b, tick = open(false, lines)
 
     -- turn on live updates for sessions 1, 2 and 3
-    ok(request(1, 'nvim_buf_live_updates', b, true, true))
+    ok(request(1, 'nvim_buf_live_updates_start', b, true))
-    ok(request(2, 'nvim_buf_live_updates', b, true, true))
+    ok(request(2, 'nvim_buf_live_updates_start', b, true))
-    ok(request(3, 'nvim_buf_live_updates', b, true, true))
+    ok(request(3, 'nvim_buf_live_updates_start', b, true))
     wantn(1, 'LiveUpdateStart', {b, tick, lines, false})
     wantn(2, 'LiveUpdateStart', {b, tick, lines, false})
     wantn(3, 'LiveUpdateStart', {b, tick, lines, false})
@@ -508,7 +508,7 @@ describe('liveupdate', function()
     wantn(3, 'LiveUpdate', {b, tick, 0, 1, {'AA'}})
 
     -- stop watching on channel 1
-    ok(request(1, 'nvim_buf_live_updates', b, false, true))
+    ok(request(1, 'nvim_buf_live_updates_stop', b))
     wantn(1, 'LiveUpdateEnd', {b})
 
     -- undo the change to buffer 1
@@ -735,7 +735,7 @@ describe('liveupdate', function()
   it('doesn\'t send the buffer\'s content when not requested', function()
     helpers.clear()
     local b, tick = editoriginal(false)
-    ok(buffer('live_updates', b, true, false))
+    ok(buffer('live_updates_start', b, false))
     expectn('LiveUpdateStart', {b, tick, {}, false})
   end)