Skip to content

mux: release the player lock during source Seek - #328

Merged
hajimehoshi merged 6 commits into
ebitengine:mainfrom
kumagi:codex/mux-seek-lock-scope
Nov 2, 2026
Merged

hajimehoshi merged 6 commits into
ebitengine:mainfrom
kumagi:codex/mux-seek-lock-scope

Conversation

@kumagi

@kumagi kumagi commented Oct 20, 2026

Copy link
Copy Markdown
Contributor

What issue is this addressing?

None

What type of issue is this addressing?

bug

What this PR does | solves

A source that blocks in Seek holds the player mutex needed by mixing and player queries. Release that mutex around the external Seek while serializing source reads, seeks and state-changing player controls. Preserve buffer invalidation and playback restoration; cleanup waits at the outer Close rather than the internal error-close path.

Validation: Native macOS arm64 internal race tests passed, including shuffle/count=3 and the final blocked-Read regression. The new mixer/getter regression fails on the actual base and passes after the fix. Tests cover controls, two seeks, source Read exclusion, stale Read results, errors and panics. Native build and Windows amd64 cross-build passed. State-changing controls still wait for a blocked Seek; this fixes mixer/query progress.

@hajimehoshi

Copy link
Copy Markdown
Member

In internal/mux/mux.go:409, could we extract the locked preparation into a helper that pairs p.m.Lock() with defer p.m.Unlock()? Keeping the lock scope within one function would make it easier to follow, while leaving the source's Seek call outside the lock.

Posted by Codex on behalf of the user.

@kumagi

kumagi commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor Author

Extracted the locked preparation into prepareSeek(), which pairs p.m.Lock() with defer p.m.Unlock() within the helper. The source's Seek call remains outside the lock, and the completion logic is unchanged.

Validation: go test -race -shuffle=on -count=3 ./internal/... and go build ./... passed on macOS arm64. The existing regressions cover blocked source seeks, player controls, in-flight reads, and error/panic cleanup.

Commit: 33dfb91.

CI for this exact head: the upstream run passed all 9 jobs. The fork run concluded failure with 8 successful jobs and 1 cancelled macOS Go 1.27 job. That job never acquired a runner and executed 0 steps; GitHub annotations report hosted-runner acquisition failure and macOS arm64 capacity constraints. No workflow was rerun.

@kumagi

kumagi commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor Author

Merged upstream main (b240613) into this branch with a normal merge commit, preserving the published history. The conflict was limited to independent test additions at the end of mux_test.go; both the blocked-Seek regressions and TestSourceReadRespectsRemainingBufferSize are retained unchanged. The remaining-capacity read fix from #330 and this PR's prepareSeek() / unlocked source Seek are both preserved.

Validation: go test -race -shuffle=on -count=3 ./internal/..., native macOS arm64 go build ./..., and Windows amd64 / JS-Wasm cross-builds passed. Cross-builds are compile checks, not native playback tests.

Merge commit: 28d47fd.

CI for this exact merge commit: the upstream run and fork run each passed all 9 jobs. GitHub now reports this PR as mergeable with a clean merge state. No workflow was rerun.

@hajimehoshi

Copy link
Copy Markdown
Member

Thanks! I checked this locally: go vet, go build ./..., and go test -race -shuffle=on -count=3 ./internal/... pass at 28d47fd. Running the new tests against main, TestSeekDoesNotBlockMixerOrGetters and TestSeekSerializesControlsWhileWaitingForRead fail there. The second one is a separate pre-existing bug that this PR also fixes: on main, a Pause issued while Seek waits for an in-flight read is silently undone when Seek restores playing.

IsPlaying now reports false during a Seek on a playing player

prepareSeek moves the player to playerPausedAndStopReading, and playerPlay is restored only after s.Seek returns. Since IsPlaying no longer blocks, other goroutines can observe that intermediate state. With a source whose Seek blocks:

  • on main, IsPlaying blocks during the Seek and then returns true;
  • with this PR, it returns false while the Seek is in flight.

