A Comprehensive Guide for iOS and Android

WebRTC is a fascinating technology that brings real-time communication capabilities to the web. While WebRTC is relatively easy to use, there are many intricacies to it, which, when not understood correctly, can lead to problems. One such issue is closing PeerConnections, especially in complex scenarios like mesh calling. Here, we will delve into the crux of the matter and learn how to overcome this challenge.

The Challenges Faced

I once spent more than a week trying to debug a seemingly straightforward issue. In a mesh calling scenario involving 8 participants from different platforms — Android and iOS, my application would become unresponsive and eventually crash. This was specifically happening on the iOS side when I was trying to close a PeerConnection while the other participants were still in the ‘connecting’ state. What seemed like a resource consumption crash was actually an issue with the main UI thread being blocked due to WebRTC background tasks.

Crash Catalog:

Over the past six months of intense and passionate development, we hadn’t experienced a crash quite like this one. It was an anomaly that had us puzzled. What was even more perplexing was that the crash reports indicated an issue of resource consumption — a possibility that hadn’t occurred to us in the context of a seemingly innocuous task of closing peer connections.

The iOS watchdog, meant to prevent any app from hogging system resources, ended up terminating our application. This signaled to us that something under the hood was indeed amiss.

Here are some screenshots of the crashes:

Test Flight Crash Report:

Date/Time:           2023-06-21 15:53:37.6520 +0500
Launch Time:         2023-06-21 15:43:18.2579 +0500
OS Version:          iPhone OS 16.5 (20F66)
Release Type:        User
Baseband Version:    4.02.01
Report Version:      104

Exception Type:  EXC_CRASH (SIGKILL)
Exception Codes: 0x0000000000000000, 0x0000000000000000
Termination Reason: FRONTBOARD 2343432205 
<RBSTerminateContext| domain:10 code:0x8BADF00D explanation:scene-update watchdog transgression: application<com.younite.development>:2048 exhausted real (wall clock) 
time allowance of 10.00 seconds
ProcessVisibility: Foreground
ProcessState: Running
WatchdogEvent: scene-update
WatchdogVisibility: Foreground
WatchdogCPUStatistics: (
"Elapsed total CPU time (seconds): 3.380 (user 3.380, system 0.000), 5% CPU",
"Elapsed application CPU time (seconds): 0.049, 0% CPU"
) reportType:CrashLog maxTerminationResistance:Interactive>

Triggered by Thread:  0

