sync: clarify bounded channel panic behavior

[tabokie]

Motivation

A panic condition is not documented.

Solution

Document it.

[ADD-SP]

Could you mention the panic behavior about Semaphore::MAX_PERMITS might be changed in the future and downstream should not rely on it.

Although it is unlikely to change the implementation of mpsc in the future, I still don't want to make the downstream relies on it, it should not be the part of semver.

[tabokie]

If I understand correct, referencing a public constant in library (instead of advertising the exact value) implies the constant may change and does prevent the compatibility risk you mentioned? (E.g. that's the way semaphore is documented: https://docs.rs/tokio/latest/tokio/sync/struct.Semaphore.html#method.new)

If however you meant the dependency between mpsc and Semaphore might change in the future and that poses a risk, then we should re-export the constant (mpsc::MAX_CAPACITY = Semaphore::MAX_PERMITS)?

might be changed in the future

okay with this addition,

downstream should not rely on it

but this is probably not how I perceive it.

[ADD-SP]

If however you meant the dependency between mpsc and Semaphore might change in the future and that poses a risk, then we should re-export the constant (mpsc::MAX_CAPACITY = Semaphore::MAX_PERMITS)?

We are not inclined to introduce a new thing into the tokio crate unless absolutely necessary. Since it is not a common case to set the capacity of mpsc to 2_305_843_009_213_693_951usize, I prefer just write document to mention the current behavior and claim it is not the part of the semver.