Android协程作用域与序列发生器限制介绍梳理

@SinceKotlin("1.3")
public fun <T> sequence(@BuilderInference block: suspend SequenceScope<T>.() -> Unit): Sequence<T> = Sequence { iterator(block) }

// 注意
@RestrictsSuspension
@SinceKotlin("1.3")
public abstract class SequenceScope<in T> internal constructor() {
    // 向迭代器中提供一个数值
    public abstract suspend fun yield(value: T)
    // 向迭代器中提供一组数值
    public abstract suspend fun yieldAll(iterator: Iterator<T>)
    // 向迭代器中提供Collection类型的一组数值
    public suspend fun yieldAll(elements: Iterable<T>) {
        if (elements is Collection && elements.isEmpty()) return
        return yieldAll(elements.iterator())
    }
    // 向迭代器中提供Sequence类型的一组数值
    public suspend fun yieldAll(sequence: Sequence<T>) = yieldAll(sequence.iterator())
}

@SinceKotlin("1.3")
@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.BINARY)
public annotation class RestrictsSuspension

public interface Sequence<out T> {
    public operator fun iterator(): Iterator<T>
}

@kotlin.internal.InlineOnly
public inline fun <T> Sequence(crossinline iterator: () -> Iterator<T>): Sequence<T> = object : Sequence<T> {
    override fun iterator(): Iterator<T> = iterator()
}

@SinceKotlin("1.3")
public fun <T> iterator(@BuilderInference block: suspend SequenceScope<T>.() -> Unit): Iterator<T> {
    val iterator = SequenceBuilderIterator<T>()
    iterator.nextStep = block.createCoroutineUnintercepted(receiver = iterator, completion = iterator)
    return iterator
}

private typealias State = Int
// 没有要发射的数据
private const val State_NotReady: State = 0
private const val State_ManyNotReady: State = 1
// 有要发射的数据
private const val State_ManyReady: State = 2
private const val State_Ready: State = 3
// 数据全部发射完毕
private const val State_Done: State = 4
// 发射过程中出错
private const val State_Failed: State = 5

private class SequenceBuilderIterator<T> : SequenceScope<T>(), Iterator<T>, Continuation<Unit> {
    // 迭代器的状态
    private var state = State_NotReady
    // 迭代器下一个要发送的值
    private var nextValue: T? = null
    // 用于保存yieldAll方法传入的迭代器
    private var nextIterator: Iterator<T>? = null
    // 用于获取下一个数据的续体
    var nextStep: Continuation<Unit>? = null
    ...
    // 空的上下文
    override val context: CoroutineContext
        get() = EmptyCoroutineContext
}

// 发射一个数据
override suspend fun yield(value: T) {
    // 保存数据到全局变量中
    nextValue = value
    // 修改状态
    state = State_Ready
    // 挂起协程，获取续体
    return suspendCoroutineUninterceptedOrReturn { c ->
        // 保存续体到全局变量中
        nextStep = c
        // 挂起
        COROUTINE_SUSPENDED
    }
}
// 发射多个数据
override suspend fun yieldAll(iterator: Iterator<T>) {
    // 如果迭代器没有数据，则直接返回
    if (!iterator.hasNext()) return
    // 如果有数据，则保存到全局变量
    nextIterator = iterator
    // 修改状态
    state = State_ManyReady
    // 挂起协程，获取续体
    return suspendCoroutineUninterceptedOrReturn { c ->
        // 保存续体到全局变量中
        nextStep = c
        // 挂起
        COROUTINE_SUSPENDED
    }
}

override fun hasNext(): Boolean {
    // 循环
    while (true) {
        // 判断状态
        when (state) {
            // 刚通过yield方法发射数据
            State_NotReady -> {}
            // 刚通过yieldAll方法发射数据
            State_ManyNotReady ->
                // 如果迭代器中还有数据
                if (nextIterator!!.hasNext()) {
                    // 修改状态，返回true
                    state = State_ManyReady
                    return true
                } else {
                    // 没有数据，则置空，丢弃迭代器
                    nextIterator = null
                }
            // 如果序列发生器已经发射完数据，返回false
            State_Done -> return false
            // 如果有数据，则直接返回true
            State_Ready, State_ManyReady -> return true
            // 其他状态，则抛出异常
            else -> throw exceptionalState()
        }
        // 走到这里，说明需要去获取下一个数据
        // 修改状态
        state = State_Failed
        // 获取全局保存的续体
        val step = nextStep!!
        // 置空
        nextStep = null
        // 恢复序列发生器的执行，直到遇到yield方法或yieldAll方法挂起
        step.resume(Unit)
    }
}
// 异常状态的处理
private fun exceptionalState(): Throwable = when (state) {
    State_Done -> NoSuchElementException()
    State_Failed -> IllegalStateException("Iterator has failed.")
    else -> IllegalStateException("Unexpected state of the iterator: $state")
}

override fun next(): T {
    // 判断状态
    when (state) {
        // 如果当前处于已经发射完数据的状态，则判断是否有数据
        State_NotReady, State_ManyNotReady -> return nextNotReady()
        // 如果通过yieldAll方法获取到了数据
        State_ManyReady -> {
            // 修改状态
            state = State_ManyNotReady
            // 通过迭代器获取数据
            return nextIterator!!.next()
        }
        // 如果通过yield方法获取到了数据
        State_Ready -> {
            // 修改状态
            state = State_NotReady
            // 获取保存的数据并进行类型转换
            @Suppress("UNCHECKED_CAST")
            val result = nextValue as T
            // 全局变量置空
            nextValue = null
            // 返回数据
            return result
        }
        // 其他情况，则抛出异常
        else -> throw exceptionalState()
    }
}
// 如果没有数据，则抛出异常，有数据，则返回数据
private fun nextNotReady(): T {
    if (!hasNext()) throw NoSuchElementException() else return next()
}