Thread 0 name:   Dispatch queue: com.apple.main-thread
Thread 0 Crashed:
0   libsystem_kernel.dylib                0x20bb88558 __psynch_cvwait + 8
1   libsystem_pthread.dylib               0x22c9d0078 _pthread_cond_wait + 1232
2   WebRTC                                0x109f92a20 0x109e4c000 + 1337888
3   WebRTC                                0x109f92900 0x109e4c000 + 1337600
4   WebRTC                                0x109ebe20c 0x109e4c000 + 467468
5   WebRTC                                0x109ebe10c 0x109e4c000 + 467212
6   WebRTC                                0x109ebda38 0x109e4c000 + 465464
7   WebRTC                                0x109ebda14 0x109e4c000 + 465428
8   WebRTC                                0x109f6b52c 0x109e4c000 + 1176876
9   libobjc.A.dylib                       0x1c5cb60a4 object_cxxDestructFromClass(objc_object*, objc_class*) + 116
10  libobjc.A.dylib                       0x1c5cbae00 objc_destructInstance + 80
11  libobjc.A.dylib                       0x1c5cc44fc _objc_rootDealloc + 80
12  libobjc.A.dylib                       0x1c5cb60a4 object_cxxDestructFromClass(objc_object*, objc_class*) + 116
13  libobjc.A.dylib                       0x1c5cbae00 objc_destructInstance + 80
14  libobjc.A.dylib                       0x1c5cc44fc _objc_rootDealloc + 80
15  WebRTC                                0x109f7302c 0x109e4c000 + 1208364
19  libswiftCore.dylib                    0x1c6d11628 _swift_release_dealloc + 56
20  libswiftCore.dylib                    0x1c6d1244c bool swift::RefCounts<swift::RefCountBitsT<(swift::RefCountInlinedness)1>>::doDecrementSlow<(swift::PerformDeinit)1>(swift::RefCountBitsT<(swift::RefCountInlinedness)1>, unsigned int) + 132
21  libswiftCore.dylib                    0x1c6d012c8 swift_arrayDestroy + 124
22  libswiftCore.dylib                    0x1c6a1c2b0 _DictionaryStorage.deinit + 468
23  libswiftCore.dylib                    0x1c6a1c31c _DictionaryStorage.__deallocating_deinit + 16
24  libswiftCore.dylib                    0x1c6d11628 _swift_release_dealloc + 56
25  libswiftCore.dylib                    0x1c6d1244c bool swift::RefCounts<swift::RefCountBitsT<(swift::RefCountInlinedness)1>>::doDecrementSlow<(swift::PerformDeinit)1>(swift::RefCountBitsT<(swift::RefCountInlinedness)1>, unsigned int) + 132
27  libswiftCore.dylib                    0x1c6d11628 _swift_release_dealloc + 56
28  libswiftCore.dylib                    0x1c6d1244c bool swift::RefCounts<swift::RefCountBitsT<(swift::RefCountInlinedness)1>>::doDecrementSlow<(swift::PerformDeinit)1>(swift::RefCountBitsT<(swift::RefCountInlinedness)1>, unsigned int) + 132
30  libsystem_blocks.dylib                0x22c9c5134 _call_dispose_helpers_excp + 48
31  libsystem_blocks.dylib                0x22c9c4d64 _Block_release + 252
32  libdispatch.dylib                     0x1d40eaeac _dispatch_client_callout + 20
33  libdispatch.dylib                     0x1d40f96a4 _dispatch_main_queue_drain + 928
34  libdispatch.dylib                     0x1d40f92f4 _dispatch_main_queue_callback_4CF + 44
35  CoreFoundation                        0x1cccb3c28 __CFRUNLOOP_IS_SERVICING_THE_MAIN_DISPATCH_QUEUE__ + 16
36  CoreFoundation                        0x1ccc95560 __CFRunLoopRun + 1992
37  CoreFoundation                        0x1ccc9a3ec CFRunLoopRunSpecific + 612
38  GraphicsServices                      0x20815f35c GSEventRunModal + 164
39  UIKitCore                             0x1cf0276e8 -[UIApplication _run] + 888
40  UIKitCore                             0x1cf02734c UIApplicationMain + 340
41  Younite                               0x101509d00 main + 64
42  dyld                                  0x1ec19adec start + 2220

While Debugging:

These crash reports provide a snapshot of the challenge we were up against. Through persistence and deep-dive analysis, we uncovered the core of the issue — a hiccup in our understanding and usage of the WebRTC protocol.

The Importance of Connection State

Before discussing the strategies to close peer connections, it’s important to understand the different states a connection can have. In WebRTC, the RTCPeerConnection.connectionState property can tell you about the current connection state. The possible states are:

• new: The connection has just been created and has not completed negotiation yet.
• connecting: The connection is in the process of negotiation.
• connected: The connection has been successfully negotiated and active data channels are open.
• disconnected: One or more transports are disconnected.
• failed: One or more transports has terminated or failed.
• closed: The connection is closed.

Before calling RTCPeerConnection.close(), it’s crucial to ensure that the connection is either connected or failed. Closing connections in transitional states (connecting or disconnected) can lead to issues and can cause the application to become unresponsive.

Unraveling PeerConnection::Close()

The PeerConnection::Close() function is at the heart of managing the lifecycle of a peer connection in WebRTC. This native function is responsible for the orderly shutdown of a connection. However, its behavior can be complex, with several conditional checks and sub-procedures that cater to different stages of the connection’s lifecycle.

In essence, this function first checks if the connection is already closed. If it’s not, it proceeds to update connection states, signalling its closure to any observers, and stops all transceivers. It also ensures all asynchronous stats requests are completed before destroying the transport controller. It then releases related resources like the voice/video/data channels, event log, and others.

This is the WebRTC Native Function, sourced from the active branches of Chromium’s WebRTC m115 branch-head: branch-heads/5790

