f - Add Lock order tree, and update docs

Author: ViktorTigerstrom

lightning/src/ln/channelmanager.rs

@@ -669,18 +669,28 @@ pub type SimpleRefChannelManager<'a, 'b, 'c, 'd, 'e, M, T, F, L> = ChannelManage
 /// you're using lightning-net-tokio.
 //
 // Lock order:
-// These `ChannelManager` locks should be aquired in the following lock order, if any of these
-// locks are held at the same time:
-// 1. `channel_state`
-// 2. `per_peer_state`
-// 3. `pending_inbound_payments`
-// 4. `pending_outbound_payments`
-// 5. `pending_events`
-// 6. `pending_background_events`
+// The tree structure below illustrates the lock order requirements for the different locks of the
+// `ChannelManager`. If two or more locks on the same branch is held at the same time, locks should
+// be taken in the order of the lowest to highest level in the tree.
 //
-// These locks should be aquired after the `channel_state` lock, in case the `channel_state` lock
-// is taken at the same time:
-// * `id_to_peer`
+// Lock order tree:
+// │
+// │──`channel_state`
+// │   │
+// │   │──`id_to_peer`
+// │   │
+// │   │──`per_peer_state`
+// │       │
+// │       │──`best_block`
+// │       │
+// │       │──`pending_inbound_payments`
+// │           │
+// │           │──`pending_outbound_payments`
+// │               │
+// │               │──`pending_events`
+// │                   │
+// │                   │──`pending_background_events`
+// │
 pub struct ChannelManager<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref>
 	where M::Target: chain::Watch<Signer>,
         T::Target: BroadcasterInterface,
@@ -694,12 +704,14 @@ pub struct ChannelManager<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref,
 	chain_monitor: M,
 	tx_broadcaster: T,
 
+	/// See `ChannelManager` struct-level documentation for lock order requirements.
 	#[cfg(test)]
 	pub(super) best_block: RwLock<BestBlock>,
 	#[cfg(not(test))]
 	best_block: RwLock<BestBlock>,
 	secp_ctx: Secp256k1<secp256k1::All>,
 
+	/// See `ChannelManager` struct-level documentation for lock order requirements.
 	#[cfg(any(test, feature = "_test_utils"))]
 	pub(super) channel_state: Mutex<ChannelHolder<Signer>>,
 	#[cfg(not(any(test, feature = "_test_utils")))]
@@ -709,6 +721,8 @@ pub struct ChannelManager<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref,
 	/// expose them to users via a PaymentReceived event. HTLCs which do not meet the requirements
 	/// here are failed when we process them as pending-forwardable-HTLCs, and entries are removed
 	/// after we generate a PaymentReceived upon receipt of all MPP parts or when they time out.
+	///
+	/// See `ChannelManager` struct-level documentation for lock order requirements.
 	pending_inbound_payments: Mutex<HashMap<PaymentHash, PendingInboundPayment>>,
 
 	/// The session_priv bytes and retry metadata of outbound payments which are pending resolution.