f describe locking structure a bit more

Author: TheBlueMatt

lightning/src/ln/peer_handler.rs

@@ -420,10 +420,14 @@ pub struct PeerManager<Descriptor: SocketDescriptor, CM: Deref, RM: Deref, L: De
 		L::Target: Logger,
 		CMH::Target: CustomMessageHandler {
 	message_handler: MessageHandler<CM, RM>,
-	/// Peer is under its own mutex for sending and receiving bytes, but note that we do *not* hold
-	/// this mutex while we're processing a message. This is fine as [`PeerManager::read_event`]
-	/// requires that there be no parallel calls for a given peer, so mutual exclusion of messages
-	/// handed to the `MessageHandler`s for a given peer is already guaranteed.
+	/// Connection state for each connected peer - we have an outer read-write lock which is taken
+	/// as read while we're doing processing for a peer and taken write when a peer is being added
+	/// or removed.
+	///
+	/// The inner Peer lock is held for sending and receiving bytes, but note that we do *not* hold
+	/// it while we're processing a message. This is fine as [`PeerManager::read_event`] requires
+	/// that there be no parallel calls for a given peer, so mutual exclusion of messages handed to
+	/// the `MessageHandler`s for a given peer is already guaranteed.
 	peers: FairRwLock<HashMap<Descriptor, Mutex<Peer>>>,
 	/// Only add to this set when noise completes.
 	/// Locked *after* peers. When an item is removed, it must be removed with the `peers` write