withTimeoutOrNull

Shorthand form for calling withTimeoutOrNull with a Duration timeout of timeMillis milliseconds. Please see the overload accepting a Duration for details.

Note: the behavior of this function can be different from withTimeoutOrNull if timeMillis is greater than Long.MAX_VALUE / 2 milliseconds.

Calls the given suspending block with the specified timeout, suspends until it completes, and returns the result.

If the block execution times out, it is cancelled with a TimeoutCancellationException. If the timeout is non-positive, this happens immediately, and the block is not executed.

Cancellation on timeout runs concurrently the code running in the block and may happen at any time, even after the block finishes executing but before the caller gets resumed with the result.

Implementation note: how the time is tracked exactly is an implementation detail of the CoroutineDispatcher in the currentCoroutineContext.

Structured Concurrency

withTimeoutOrNull behaves like coroutineScope, as it, too, creates a new lexically scoped child coroutine. Refer to the documentation of coroutineScope for details.

Pitfalls

Cancellation is cooperative

withTimeoutOrNull will not automatically stop all code inside it from being executed once the timeout gets triggered. It only cancels the running block, but it's up to the block to notice that it was cancelled, for example, by suspending or checking isActive.

This JVM code will run to completion, taking 10 seconds to do so:

withTimeoutOrNull(1.seconds) {
    Thread.sleep(10_000)
}

On the JVM, use the runInterruptible function to propagate cancellations to blocking JVM code as thread interruptions.

See the Make coroutines react to cancellation section of the coroutines guide for details.

Returning closeable resources

Values returned from withTimeoutOrNull will typically be lost if the caller is cancelled.

See the corresponding section in the coroutineScope documentation for details.

See also