Add lock order docs to ChannelManager fields

Author: ViktorTigerstrom

lightning/src/ln/channelmanager.rs

@@ -697,7 +697,12 @@ 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.
-	/// Locked *after* channel_state.
+	///
+	/// If any of these locks are held at the same time as `pending_inbound_payments`, the lock
+	/// order requires that these locks are taken prior to `pending_inbound_payments`:
+	/// * `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.
@@ -711,7 +716,12 @@ pub struct ChannelManager<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref,
 	///
 	/// See `PendingOutboundPayment` documentation for more info.
 	///
-	/// Locked *after* channel_state.
+	/// If any of these locks are held at the same time as `pending_outbound_payments`, the lock
+	/// order requires that these locks are taken prior to `pending_outbound_payments`:
+	/// * `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.
@@ -722,6 +732,8 @@ 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`!
+	///
+	/// If also holding `channel_state` lock, must lock `channel_state` prior to `forward_htlcs`.
 	#[cfg(any(test, feature = "_test_utils"))]
 	pub(super) forward_htlcs: Mutex<HashMap<u64, Vec<HTLCForwardInfo>>>,
 	#[cfg(not(any(test, feature = "_test_utils")))]
@@ -785,10 +797,28 @@ pub struct ChannelManager<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref,
 	/// operate on the inner value freely. Sadly, this prevents parallel operation when opening a
 	/// new channel.
 	///
-	/// If also holding `channel_state` lock, must lock `channel_state` prior to `per_peer_state`.
+	/// If any of these locks are held at the same time as `per_peer_state`, the lock order
+	/// requires that these locks are taken prior to `per_peer_state`:
+	/// * `channel_state`
+	/// * `forward_htlcs`
 	per_peer_state: RwLock<HashMap<PublicKey, Mutex<PeerState>>>,
 
+	/// If any of these locks are held at the same time as `pending_events`, the lock order
+	/// requires that these locks are taken prior to `pending_events`:
+	/// * `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 as `pending_background_events`, the lock
+	/// order requires that these locks are taken prior to `pending_background_events`:
+	/// * `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.