Skip to content

Update race docs for new 3.5 semantics #4526

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: series/3.x
Choose a base branch
from
+4 −6
Open

Update race docs for new 3.5 semantics #4526

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 4 additions & 6 deletions kernel/shared/src/main/scala/cats/effect/kernel/GenSpawn.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -377,18 +377,16 @@ trait GenSpawn[F[_], E] extends MonadCancel[F, E] with Unique[F] {

/**
* Races the evaluation of two fibers that returns the result of the winner, except in the
* case of cancelation.
* case of cancelation which cancels the whole race.
Copy link
Contributor

@durban durban Nov 23, 2025

Choose a reason for hiding this comment

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

I think this is ambiguous: "in the case of cancelation" <- what does this mean? If the fiber executing race is canceled? If one or the other side cancels?

*
* The semantics of [[race]] are described by the following rules:
*
* 1. If the winner completes with [[Outcome.Succeeded]], the race returns the successful
* value. The loser is canceled before returning. 2. If the winner completes with
* [[Outcome.Errored]], the race raises the error. The loser is canceled before
* returning. 3. If the winner completes with [[Outcome.Canceled]], the race returns the
* result of the loser, consistent with the first two rules. 4. If both the winner and
* loser complete with [[Outcome.Canceled]], the race is canceled. 8. If the race is
* masked and is canceled because both participants canceled, the fiber will block
* indefinitely.
* returning. 3. If the winner completes with [[Outcome.Canceled]], the loser is canceled
* immediately but its outcome is returned if already completed. 4. If the race is masked
Copy link
Contributor

@durban durban Nov 23, 2025

Choose a reason for hiding this comment

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

There is a subtle point here: if the loser is cancelled, its Succeeded result can be returned even if it's yet to happen.

In other words: "the loser is canceled immediately but its outcome is returned if already completed" <- I think this sentence suggests, that if the loser is not yet completed when it's cancelled, then its outcome will not be returned. This is not true.

* and is canceled because both participants canceled, the fiber will block indefinitely.
*
* @param fa
* the effect for the first racing fiber
Expand Down
Loading