This breaks the README's for player.IsPlaying() { time.Sleep(...) } pattern when another goroutine seeks concurrently: the loop exits as if playback had ended. SetVolume has the same cause: called during the Seek, it sees state != playerPlay, overwrites prevVolume, and the volume ramp is skipped.

Two possible fixes:

  1. Keep playerPlay for the whole Seek: wait for p.reading directly instead of calling pauseAndStopReadingImpl, and let seeking block reads. The restore-on-finish step then goes away. I'd prefer this one.
  2. Have IsPlaying also report the saved playing value while a Seek is in flight.

Either way, TestSeekSerializesControlsWhileWaitingForRead needs another way to detect that Seek has started waiting, as it currently relies on IsPlaying turning false.

The new p.seeking read guards are redundant as written

The p.seeking || checks in canReadSourceToBuffer and prepareSourceRead never change the outcome: throughout the Seek, the state is already playerPausedAndStopReading or playerClosed, which both functions reject. With the checks removed, go test -race -shuffle=on -count=5 ./internal/mux/ still passes. With fix 1 above, they would become the guards that actually block reads.

Nits

  • The deferred closure in Seek could be a finishSeek(playing bool) helper, mirroring prepareSourceRead / finishSourceRead.
  • The seeking field has no comment of its own.
  • prepareSeek's bool return value isn't documented.
  • The new test struct literals are one-liners, while the rest of mux_test.go puts one field per line.
  • The godoc of Player.Seek in player.go could mention that other player controls wait for an in-flight Seek.

Posted by Claude (Claude Code) on behalf of @hajimehoshi.

@kumagi

kumagi commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor Author

Kept playerPlay throughout a playing player's Seek and now wait for p.reading directly. The seeking guards exclude source reads and mixing, so an empty mix during the blocked Seek cannot consume the pending volume ramp. Paused players retain their previous stopped-read behavior after seeking. The saved playing flag and restore step are gone; preparation and completion use prepareSeek() / finishSeek() with local lock scopes.

The Read-wait regression now detects the discarded buffer rather than a false IsPlaying result. Added focused checks for playing state and volume ramp, including a mix during the blocked Seek and paused-source reuse. The new state/ramp regressions fail on 28d47fd. Removing just the mix guard also makes the mix-during-Seek ramp case fail. Updated the seeking comment, struct literal formatting, and Seek godoc for serialized controls.

Validation on macOS arm64:

  • go test -race -shuffle=on -count=5 ./internal/... passed.
  • Native build and Windows amd64 / JS-Wasm cross-builds passed (cross-builds are compile-only).
  • Internal vet, JS-Wasm vet, and native vet with -unsafeptr=false passed. Full native go vet ./... reports the unchanged driver_darwin.go:309 unsafe.Pointer diagnostic; the same diagnostic reproduces on 28d47fd.

No native Windows/browser playback or device-outage testing was performed for this change.

Commit: 66717ee.

CI for this exact commit: the upstream run and fork run each passed all 9 jobs. The PR is mergeable with a clean merge state. No workflow was rerun.

@hajimehoshi

Copy link
Copy Markdown
Member

Thanks, this addresses everything. I checked 66717ee locally: go test -race -shuffle=on -count=5 ./internal/... passes, the new state/ramp tests fail on 28d47fd, and removing either the prepareSourceRead or the readBufferAndAdd seeking guard makes the suite fail.

A few optional comment nits before approving:

  • internal/mux/mux.go:439: "A paused player stays stopped after seeking, as before." compares the code to its history. Something like "A paused player stops reading the source after seeking." states the same thing without it.
  • internal/mux/mux.go:422: the second sentence of prepareSeek's doc comment ("The seeking flag excludes new reads.") describes the implementation rather than the contract and could be dropped.
  • prepareSeek repeats the for p.reading { p.readCond.Wait() } loop from pauseAndStopReadingImpl (line 388 and line 447). A small helper that waits for the in-flight read could serve both.

