f - Update lock order docs

Author: ViktorTigerstrom

lightning/src/ln/channelmanager.rs

@@ -667,6 +667,20 @@ pub type SimpleRefChannelManager<'a, 'b, 'c, 'd, 'e, M, T, F, L> = ChannelManage
 /// essentially you should default to using a SimpleRefChannelManager, and use a
 /// SimpleArcChannelManager when you require a ChannelManager with a static lifetime, such as when
 /// 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`
+//
+// 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`
 pub struct ChannelManager<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref>
 	where M::Target: chain::Watch<Signer>,
         T::Target: BroadcasterInterface,
@@ -695,12 +709,6 @@ 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.
-	///
-	/// If any of these locks are held at the same time, they must be acquired prior and in the
-	/// following order:
-	/// * `channel_state`
-	/// * `forward_htlcs`
-	/// * `per_peer_state`
 	pending_inbound_payments: Mutex<HashMap<PaymentHash, PendingInboundPayment>>,
 
 	/// The session_priv bytes and retry metadata of outbound payments which are pending resolution.
@@ -713,13 +721,6 @@ pub struct ChannelManager<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref,
 	/// after reloading from disk while replaying blocks against ChannelMonitors.
 	///
 	/// See `PendingOutboundPayment` documentation for more info.
-	///
-	/// If any of these locks are held at the same time as, they must be acquired prior and in the
-	/// following order:
-	/// * `channel_state`
-	/// * `forward_htlcs`
-	/// * `per_peer_state`
-	/// * `pending_inbound_payments`
 	pending_outbound_payments: Mutex<HashMap<PaymentId, PendingOutboundPayment>>,
 
 	/// SCID/SCID Alias -> forward infos. Key of 0 means payments received.
@@ -730,8 +731,6 @@ pub struct ChannelManager<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref,
 	///
 	/// Note that no consistency guarantees are made about the existence of a channel with the
 	/// `short_channel_id` here, nor the `short_channel_id` in the `PendingHTLCInfo`!
-	///
-	/// Locked *after* `channel_state`.
 	#[cfg(test)]
 	pub(super) forward_htlcs: Mutex<HashMap<u64, Vec<HTLCForwardInfo>>>,
 	#[cfg(not(test))]
@@ -760,8 +759,6 @@ pub struct ChannelManager<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref,
 	/// We should add `counterparty_node_id`s to `MonitorEvent`s, and eventually rely on it in the
 	/// future. That would make this map redundant, as only the `ChannelManager::per_peer_state` is
 	/// required to access the channel with the `counterparty_node_id`.
-	///
-	/// Locked *after* `channel_state`.
 	id_to_peer: Mutex<HashMap<[u8; 32], PublicKey>>,
 
 	our_network_key: SecretKey,
@@ -792,29 +789,10 @@ pub struct ChannelManager<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref,
 	/// Because adding or removing an entry is rare, we usually take an outer read lock and then
 	/// operate on the inner value freely. Sadly, this prevents parallel operation when opening a
 	/// new channel.
-	///
-	/// If any of these locks are held at the same time, they must be acquired prior and in the
-	/// following order:
-	/// * `channel_state`
-	/// * `forward_htlcs`
 	per_peer_state: RwLock<HashMap<PublicKey, Mutex<PeerState>>>,
 
-	/// If any of these locks are held at the same time, they must be acquired prior and in the
-	/// following order:
-	/// * `channel_state`
-	/// * `forward_htlcs`
-	/// * `per_peer_state`
-	/// * `pending_inbound_payments`
-	/// * `pending_outbound_payments`
 	pending_events: Mutex<Vec<events::Event>>,
-	/// If any of these locks are held at the same time, they must be acquired prior and in the
-	/// following order:
-	/// * `channel_state`
-	/// * `forward_htlcs`
-	/// * `per_peer_state`
-	/// * `pending_inbound_payments`
-	/// * `pending_outbound_payments`
-	/// * `pending_events`
+
 	pending_background_events: Mutex<Vec<BackgroundEvent>>,
 	/// Used when we have to take a BIG lock to make sure everything is self-consistent.
 	/// Essentially just when we're serializing ourselves out.