void PeerConnection::Close() {
  RTC_DCHECK_RUN_ON(signaling_thread());
  TRACE_EVENT0("webrtc", "PeerConnection::Close");

  RTC_LOG_THREAD_BLOCK_COUNT();

  if (IsClosed()) {
    return;
  }
  // Update stats here so that we have the most recent stats for tracks and
  // streams before the channels are closed.
  legacy_stats_->UpdateStats(kStatsOutputLevelStandard);

  ice_connection_state_ = PeerConnectionInterface::kIceConnectionClosed;
  Observer()->OnIceConnectionChange(ice_connection_state_);
  standardized_ice_connection_state_ =
      PeerConnectionInterface::IceConnectionState::kIceConnectionClosed;
  connection_state_ = PeerConnectionInterface::PeerConnectionState::kClosed;
  Observer()->OnConnectionChange(connection_state_);

  sdp_handler_->Close();

  NoteUsageEvent(UsageEvent::CLOSE_CALLED);

  if (ConfiguredForMedia()) {
    for (const auto& transceiver : rtp_manager()->transceivers()->List()) {
      transceiver->internal()->SetPeerConnectionClosed();
      if (!transceiver->stopped())
        transceiver->StopInternal();
    }
  }
  // Ensure that all asynchronous stats requests are completed before destroying
  // the transport controller below.
  if (stats_collector_) {
    stats_collector_->WaitForPendingRequest();
  }

  // Don't destroy BaseChannels until after stats has been cleaned up so that
  // the last stats request can still read from the channels.
  sdp_handler_->DestroyAllChannels();

  // The event log is used in the transport controller, which must be outlived
  // by the former. CreateOffer by the peer connection is implemented
  // asynchronously and if the peer connection is closed without resetting the
  // WebRTC session description factory, the session description factory would
  // call the transport controller.
  sdp_handler_->ResetSessionDescFactory();
  if (ConfiguredForMedia()) {
    rtp_manager_->Close();
  }

  network_thread()->BlockingCall([this] {
    // Data channels will already have been unset via the DestroyAllChannels()
    // call above, which triggers a call to TeardownDataChannelTransport_n().
    // TODO(tommi): ^^ That's not exactly optimal since this is yet another
    // blocking hop to the network thread during Close(). Further still, the
    // voice/video/data channels will be cleared on the worker thread.
    RTC_DCHECK_RUN_ON(network_thread());
    transport_controller_.reset();
    port_allocator_->DiscardCandidatePool();
    if (network_thread_safety_) {
      network_thread_safety_->SetNotAlive();
    }
  });

  worker_thread()->BlockingCall([this] {
    RTC_DCHECK_RUN_ON(worker_thread());
    worker_thread_safety_->SetNotAlive();
    call_.reset();
    // The event log must outlive call (and any other object that uses it).
    event_log_.reset();
  });
  ReportUsagePattern();
  // The .h file says that observer can be discarded after close() returns.
  // Make sure this is true.
  observer_ = nullptr;

  // Signal shutdown to the sdp handler. This invalidates weak pointers for
  // internal pending callbacks.
  sdp_handler_->PrepareForShutdown();
}

The PeerConnection::Close() function is responsible for properly closing a WebRTC PeerConnection and cleaning up all related resources. Let’s break down what’s happening in this method:

1. RTC_DCHECK_RUN_ON(signaling_thread());: This line checks to ensure that the Close() method is being called from the signaling thread. The signaling thread is used for operations that change the state of the PeerConnection, such as handling SDP offers and answers, ICE candidates, and closing the connection.
2. if (IsClosed()) { return; }: This line checks if the PeerConnection is already closed. If so, the method immediately returns because there’s no work to do.
3. legacy_stats_->UpdateStats(kStatsOutputLevelStandard);: This line updates the statistics for the PeerConnection before it is closed.
4. The next few lines set the ICE connection state and the standard connection state to “closed”, and call the OnIceConnectionChange and OnConnectionChange methods on the observer (which could be an application that’s using the WebRTC library). This notifies the observer that the connection is now closed.
5. sdp_handler_->Close();: This line closes the SDP (Session Description Protocol) handler, which is responsible for handling the SDP offers and answers that are part of the WebRTC handshake process.
6. The next block of code stops all active transceivers if media is configured for the connection. A transceiver is a combination of a sender and a receiver for media (audio or video) data.
7. The next few lines clean up various resources associated with the PeerConnection, such as the transport controller (which handles the actual network transports used for the connection), the port allocator (which is used to find local and remote ports for the connection), and any ongoing statistics collections.
8. The call to observer_ = nullptr; removes the reference to the observer, as it’s no longer needed after the connection is closed.
9. Finally, the method calls sdp_handler_->PrepareForShutdown();, which prepares the SDP handler for shutdown by invalidating any weak pointers for internal pending callbacks.

