@@ -251,21 +251,22 @@ data ValidLocalEndPointState = ValidLocalEndPointState
251251--
252252-- Remote endpoints (basically, TCP connections) have the following lifecycle:
253253--
254−-- Init ----+---> Invalid
254+-- Init ---+---> Invalid
255255-- |
256−-- | /----------------\
257−-- | | |
258−-- | v |
259−-- +---> Valid ----+---> Closing
260−-- | | |
261−-- | | v
262−-- \---------------+---> Closed
256+-- | /--------------\
257+-- | | |
258+-- | v |
259+-- +---> Valid ---+---> Closing ---+---> Closed
260+-- | | | |
261+-- | | | v
262+-- \-------+--------------+------------> Failed
263263--
264264-- Init: There are two places where we create new remote endpoints: in
265265-- requestConnectionTo (in response to an API 'connect' call) and in
266266-- handleConnectionRequest (when a remote node tries to connect to us).
267267-- 'Init' carries an MVar () 'resolved' which concurrent threads can use to
268−-- wait for the remote endpoint to finish initialization.
268+-- wait for the remote endpoint to finish initialization. We record who
269+-- requested the connection (the local endpoint or the remote endpoint).
269270--
270271-- Invalid: We put the remote endpoint in invalid state only during
271272-- requestConnectionTo when we fail to connect.
@@ -281,8 +282,11 @@ data ValidLocalEndPointState = ValidLocalEndPointState
281282-- the request.
282283--
283284-- Closed: The endpoint is put in Closed state after a successful garbage
284−-- collection, when the endpoint (or the whole transport) is closed manually,
285−-- or when an IO exception occurs during communication.
285+-- collection.
286+--
287+-- Failed: If the connection to the remote endpoint is lost, or the local
288+-- endpoint (or the whole transport) is closed manually, the remote endpoint is
289+-- put in Failed state, and we record the reason.
286290--
287291-- Invariants for dealing with remote endpoints:
288292--
@@ -290,7 +294,7 @@ data ValidLocalEndPointState = ValidLocalEndPointState
290294-- interleaving bits of payload).
291295--
292296-- INV-CLOSE: Local endpoints should never point to remote endpoint in closed
293−-- state. Whenever we put an endpoint in closed state we remove that
297+-- state. Whenever we put an endpoint in Closed state we remove that
294298-- endpoint from localConnections first, so that if a concurrent thread reads
295299-- the MVar, finds RemoteEndPointClosed, and then looks up the endpoint in
296300-- localConnections it is guaranteed to either find a different remote