feat(api): broadcast events to ALL channels #28487

Problem:
`vim.rpcnotify(0)` and `rpcnotify(0)` are documented as follows:

    If {channel} is 0, the event is broadcast to all channels.

But that's not actually true. Channels must call `nvim_subscribe` to
receive "broadcast" events, so it's actually "multicast".

- Assuming there is a use-case for "broadcast", the current model adds
  an extra step for broadcasting: all channels need to "subscribe".
- The presence of `nvim_subscribe` is a source of confusion for users,
  because its name implies something more generally useful than what it
  does.

Presumably the use-case of `nvim_subscribe` is to avoid "noise" on RPC
channels not expected a broadcast notification, and potentially an error
if the channel client reports an unknown event.

Solution:
- Deprecate `nvim_subscribe`/`nvim_unsubscribe`.
  - If applications want to multicast, they can keep their own multicast
    list. Or they can use `nvim_list_chans()` and `nvim_get_chan_info()`
    to enumerate and filter the clients they want to target.
- Always send "broadcast" events to ALL channels. Don't require channels
  to "subscribe" to receive broadcasts. This matches the documented
  behavior of `rpcnotify()`.

3 files changed, 67 insertions, 72 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 13884e865d..2aa147770d 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -1461,24 +1461,6 @@ nvim_strwidth({text})                                        *nvim_strwidth()*
     Return: ~
         Number of cells
 
-nvim_subscribe({event})                                     *nvim_subscribe()*
-    Subscribes to event broadcasts.
-
-    Attributes: ~
-        |RPC| only
-
-    Parameters: ~
-      • {event}  Event type string
-
-nvim_unsubscribe({event})                                 *nvim_unsubscribe()*
-    Unsubscribes to event broadcasts.
-
-    Attributes: ~
-        |RPC| only
-
-    Parameters: ~
-      • {event}  Event type string
-
 nvim__complete_set({index}, {opts})                     *nvim__complete_set()*
     EXPERIMENTAL: this API may change in the future.
 
diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index 3fc2d872f6..646ba72bd8 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -12,76 +12,82 @@ They should not be used in new scripts, and old scripts should be updated.
 ==============================================================================
 Deprecated features
 
-DEPRECATED IN 0.11 *deprecated-0.11*
+------------------------------------------------------------------------------
+DEPRECATED IN 0.11					*deprecated-0.11*
+
+API
+- nvim_subscribe()	Plugins must maintain their own "multicast" channels list.
+- nvim_unsubscribe()	Plugins must maintain their own "multicast" channels list.
 
-• N/A
 
-DEPRECATED IN 0.10 *deprecated-0.10*
+------------------------------------------------------------------------------
+DEPRECATED IN 0.10					*deprecated-0.10*
 
+API
+• *nvim_buf_get_option()*	Use |nvim_get_option_value()| instead.
+• *nvim_buf_set_option()*	Use |nvim_set_option_value()| instead.
+• *nvim_call_atomic()*		Use |nvim_exec_lua()| instead.
+• *nvim_get_option()*		Use |nvim_get_option_value()| instead.
+• *nvim_set_option()*		Use |nvim_set_option_value()| instead.
+• *nvim_win_get_option()*	Use |nvim_get_option_value()| instead.
+• *nvim_win_set_option()*	Use |nvim_set_option_value()| instead.
+
+CHECKHEALTH
+• *health#report_error* *vim.health.report_error()*	Use |vim.health.error()| instead.
+• *health#report_info* *vim.health.report_info()*	Use |vim.health.info()| instead.
+• *health#report_ok* *vim.health.report_ok()*		Use |vim.health.ok()| instead.
+• *health#report_start* *vim.health.report_start()*	Use |vim.health.start()| instead.
+• *health#report_warn* *vim.health.report_warn()*	Use |vim.health.warn()| instead.
+
+DIAGNOSTICS
 • Configuring |diagnostic-signs| using |:sign-define| or |sign_define()|. Use
   the "signs" key of |vim.diagnostic.config()| instead.
-
-• Checkhealth functions:
-  - *health#report_error* *vim.health.report_error()*	Use |vim.health.error()| instead.
-  - *health#report_info* *vim.health.report_info()*	Use |vim.health.info()| instead.
-  - *health#report_ok* *vim.health.report_ok()*		Use |vim.health.ok()| instead.
-  - *health#report_start* *vim.health.report_start()*	Use |vim.health.start()| instead.
-  - *health#report_warn* *vim.health.report_warn()*	Use |vim.health.warn()| instead.
-
-• |API| functions:
-  - *nvim_buf_get_option()*	Use |nvim_get_option_value()| instead.
-  - *nvim_buf_set_option()*	Use |nvim_set_option_value()| instead.
-  - *nvim_call_atomic()*		Use |nvim_exec_lua()| instead.
-  - *nvim_get_option()*		Use |nvim_get_option_value()| instead.
-  - *nvim_set_option()*		Use |nvim_set_option_value()| instead.
-  - *nvim_win_get_option()*	Use |nvim_get_option_value()| instead.
-  - *nvim_win_set_option()*	Use |nvim_set_option_value()| instead.
-
 • vim.diagnostic functions:
