Ability to add a custom message into exception thrown by withTimeout

[dant3]

Sorry if this is a duplicate or superseeded by something else.

Use case
Consider the code like:

withTimeout(timeout1) {
   // some function awaiting for result
}

withTimeout(imeout2) {
   // some other awaiting logic
}

There is no way to tell which one of those thrown TimeoutCancellationException especially if the timeout value is the same. Currently the only cumbersome alternatives exist are:

try {
   withTimeout ...
} catch (ex: TimeoutCancellationException) {
    throw MyException("this is timeout1");
}

// or...

withTimeoutOrNull(timeout1) {
} ?: throw MyException("timeout1")

The Shape of the API

This could be just as simple as an optional parameter. Consider junit assertions as example: by default you can assert without any specification and when assertion fails there is not much of the specifics. However you can specify an optional parameter message and this message will be added to the AssertionError, making it easier to understand what went south. In case of kotlin coroutines stacktraces can be hard to figure out, so this becomes even more important.

Proposal

withTimeout(duration, name = "waiting for X") {
     // waiting for X
}
// produces TimeoutCancellaionException("Timed out waiting for 15000 ms: waiting for X")

Alternatively, could use CoroutineName

withTimeout(duration, context = CoroutineName("waiting for X")) {
   // waiting for X
}

// produces TimeoutCancellaionException("Coroutine(\"waiting for X\") timed out waiting for 15000 ms")

[dkhalanskyjb]

Hi! This is a new issue, not a duplicate.

1. The proposed options don't look like idiomatic Kotlin to me. "doSomething" and "doSomethingOrNull" pairs are common in Kotlin in general, and I don't think a single one of them allows parameterizing doSomething with the additional information for the exception message. Yet your arguments are just as applicable to single/singleOrNull, first/firstOrNull, etc., are they not? If there are several first calls in a row, it may be helpful to know which one failed, for example. Do you see any differences between withTimeout and single in this regard, or do you consider userRepo.withId(id).single(name = "the user with the given ID") a valuable addition as well?
2. In this situation, I personally would use exactly the withTimeoutOrNull ?: throw MyException pattern. It reads naturally to me, and it's also flexible: if I needed to edit the code later to do something other than throw an exception later (e.g., retry, or gracefully output a message, etc.), it would be a straightforward edit.
3. That said, we can enhance the withTimeout exception message with the coroutine name, sounds like a non-controversial useful addition! I don't think this will help you much without us also exposing context = in withTimeout, though, as you'd have to write this cumbersome form anyway:

withContext(CoroutineName("waiting for x")) {
    withTimeout(duration) {
        // ...
    }
}