mirror of
https://github.com/mamoe/mirai.git
synced 2025-03-24 14:30:09 +08:00
Rename listener to handler
This commit is contained in:
Him188
parent
8a2027a0e4
commit
0475cbb841
@ -133,7 +133,7 @@ interface Listener<in E : Event> : CompletableJob {
|
||||
/**
|
||||
* 在指定的 [协程作用域][CoroutineScope] 下创建一个事件监听器, 监听所有 [E] 及其子类事件.
|
||||
*
|
||||
* 每当 [事件广播][Event.broadcast] 时, [listener] 都会被执行.
|
||||
* 每当 [事件广播][Event.broadcast] 时, [handler] 都会被执行.
|
||||
*
|
||||
*
|
||||
* ### 创建监听
|
||||
@ -165,7 +165,7 @@ interface Listener<in E : Event> : CompletableJob {
|
||||
* ```
|
||||
*
|
||||
* #### 在监听器内部停止后续监听
|
||||
* 当 [listener] 返回 [ListeningStatus.STOPPED] 时停止监听.
|
||||
* 当 [handler] 返回 [ListeningStatus.STOPPED] 时停止监听.
|
||||
* 或 [Listener.complete] 后结束.
|
||||
*
|
||||
* ### 子类监听
|
||||
@ -174,23 +174,23 @@ interface Listener<in E : Event> : CompletableJob {
|
||||
* ### 异常处理
|
||||
* 事件处理时的 [CoroutineContext] 为调用本函数时的 [receiver][this] 的 [CoroutineScope.coroutineContext].
|
||||
* 因此:
|
||||
* - 当参数 [listener] 处理抛出异常时, 将会按如下顺序寻找 [CoroutineExceptionHandler] 处理异常:
|
||||
* - 当参数 [handler] 处理抛出异常时, 将会按如下顺序寻找 [CoroutineExceptionHandler] 处理异常:
|
||||
* 1. 参数 [coroutineContext]
|
||||
* 2. 接收者 [this] 的 [CoroutineScope.coroutineContext]
|
||||
* 3. [Event.broadcast] 调用者的 [coroutineContext]
|
||||
* 4. 若事件为 [BotEvent], 则从 [BotEvent.bot] 获取到 [Bot], 进而在 [Bot.coroutineContext] 中寻找
|
||||
* 5. 若以上四个步骤均无法获取 [CoroutineExceptionHandler], 则使用 [MiraiLogger.Companion] 通过日志记录. 但这种情况理论上不应发生.
|
||||
* - 事件处理时抛出异常不会停止监听器.
|
||||
* - 建议在事件处理中 (即 [listener] 里) 处理异常,
|
||||
* - 建议在事件处理中 (即 [handler] 里) 处理异常,
|
||||
* 或在参数 [coroutineContext] 中添加 [CoroutineExceptionHandler].
|
||||
*
|
||||
*
|
||||
* @param coroutineContext 给事件监听协程的额外的 [CoroutineContext].
|
||||
* @param concurrency 并发类型. 查看 [Listener.ConcurrencyKind]
|
||||
* @param priority 监听优先级，优先级越高越先执行
|
||||
* @param listener 事件处理器. 在接收到事件时会调用这个处理器. 其返回值意义参考 [ListeningStatus]. 其异常处理参考上文
|
||||
* @param handler 事件处理器. 在接收到事件时会调用这个处理器. 其返回值意义参考 [ListeningStatus]. 其异常处理参考上文
|
||||
*
|
||||
* @return 监听器实例. 此监听器已经注册到指定事件上, 在事件广播时将会调用 [listener]
|
||||
* @return 监听器实例. 此监听器已经注册到指定事件上, 在事件广播时将会调用 [handler]
|
||||
*
|
||||
* @see syncFromEvent 挂起当前协程, 监听一个事件, 并尝试从这个事件中**同步**一个值
|
||||
* @see asyncFromEvent 异步监听一个事件, 并尝试从这个事件中获取一个值.
|
||||
@ -212,27 +212,27 @@ inline fun <reified E : Event> CoroutineScope.subscribe(
|
||||
coroutineContext: CoroutineContext = EmptyCoroutineContext,
|
||||
concurrency: Listener.ConcurrencyKind = LOCKED,
|
||||
priority: Listener.EventPriority = NORMAL,
|
||||
noinline listener: suspend E.(E) -> ListeningStatus
|
||||
): Listener<E> = subscribe(E::class, coroutineContext, concurrency, priority, listener)
|
||||
noinline handler: suspend E.(E) -> ListeningStatus
|
||||
): Listener<E> = subscribe(E::class, coroutineContext, concurrency, priority, handler)
|
||||
|
||||
/**
|
||||
* 与 [subscribe] 的区别是接受 [eventClass] 参数, 而不使用 `reified` 泛型
|
||||
*
|
||||
* @see CoroutineScope.subscribe
|
||||
*
|
||||
* @return 监听器实例. 此监听器已经注册到指定事件上, 在事件广播时将会调用 [listener]
|
||||
* @return 监听器实例. 此监听器已经注册到指定事件上, 在事件广播时将会调用 [handler]
|
||||
*/
|
||||
fun <E : Event> CoroutineScope.subscribe(
|
||||
eventClass: KClass<E>,
|
||||
coroutineContext: CoroutineContext = EmptyCoroutineContext,
|
||||
concurrency: Listener.ConcurrencyKind = LOCKED,
|
||||
priority: Listener.EventPriority = NORMAL,
|
||||
listener: suspend E.(E) -> ListeningStatus
|
||||
): Listener<E> = eventClass.subscribeInternal(Handler(coroutineContext, concurrency, priority) { it.listener(it); })
|
||||
handler: suspend E.(E) -> ListeningStatus
|
||||
): Listener<E> = eventClass.subscribeInternal(Handler(coroutineContext, concurrency, priority) { it.handler(it); })
|
||||
|
||||
/**
|
||||
* 在指定的 [CoroutineScope] 下订阅所有 [E] 及其子类事件.
|
||||
* 每当 [事件广播][Event.broadcast] 时, [listener] 都会被执行.
|
||||
* 每当 [事件广播][Event.broadcast] 时, [handler] 都会被执行.
|
||||
*
|
||||
* 可在任意时候通过 [Listener.complete] 来主动停止监听.
|
||||
* [CoroutineScope] 被关闭后事件监听会被 [取消][Listener.cancel].
|
||||
@ -241,7 +241,7 @@ fun <E : Event> CoroutineScope.subscribe(
|
||||
* @param coroutineContext 给事件监听协程的额外的 [CoroutineContext]
|
||||
* @param priority 处理优先级, 优先级高的先执行
|
||||
*
|
||||
* @return 监听器实例. 此监听器已经注册到指定事件上, 在事件广播时将会调用 [listener]
|
||||
* @return 监听器实例. 此监听器已经注册到指定事件上, 在事件广播时将会调用 [handler]
|
||||
*
|
||||
* @see CoroutineScope.subscribe 获取更多说明
|
||||
*/
|
||||
@ -249,8 +249,8 @@ inline fun <reified E : Event> CoroutineScope.subscribeAlways(
|
||||
coroutineContext: CoroutineContext = EmptyCoroutineContext,
|
||||
concurrency: Listener.ConcurrencyKind = CONCURRENT,
|
||||
priority: Listener.EventPriority = NORMAL,
|
||||
noinline listener: suspend E.(E) -> Unit
|
||||
): Listener<E> = subscribeAlways(E::class, coroutineContext, concurrency, priority, listener)
|
||||
noinline handler: suspend E.(E) -> Unit
|
||||
): Listener<E> = subscribeAlways(E::class, coroutineContext, concurrency, priority, handler)
|
||||
|
||||
|
||||
/**
|
||||
@ -262,14 +262,14 @@ fun <E : Event> CoroutineScope.subscribeAlways(
|
||||
coroutineContext: CoroutineContext = EmptyCoroutineContext,
|
||||
concurrency: Listener.ConcurrencyKind = CONCURRENT,
|
||||
priority: Listener.EventPriority = NORMAL,
|
||||
listener: suspend E.(E) -> Unit
|
||||
handler: suspend E.(E) -> Unit
|
||||
): Listener<E> = eventClass.subscribeInternal(
|
||||
Handler(coroutineContext, concurrency, priority) { it.listener(it); ListeningStatus.LISTENING }
|
||||
Handler(coroutineContext, concurrency, priority) { it.handler(it); ListeningStatus.LISTENING }
|
||||
)
|
||||
|
||||
/**
|
||||
* 在指定的 [CoroutineScope] 下订阅所有 [E] 及其子类事件.
|
||||
* 仅在第一次 [事件广播][Event.broadcast] 时, [listener] 会被执行.
|
||||
* 仅在第一次 [事件广播][Event.broadcast] 时, [handler] 会被执行.
|
||||
*
|
||||
* 可在任意时候通过 [Listener.complete] 来主动停止监听.
|
||||
* [CoroutineScope] 被关闭后事件监听会被 [取消][Listener.cancel].
|
||||
@ -283,8 +283,8 @@ fun <E : Event> CoroutineScope.subscribeAlways(
|
||||
inline fun <reified E : Event> CoroutineScope.subscribeOnce(
|
||||
coroutineContext: CoroutineContext = EmptyCoroutineContext,
|
||||
priority: Listener.EventPriority = NORMAL,
|
||||
noinline listener: suspend E.(E) -> Unit
|
||||
): Listener<E> = subscribeOnce(E::class, coroutineContext, priority, listener)
|
||||
noinline handler: suspend E.(E) -> Unit
|
||||
): Listener<E> = subscribeOnce(E::class, coroutineContext, priority, handler)
|
||||
|
||||
/**
|
||||
* @see CoroutineScope.subscribeOnce
|
||||
@ -293,9 +293,9 @@ fun <E : Event> CoroutineScope.subscribeOnce(
|
||||
eventClass: KClass<E>,
|
||||
coroutineContext: CoroutineContext = EmptyCoroutineContext,
|
||||
priority: Listener.EventPriority = NORMAL,
|
||||
listener: suspend E.(E) -> Unit
|
||||
handler: suspend E.(E) -> Unit
|
||||
): Listener<E> = eventClass.subscribeInternal(
|
||||
Handler(coroutineContext, LOCKED, priority) { it.listener(it); ListeningStatus.STOPPED }
|
||||
Handler(coroutineContext, LOCKED, priority) { it.handler(it); ListeningStatus.STOPPED }
|
||||
)
|
||||
|
||||
//
|
||||
@ -462,7 +462,7 @@ inline fun <reified E : Event> CoroutineScope.subscribeDeprecated(
|
||||
coroutineContext = coroutineContext,
|
||||
concurrency = concurrency,
|
||||
priority = MONITOR,
|
||||
listener = handler
|
||||
handler = handler
|
||||
)
|
||||
|
||||
@PlannedRemoval("1.2.0")
|
||||
@ -480,7 +480,7 @@ fun <E : Event> CoroutineScope.subscribeDeprecated(
|
||||
coroutineContext = coroutineContext,
|
||||
concurrency = concurrency,
|
||||
priority = MONITOR,
|
||||
listener = handler
|
||||
handler = handler
|
||||
)
|
||||
|
||||
@PlannedRemoval("1.2.0")
|
||||
@ -496,7 +496,7 @@ inline fun <reified E : Event> CoroutineScope.subscribeAlwaysDeprecated(
|
||||
coroutineContext = coroutineContext,
|
||||
concurrency = concurrency,
|
||||
priority = MONITOR,
|
||||
listener = listener
|
||||
handler = listener
|
||||
)
|
||||
|
||||
@PlannedRemoval("1.2.0")
|
||||
@ -514,7 +514,7 @@ fun <E : Event> CoroutineScope.subscribeAlwaysDeprecated(
|
||||
coroutineContext = coroutineContext,
|
||||
concurrency = concurrency,
|
||||
priority = MONITOR,
|
||||
listener = listener
|
||||
handler = listener
|
||||
)
|
||||
|
||||
@PlannedRemoval("1.2.0")
|
||||
@ -528,7 +528,7 @@ inline fun <reified E : Event> CoroutineScope.subscribeOnceDeprecated(
|
||||
): Listener<E> = subscribeOnce(
|
||||
coroutineContext = coroutineContext,
|
||||
priority = MONITOR,
|
||||
listener = listener
|
||||
handler = listener
|
||||
)
|
||||
|
||||
@PlannedRemoval("1.2.0")
|
||||
@ -544,7 +544,7 @@ fun <E : Event> CoroutineScope.subscribeOnceDeprecated(
|
||||
eventClass = eventClass,
|
||||
coroutineContext = coroutineContext,
|
||||
priority = MONITOR,
|
||||
listener = listener
|
||||
handler = listener
|
||||
)
|
||||
|
||||
@PlannedRemoval("1.2.0")
|
||||
@ -561,7 +561,7 @@ inline fun <reified E : BotEvent> Bot.subscribeDeprecated(
|
||||
coroutineContext = coroutineContext,
|
||||
concurrency = concurrency,
|
||||
priority = MONITOR,
|
||||
listener = handler
|
||||
handler = handler
|
||||
)
|
||||
|
||||
@PlannedRemoval("1.2.0")
|
||||
@ -579,7 +579,7 @@ fun <E : BotEvent> Bot.subscribeDeprecated(
|
||||
coroutineContext = coroutineContext,
|
||||
concurrency = concurrency,
|
||||
priority = MONITOR,
|
||||
listener = handler
|
||||
handler = handler
|
||||
)
|
||||
|
||||
@PlannedRemoval("1.2.0")
|
||||
@ -596,7 +596,7 @@ inline fun <reified E : BotEvent> Bot.subscribeAlwaysDeprecated(
|
||||
coroutineContext = coroutineContext,
|
||||
concurrency = concurrency,
|
||||
priority = MONITOR,
|
||||
listener = listener
|
||||
handler = listener
|
||||
)
|
||||
|
||||
@PlannedRemoval("1.2.0")
|
||||
@ -614,7 +614,7 @@ fun <E : BotEvent> Bot.subscribeAlwaysDeprecated(
|
||||
coroutineContext = coroutineContext,
|
||||
concurrency = concurrency,
|
||||
priority = MONITOR,
|
||||
listener = listener
|
||||
handler = listener
|
||||
)
|
||||
|
||||
@PlannedRemoval("1.2.0")
|
||||
@ -628,7 +628,7 @@ inline fun <reified E : BotEvent> Bot.subscribeOnceDeprecated(
|
||||
): Listener<E> = subscribeOnce(
|
||||
coroutineContext = coroutineContext,
|
||||
priority = MONITOR,
|
||||
listener = listener
|
||||
handler = listener
|
||||
)
|
||||
|
||||
@PlannedRemoval("1.2.0")
|
||||
@ -644,6 +644,6 @@ fun <E : BotEvent> Bot.subscribeOnceDeprecated(
|
||||
eventClass = eventClass,
|
||||
coroutineContext = coroutineContext,
|
||||
priority = MONITOR,
|
||||
listener = listener
|
||||
handler = listener
|
||||
)
|
||||
// endregion
|
||||
Loading…
Reference in New Issue
Block a user