1 /*
2 * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
3 */
4
5 package kotlinx.coroutines.jdk9
6
7 import java.util.concurrent.*
8 import org.reactivestreams.FlowAdapters
9 import kotlinx.coroutines.reactive.*
10
11 /**
12 * Awaits for the first value from the given publisher without blocking a thread and
13 * returns the resulting value or throws the corresponding exception if this publisher had produced error.
14 *
15 * This suspending function is cancellable.
16 * If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function
17 * immediately resumes with [CancellationException].
18 *
19 * @throws NoSuchElementException if publisher does not emit any value
20 */
awaitFirstnull21 public suspend fun <T> Flow.Publisher<T>.awaitFirst(): T = FlowAdapters.toPublisher(this).awaitFirst()
22
23 /**
24 * Awaits for the first value from the given observable or the [default] value if none is emitted without blocking a
25 * thread and returns the resulting value or throws the corresponding exception if this observable had produced error.
26 *
27 * This suspending function is cancellable.
28 * If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function
29 * immediately resumes with [CancellationException].
30 */
31 public suspend fun <T> Flow.Publisher<T>.awaitFirstOrDefault(default: T): T =
32 FlowAdapters.toPublisher(this).awaitFirstOrDefault(default)
33
34 /**
35 * Awaits for the first value from the given observable or `null` value if none is emitted without blocking a
36 * thread and returns the resulting value or throws the corresponding exception if this observable had produced error.
37 *
38 * This suspending function is cancellable.
39 * If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function
40 * immediately resumes with [CancellationException].
41 */
42 public suspend fun <T> Flow.Publisher<T>.awaitFirstOrNull(): T? =
43 FlowAdapters.toPublisher(this).awaitFirstOrNull()
44
45 /**
46 * Awaits for the first value from the given observable or call [defaultValue] to get a value if none is emitted without blocking a
47 * thread and returns the resulting value or throws the corresponding exception if this observable had produced error.
48 *
49 * This suspending function is cancellable.
50 * If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function
51 * immediately resumes with [CancellationException].
52 */
53 public suspend fun <T> Flow.Publisher<T>.awaitFirstOrElse(defaultValue: () -> T): T =
54 FlowAdapters.toPublisher(this).awaitFirstOrElse(defaultValue)
55
56 /**
57 * Awaits for the last value from the given publisher without blocking a thread and
58 * returns the resulting value or throws the corresponding exception if this publisher had produced error.
59 *
60 * This suspending function is cancellable.
61 * If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function
62 * immediately resumes with [CancellationException].
63 *
64 * @throws NoSuchElementException if publisher does not emit any value
65 */
66 public suspend fun <T> Flow.Publisher<T>.awaitLast(): T =
67 FlowAdapters.toPublisher(this).awaitLast()
68
69 /**
70 * Awaits for the single value from the given publisher without blocking a thread and
71 * returns the resulting value or throws the corresponding exception if this publisher had produced error.
72 *
73 * This suspending function is cancellable.
74 * If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function
75 * immediately resumes with [CancellationException].
76 *
77 * @throws NoSuchElementException if publisher does not emit any value
78 * @throws IllegalArgumentException if publisher emits more than one value
79 */
80 public suspend fun <T> Flow.Publisher<T>.awaitSingle(): T =
81 FlowAdapters.toPublisher(this).awaitSingle()
82