-  - *vim.diagnostic.disable()*		Use |vim.diagnostic.enable()|
-  - *vim.diagnostic.is_disabled()*	Use |vim.diagnostic.is_enabled()|
-  - Legacy signature: `vim.diagnostic.enable(buf:number, namespace:number)`
-
-• vim.lsp functions:
-  - *vim.lsp.util.get_progress_messages()*	Use |vim.lsp.status()| instead.
-  - *vim.lsp.get_active_clients()*		Use |vim.lsp.get_clients()| instead.
-  - *vim.lsp.for_each_buffer_client()*		Use |vim.lsp.get_clients()| instead.
-  - *vim.lsp.util.trim_empty_lines()*		Use |vim.split()| with `trimempty` instead.
-  - *vim.lsp.util.try_trim_markdown_code_blocks()*
-  - *vim.lsp.util.set_lines()*
-  - *vim.lsp.util.extract_completion_items()*
-  - *vim.lsp.util.parse_snippet()*
-  - *vim.lsp.util.text_document_completion_list_to_complete_items()*
-  - *vim.lsp.util.lookup_section()*		Use |vim.tbl_get()| instead: >
+  • *vim.diagnostic.disable()*		Use |vim.diagnostic.enable()|
+  • *vim.diagnostic.is_disabled()*	Use |vim.diagnostic.is_enabled()|
+  • Legacy signature: `vim.diagnostic.enable(buf:number, namespace:number)`
+
+LSP
+• *vim.lsp.util.get_progress_messages()*	Use |vim.lsp.status()| instead.
+• *vim.lsp.get_active_clients()*		Use |vim.lsp.get_clients()| instead.
+• *vim.lsp.for_each_buffer_client()*		Use |vim.lsp.get_clients()| instead.
+• *vim.lsp.util.trim_empty_lines()*		Use |vim.split()| with `trimempty` instead.
+• *vim.lsp.util.try_trim_markdown_code_blocks()*
+• *vim.lsp.util.set_lines()*
+• *vim.lsp.util.extract_completion_items()*
+• *vim.lsp.util.parse_snippet()*
+• *vim.lsp.util.text_document_completion_list_to_complete_items()*
+• *vim.lsp.util.lookup_section()*		Use |vim.tbl_get()| instead: >
 						local keys = vim.split(section, '.', { plain = true })
 						local  vim.tbl_get(table, unpack(keys))
 
+LUA
 • *vim.loop*				Use |vim.uv| instead.
+• *vim.tbl_add_reverse_lookup()*
+• *vim.tbl_flatten()*			Use |Iter:flatten()| instead.
+• *vim.tbl_islist()*			Use |vim.islist()| instead.
 
-• vim.treesitter functions:
-  - *LanguageTree:for_each_child()*		Use |LanguageTree:children()| (non-recursive) instead.
-
+OPTIONS
 • The "term_background" UI option |ui-ext-options| is deprecated and no longer
   populated. Background color detection is now performed in Lua by the Nvim
   core, not the TUI.
 
-• Lua stdlib:
-  - *vim.tbl_add_reverse_lookup()*
-  - *vim.tbl_flatten()*			Use |Iter:flatten()| instead.
-  - *vim.tbl_islist()*			Use |vim.islist()| instead.
-
-DEPRECATED IN 0.9 *deprecated-0.9*
+TREESITTER
+• *LanguageTree:for_each_child()*	Use |LanguageTree:children()| (non-recursive) instead.
 
-• vim.treesitter functions
-  - *vim.treesitter.language.require_language()*	Use |vim.treesitter.language.add()| instead.
-  - *vim.treesitter.get_node_at_pos()*			Use |vim.treesitter.get_node()| instead.
-  - *vim.treesitter.get_node_at_cursor()*		Use |vim.treesitter.get_node()|
-							and |TSNode:type()| instead.
 
-• |API| functions:
-  - *nvim_get_hl_by_name()*		Use |nvim_get_hl()| instead.
-  - *nvim_get_hl_by_id()*		Use |nvim_get_hl()| instead.
+------------------------------------------------------------------------------
+DEPRECATED IN 0.9					*deprecated-0.9*
 
+API
+- *nvim_get_hl_by_name()*		Use |nvim_get_hl()| instead.
+- *nvim_get_hl_by_id()*			Use |nvim_get_hl()| instead.
+
+TREESITTER
+- *vim.treesitter.language.require_language()*	Use |vim.treesitter.language.add()| instead.
+- *vim.treesitter.get_node_at_pos()*		Use |vim.treesitter.get_node()| instead.
+- *vim.treesitter.get_node_at_cursor()*		Use |vim.treesitter.get_node()|
+						and |TSNode:type()| instead.
 • The following top level Treesitter functions have been moved:
   - *vim.treesitter.inspect_language()*    -> |vim.treesitter.language.inspect()|
   - *vim.treesitter.get_query_files()*     -> |vim.treesitter.query.get_files()|
@@ -98,10 +104,12 @@ DEPRECATED IN 0.9 *deprecated-0.9*
   - *vim.treesitter.query.get_range()*     -> |vim.treesitter.get_range()|
   - *vim.treesitter.query.get_node_text()* -> |vim.treesitter.get_node_text()|
 
-• Lua stdlib:
+LUA
   - *nvim_exec()*				Use |nvim_exec2()| instead.
   - *vim.pretty_print()*			Use |vim.print()| instead.
 
+
+------------------------------------------------------------------------------
 DEPRECATED IN 0.8 OR EARLIER
 
 API
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index a1859d19cf..0730faa441 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -25,7 +25,12 @@ These changes may require adaptations in your config or plugins.
 
 API
 
-• TODO
+• `vim.rpcnotify(0)` and `rpcnotify(0)` broadcast to ALL channels. Previously
+  they would "multicast" only to subscribed channels (controlled by
+  `nvim_subscribe()`). Plugins and clients that want "multicast" behavior must
+  now maintain their own list of channels.
+  • In the future, |vim.rpcnotify()| may accept a list of channels, if there
+    is demand for this use-case.
 
 DEFAULTS