Doc: Add documentation for AsyncRuntime::Watch traits

[drmingdrmer]

Changelog

Doc: Add documentation for AsyncRuntime::Watch traits

Add comprehensive documentation for the Watch trait and its associated traits
in the AsyncRuntime module. This improves code clarity and helps developers
understand the purpose and usage and behavior of these traits.

• Fix: Improper use of Raft::metrics() can block the RaftCore async task and underlying OS thread #1238

---

This change is 

[SteveLauC]

LGTM, just some nits:)

Reviewed all commit messages.
Reviewable status: 0 of 1 files reviewed, 3 unresolved discussions (waiting on @drmingdrmer)

---

openraft/src/type_config/async_runtime/watch/mod.rs line 12 at r1 (raw file):

/// A `Watch` is a pair of `WatchSender` and `WatchReceiver` that can be used to watch for changes
/// to a value.
/// A multi-producer, multi-consumer channel that only retains the last sent value.

Our WatchSender trait does not have Clone as its supertrait, so technically, it is not a multi-producer channel, though tokio::sync::watch::Sender has Clone implemented:>

---

openraft/src/type_config/async_runtime/watch/mod.rs line 38 at r1 (raw file):

    /// ```text
    /// // Task 1 (on thread A)    |  // Task 2 (on thread B)
    /// let _ref1 = rx.borrow();   |

- /// let _ref1 = rx.borrow();   |
+ /// let _ref1 = rx.borrow_watched();   |

In our impl, we call this method borrow_watched() 😀

---

openraft/src/type_config/async_runtime/watch/mod.rs line 42 at r1 (raw file):

    ///                            |  let _ = tx.send(());
    /// // may deadlock            |
    /// let _ref2 = rx.borrow();   |

Same as above.

[drmingdrmer]

Thank you for your detailed review and suggestions!

Reviewable status: 0 of 1 files reviewed, 3 unresolved discussions (waiting on @SteveLauC)

---

openraft/src/type_config/async_runtime/watch/mod.rs line 12 at r1 (raw file):

Previously, SteveLauC (SteveLauC) wrote…

Our WatchSender trait does not have Clone as its supertrait, so technically, it is not a multi-producer channel, though tokio::sync::watch::Sender has Clone implemented:>

Done.

---

openraft/src/type_config/async_runtime/watch/mod.rs line 38 at r1 (raw file):

Previously, SteveLauC (SteveLauC) wrote…

- /// let _ref1 = rx.borrow();   |
+ /// let _ref1 = rx.borrow_watched();   |

In our impl, we call this method borrow_watched() 😀

Done.

---

openraft/src/type_config/async_runtime/watch/mod.rs line 42 at r1 (raw file):

Previously, SteveLauC (SteveLauC) wrote…

Same as above.

Done.

[SteveLauC]

Reviewable status: 0 of 1 files reviewed, 3 unresolved discussions