Closing PeerConnections: Best Practices for Android & iOS

Here are some general guidelines to follow when closing peer connections, with examples tailored for Android and iOS platforms.

Android

Single PeerConnection Closure

// Assuming peerConnection is a PeerConnection object
fun disconnectPeer(peerConnection: PeerConnection) {
    // Check the connection state
    if (peerConnection.connectionState() == PeerConnection.PeerConnectionState.CONNECTED ||
        peerConnection.connectionState() == PeerConnection.PeerConnectionState.FAILED) {
        // Close each track
        peerConnection.localStreams.forEach { mediaStream ->
            mediaStream.videoTracks.forEach { it.setEnabled(false) }
            mediaStream.audioTracks.forEach { it.setEnabled(false) }
        }

        // Close the connection
        peerConnection.close()
    }

    // Nullify the reference
    peerConnection = null
}

Mesh Calling PeerConnection Closure

// Assuming peerConnections is a list of PeerConnection objects
fun disconnectPeers(peerConnections: MutableList<PeerConnection>) {
    peerConnections.forEach { peerConnection ->
        // Check the connection state
        if (peerConnection.connectionState() == PeerConnection.PeerConnectionState.CONNECTED ||
            peerConnection.connectionState() == PeerConnection.PeerConnectionState.FAILED) {
            // Close each track
            peerConnection.localStreams.forEach { mediaStream ->
                mediaStream.videoTracks.forEach { it.setEnabled(false) }
                mediaStream.audioTracks.forEach { it.setEnabled(false) }
            }

            // Close the connection
            peerConnection.close()
        }
    }

    // Clear the list
    peerConnections.clear()
}

iOS

Single PeerConnection Closure

// Assuming peerConnection is a RTCPeerConnection object
func disconnectPeer(peerConnection: RTCPeerConnection) {
    // Check the connection state
    if (peerConnection.connectionState == .connected || 
        peerConnection.connectionState == .failed) {
        // Close each track
        peerConnection.senders.forEach { sender in
            sender.track?.isEnabled = false
        }

        // Close the connection
        peerConnection.close()
    }

    // Nullify the reference
    peerConnection = nil
}

Mesh Calling PeerConnection Closure

// Assuming peerConnections is an array of RTCPeerConnection objects
func disconnectPeers(peerConnections: inout [RTCPeerConnection]) {
    peerConnections.forEach { peerConnection in
        // Check the connection state
        if (peerConnection.connectionState == .connected || 
            peerConnection.connectionState == .failed) {
            // Close each track
            peerConnection.senders.forEach { sender in
                sender.track?.isEnabled = false
            }

            // Close the connection
            peerConnection.close()
        }
    }

    // Empty the array
    peerConnections.removeAll()
}

The Universal Solution

Here is an improved approach for a seamless closing of PeerConnections:

// Assuming peers is an array of RTCPeerConnection objects
function disconnectPeers(peers) {
    peers.forEach(peer => {
        // Close each track
        peer.getTracks().forEach(track => {
            track.stop();
        });
        
        // Remove all event listeners
        peer.ontrack = null;
        peer.onremovetrack = null;
        peer.onicecandidate = null;
        peer.oniceconnectionstatechange = null;
        peer.onsignalingstatechange = null;
        
        // Close the connection
        peer.close();
    });
    
    // Empty the array
    peers = [];
}

This approach ensures that all resources and event listeners associated with the PeerConnection are correctly closed and removed. Each track associated with the PeerConnection is individually stopped, ensuring a complete and safe disconnection. Removing event listeners aids in preventing any unanticipated triggers after the connection has been closed.

Expert Opinion

Navigating through the complexities of WebRTC can seem like a daunting task, but it’s all part of the journey. As the saying goes, “Every expert was once a beginner.” I’ve put together this guide with the intention of making that journey a little less complicated for you.

“In the realm of WebRTC, effective resource management is not just an option, it’s a necessity. Treat it like a puzzle, where each piece must fit perfectly for the whole picture to make sense.”

Through careful understanding and application of these principles, I believe you’ll be able to overcome any hurdles you encounter in the realm of peer connections. Let’s keep learning and growing together in this fascinating field!