Posted by Claude (Claude Code) on behalf of @hajimehoshi.

@kumagi

kumagi commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor Author

Updated the paused-player comment to describe the current behavior without referring to its history, and removed the implementation sentence from prepareSeek's doc comment. Extracted waitForReadImpl() for both prepareSeek and pauseAndStopReadingImpl; both callers still hold the player mutex, with the same wait condition and state/lock ordering. Existing tests are unchanged.

Validation: go test -race -shuffle=on -count=5 ./internal/..., go vet ./internal/..., native macOS arm64 build, and Windows amd64 / JS-Wasm cross-builds passed. The cross-builds are compile checks, not native playback tests.

Commit: 0dd6da7.

CI for this exact commit: the upstream run and fork run each passed all 9 jobs. The PR is mergeable with a clean merge state. No workflow was rerun.

@hajimehoshi

Copy link
Copy Markdown
Member

Thanks for the updates. I checked whether all the new tests are needed: I broke the fix in 18 different ways (for example, removing one control's waitForSeekImpl, holding p.m across the source Seek, or not deferring finishSeek) and recorded which tests fail for each. Most tests catch something nothing else does, but a few cases are redundant:

  • TestSeekPreservesPlayingState can be dropped. The paused case is already covered by the existing TestSeekDiscardsOngoingReadResult, and whatever the playing case catches, TestSeekPreservesVolumeRamp and TestSeekSerializesControlsWhileWaitingForRead catch too. To keep a direct check, TestSeekDoesNotBlockMixerOrGetters could assert that p.IsPlaying() is true during the Seek (it currently calls it and ignores the result).
  • TestSeekFailureReleasesPlayer: only the panic case is needed. It is the one that catches a non-deferred finishSeek; the error case catches nothing extra.
  • TestSeekPreservesVolumeRamp: only mixDuringSeek=true is needed. It catches everything the false case does, plus a missing mix guard.
  • Optionally, the buffer and overlap assertions in TestSeekSerializesControlsWhileWaitingForRead repeat TestSeekDiscardsOngoingReadResult and TestSeekWaitsForOngoingRead. The test itself should stay: it is the only one that catches seeking being set after the in-flight read wait, which would let a second Seek reach the source concurrently.

The rest, TestSeekDoesNotBlockMixerOrGetters and all six cases of TestSeekSerializesPlayerControls, each catch at least one breakage nothing else does.

Posted by Claude (Claude Code) on behalf of @hajimehoshi.

@kumagi

kumagi commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor Author

Simplified the tests as requested:

  • Removed TestSeekPreservesPlayingState and added the direct IsPlaying() == true assertion during the blocked Seek in TestSeekDoesNotBlockMixerOrGetters.
  • Kept only panic cleanup in TestSeekFailureReleasesPlayer and only the mix-during-Seek scenario in TestSeekPreservesVolumeRamp, removing the redundant table wrappers.
  • Retained TestSeekSerializesControlsWhileWaitingForRead (including its assertions) and all six TestSeekSerializesPlayerControls cases unchanged. No production source changed.

Validation: go test -race -shuffle=on -count=5 ./internal/..., go vet ./internal/..., and native macOS arm64 build passed. The mux tests also cross-compiled for Windows amd64 and JS-Wasm (compile-only; no native Windows/browser playback testing). Focused checks still fail for the old paused-state behavior and for a removed mix guard.

Commit: 381bb20.

CI for this exact commit: the upstream run and fork run each passed all 9 jobs. The PR is mergeable with a clean merge state. No workflow was rerun.

@hajimehoshi hajimehoshi left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@hajimehoshi
hajimehoshi merged commit 0048738 into ebitengine:main Nov 2, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants