Repository navigation
iOS: notify the ADM observer when an enable operation rolls back after will-enable - #270
Open
hiroshihorie wants to merge 1 commit into
Open
hiroshihorie wants to merge 1 commit into
hiroshihorie wants to merge 1 commit into
Conversation
…able OnEngineWillEnable is invoked before the fallible parts of an enable operation: permission and category checks, node configuration, and engine start. When any of those failed, the rollback replayed only the constructive engine actions and never told the observer, so an observer that configured and activated the audio session for the enable was left holding an activation for an engine state that never materialized. It leaked until the next retry or stop. Push a rollback action right after a successful will-enable that fires OnEngineDidDisable with the previous engine state. Existing observers already implement did-disable as the release edge, so they get correct compensation without adopting a new callback. The result is ignored since the rollback itself cannot be aborted. Applies to both the device and manual rendering paths.
There was a problem hiding this comment.
Pull request overview
This PR fixes an iOS observer lifecycle gap where OnEngineWillEnable can succeed but a later enable step fails, causing the engine to roll back without notifying the ADM observer—potentially leaking audio session activation in observers that acquire resources in willEnable.
Changes:
- Add a rollback action immediately after successful
OnEngineWillEnablethat notifies the observer viaOnEngineDidDisablewith the previous engine state when a later enable step fails. - Apply the same rollback-notification behavior to both manual rendering and device rendering paths.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+1855
to
+1859
| if (observer_ != nullptr) { | ||
| LOGW() << "Enable rolled back after OnEngineWillEnable, notifying observer (Manual)"; | ||
| observer_->OnEngineDidDisable(engine_manual_input_, state.prev.IsOutputEnabled(), | ||
| state.prev.IsInputEnabled()); | ||
| } |
Comment on lines
+2297
to
+2301
| if (observer_ != nullptr) { | ||
| LOGW() << "Enable rolled back after OnEngineWillEnable, notifying observer"; | ||
| observer_->OnEngineDidDisable(engine_device_, state.prev.IsOutputEnabled(), | ||
| state.prev.IsInputEnabled()); | ||
| } |
cloudwebrtc
approved these changes
Jul 16, 2026
This was referenced Oct 12, 2026
Closed
hiroshihorie
added a commit
that referenced
this pull request
Nov 17, 2026
Supersedes #305, #306 and #309 (closed). #310 is a separate change. ## Problem `ModifyEngineState` applies an engine transition step by step, rolls back on any error, and commits the new state only when every step succeeds. The engine observer hooks did not fit that model in two ways. - Setup hooks could acquire without a release. When an enable failed after a successful `OnEngineWillEnable`, or a create rolled back after a successful `OnEngineDidCreate`, the observer was never told, so whatever it acquired stayed held. - Teardown hooks could roll back what cannot be undone. `OnEngineDidStop`, `OnEngineDidDisable` and `OnEngineWillRelease` run after `[engine stop]`, and the stop step registers no undo. An error from them rolled the transition back with the engine already stopped, so the committed state still said running. A later start saw no change and never ran the engine, and an interruption end never restarted it. ## Change The contract, documented in `api/audio/audio_device.h` and `RTCAudioDeviceModule.h`: 1. Setup hooks (`OnEngineDidCreate`, `OnEngineWillEnable`, `OnEngineWillStart` and the connect hooks) can fail the operation. A non-zero result rolls it back and reaches the caller. 2. A setup hook that succeeded gets its release when the operation rolls back. `OnEngineDidDisable` follows `OnEngineWillEnable`, and `OnEngineWillRelease` follows `OnEngineDidCreate`. 3. Teardown hooks (`OnEngineDidStop`, `OnEngineDidDisable` and `OnEngineWillRelease`) cannot fail the operation. A non-zero result is logged and the operation completes. One commit per rule: - `68ac34a269` and `f92becad78`: will-enable compensation, port of #270 with its review follow-ups (previously #305). - `9dc7a011fa`: did-create compensation (previously #306). - `f300557860`: teardown errors are only logged, in the device and manual rendering paths. Covers the interruption begin case of #309. ## Behavior change A teardown hook error no longer reaches the caller. The Swift SDK's `observerFail` audio test expects `stopLocalRecording()` to throw on a failing `engineDidStop` and needs a matching update. React Native apps whose JS did-stop handler throws get a log line instead of an error. ## Notes for review - Not covered yet: an engine start failure after a successful `OnEngineWillStart` still gets no `OnEngineDidStop`. The fault matrix cannot inject a start failure, and current observers hold nothing from will-start. - #310 (double start at interruption end) and the interruption events are separate changes and merge cleanly with this. ## Testing - `clang -fsyntax-only` of `audio_engine_device.mm` and `RTCAudioDeviceModule.mm` for macOS and iOS: no errors. The one iOS warning is a pre-existing deprecation in `api/audio_options.h`. - Fault injection matrix on device (iPhone 17 Pro Max, iOS 27), apple-audio-lab `RollbackFaultMatrixTests`. A probe at the head of the Swift SDK observer chain fails one of eight hooks once during one of eight engine operations (capture start and stop, engine availability off and on, interruption begin and end, mute and unmute in restart mute mode). Each case then checks that bringing capture up runs the engine, that taking it down stops it, and that every successful setup hook got its release back at idle. - Swift SDK 2.15.3 with the released LiveKitWebRTC 144.7559.11: 22 of 26 cases violate. 12 are setup failures that leak an acquire, 10 are teardown failures that leave the engine stopped while the state says running. - #306, which includes #305: 10 violations, all on the teardown path. - Both numbers above predate the probe change below, which only affects the three `willRelease` rows. - A prototype of the teardown rule on top of #306 cleared the teardown violations, except three that came from the probe itself (it failed `willRelease` without forwarding it, which the probe now does). - This head: 0 of 26 cases violate. - Other lab suites on this head, same device: - Rolled back enable tests pass, including the did-disable order and the release of the engine created for the failed enable. - The #309 repro passes. A did-stop that fails at an interruption begin no longer drops the interruption, and the end restarts the engine. - A did-stop that fails on an app requested stop no longer throws, and the next start runs the engine. - Interruption path and processing seed tests pass. - The double start repros still hit `Check failed: configuration_observer_ == nullptr` on this head, as expected without #310.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
OnEngineWillEnableruns before permission and category checks, node configuration, and engine startup. If a later step fails, rollback never notifies the observer. Observers that configure or activate the audio session inwillEnablecan therefore retain resources for an engine state that was never applied.Change
After a successful
OnEngineWillEnable, register a rollback action that callsOnEngineDidDisablewith the previous state. This covers both device and manual rendering paths. The result is ignored because rollback cannot be cancelled.OnEngineDidDisablemay now represent an attempted enable returning to the previous state, not only a completed disable.Testing
Built
framework_objcfor an arm64 iOS device. Reproduced by enabling input with an incompatible playback-only category and verified that rollback now notifies the observer.