I wanted to consolidate my understanding of the states delivered via NWListener.stateUpdateHandler for ConnectedUDP and verify if this interpretation is correct.
From what I understand, the following states can occur:
.setup
This state occurs immediately after creating the NWListener instance and persists until start(queue:) is called.
.waiting
This occurs when the listener is unable to bind or become ready at that moment, but may recover.
Typical scenarios include:
Required network interface is temporarily unavailable
Port is temporarily unavailable (e.g., already in use but may be released)
Local network permission has not yet been granted
.ready
This occurs when the listener has successfully bound to a port and selected a viable interface/path. At this point, it is ready to receive incoming traffic.
.failed
This represents a non-recoverable error that prevents the listener from functioning.
Typical scenarios include:
Invalid parameters during initialization (e.g., EINVAL)
Binding to an invalid or unavailable address (EADDRNOTAVAIL)
Permission explicitly denied (EACCES)
Port in use by another long-lived process (EADDRINUSE)
.cancelled
This occurs after cancel() is explicitly called on the listener and represents a terminal state.
State Transition Understanding
Based on this, my current understanding is:
Once the listener transitions out of .setup, it does not return to .setup.
In the normal (“happy path”) case, the state progression is: .setup → .ready → .cancelled
.waiting is a recoverable state, whereas .failed is non-recoverable. In other words, once the listener enters .failed, it will not transition to any other state except .cancelled.
Topic:
App & System Services
SubTopic:
Networking
Tags: