# Coroutine 模块

## 模块概述

Coroutine 模块是 Kotlin 协程工具封装模块，提供了统一的线程池管理、协程调度器、异常处理机制和 Flow 扩展功能。该模块简化了协程的使用，提供了高效的线程管理策略和便捷的异常处理方案。

## 主要功能

### 1. 线程池统一管理
- **Dispatcher**: 统一的线程调度器管理
- 智能的线程池策略设计
- 基于 CPU 核心数的线程分配
- 串行和并行线程池支持

### 2. 协程扩展工具
- **CoroutineExt**: 协程扩展函数
- 支持全局异常捕获的协程启动
- 便捷的作用域创建工具
- 异常处理链式调用

### 3. Flow 扩展
- **FlowExt**: Flow 扩展功能
- 节流 (throttleFirst) 支持
- 防止重复触发机制

### 4. 线程工厂
- **NamedThreadFactory**: 命名线程工厂
- 支持线程优先级设置
- 便于调试和监控

## 核心类和接口

### Dispatcher
```kotlin
object Dispatcher {
    // UI 主线程调度器
    val UI: CoroutineDispatcher
    
    // 获取串行处理 Handler
    fun getSerialHandler(): Handler
    
    // 通用线程池调度器
    val WENEXT_THREAD_POOL: CoroutineDispatcher
    
    // Handler 扩展方法
    fun Handler.submit(runnable: Runnable, delay: Long = 0L)
    fun Handler.remove(runnable: Runnable)
}
```

### 协程扩展
```kotlin
// 创建 IO 作用域
fun createIOScope(context: CoroutineContext = EmptyCoroutineContext): CoroutineScope

// 创建主线程作用域
fun createMainScope(context: CoroutineContext = EmptyCoroutineContext): CoroutineScope

// 带异常捕获的协程启动
fun CoroutineScope.launchWithCatch(
    context: CoroutineContext = coroutineContext,
    start: CoroutineStart = CoroutineStart.DEFAULT,
    block: suspend CoroutineScope.() -> Unit
): CoroutineCatcher
```

### Flow 扩展
```kotlin
// 节流操作，防止频繁触发
fun <T> Flow<T>.throttleFirst(duration: Long): Flow<T>
```

## 使用方式

### 1. 使用 Dispatcher 进行线程调度
```kotlin
// 在主线程执行
launch(Dispatcher.UI) {
    // UI 操作
    updateUI()
}

// 在后台线程执行
launch(Dispatcher.WENEXT_THREAD_POOL) {
    // 耗时操作
    val result = networkCall()
}

// 使用串行 Handler
val serialHandler = Dispatcher.getSerialHandler()
serialHandler.submit({
    // 串行执行的任务
    processData()
}, delay = 1000L)
```

### 2. 使用协程作用域扩展
```kotlin
// 创建 IO 作用域
val ioScope = createIOScope()
ioScope.launch {
    // IO 操作
    val data = loadFromDatabase()
}

// 创建主线程作用域
val mainScope = createMainScope()
mainScope.launch {
    // 主线程操作
    updateView()
}
```

### 3. 使用异常捕获协程
```kotlin
// 链式异常处理
viewModelScope.launchWithCatch {
    // 可能抛出异常的操作
    val result = riskyOperation()
    updateUI(result)
}.catch { context, throwable ->
    // 统一异常处理
    Log.e("TAG", "Coroutine error", throwable)
    showError(throwable.message)
}
```

### 4. 使用 Flow 扩展
```kotlin
// 防止频繁点击
clickFlow
    .throttleFirst(1000L) // 1秒内只响应第一次点击
    .collect { 
        handleClick() 
    }

// 搜索防抖
searchFlow
    .throttleFirst(300L) // 300ms 防抖
    .collect { query ->
        performSearch(query)
    }
```

## 线程池管理策略

### 1. 线程分配策略
- **UI 线程**: 1 个主线程处理器
- **串行线程**: (CPU 核心数 - 1) 个串行处理线程
- **IO 线程池**: 最少 2 个，最多基于 CPU 核心数动态调整

### 2. 线程池配置
```kotlin
// 主线程池配置
ThreadPoolExecutor(
    1,                                    // 核心线程数
    20.coerceAtLeast(AVAILABLE_PROCESSORS), // 最大线程数
    3, TimeUnit.SECONDS,                  // 空闲超时
    SynchronousQueue(),                   // 同步队列
    NamedThreadFactory("wenext-thread-pool") // 命名工厂
)

// 备用线程池（用于拒绝策略）
ThreadPoolExecutor(
    IO_CORE_POOL_SIZE,
    IO_CORE_POOL_SIZE,
    3, TimeUnit.SECONDS,
    LinkedBlockingQueue(),               // 无界队列
    NamedThreadFactory("wenext-backup-thread-pool")
)
```

## 依赖关系

### 编译时依赖
- `kotlinx.coroutines.core` - Kotlin 协程核心库
- `kotlinx.coroutines.android` - Android 协程支持

### 被依赖关系
- `frame:base` - 基础模块使用协程调度器
- `frame:mvvm` - MVVM 模块使用协程作用域
- 其他需要异步处理的模块

## 构建配置

```gradle
implementation "com.wenext.android:frame-coroutine:6.0.0"
```

## 注意事项

1. **线程池管理**: Dispatcher 使用单例模式，自动管理线程生命周期
2. **异常处理**: launchWithCatch 提供全局异常捕获，子协程的异常会统一处理
3. **内存泄漏**: 使用协程作用域时注意及时取消，避免内存泄漏
4. **线程切换**: Handler.submit 会根据当前线程智能选择立即执行或调度执行
5. **性能优化**: 串行 Handler 使用轮询分配，避免单一线程过载
6. **拒绝策略**: 主线程池满载时会自动降级到备用线程池
7. **Flow 节流**: throttleFirst 基于时间窗口，适用于防重复点击场景