simbot-api/love.forte.simbot.event/EventProcessor/push

push

abstract fun push(event: Event): Flow<EventResult>

推送一个事件，得到内部所有事件依次将其处理后得到最终的结果流。

结果流是冷流。

只有当对结果进行收集时事件才会真正的被处理。可以通过响应的流对事件处理量进行控制。

事件内部实际的调度器由构造 EventProcessor 时的配置属性和具体实现为准。

返回结果的 Flow 中每一次事件调度都可能伴随着上下文的切换（通过 EventDispatcherConfiguration.coroutineContext 的配置），但并非通过 Flow.flowOn 进行切换，不会导致实际执行的事件调度逻辑比收集到的逻辑更多。

eventDispatcher.push(event)
  .take(3)
  .collect { ... } // flow 中只会执行优先级最高的三个 listener 并收集到它们的结果

eventDispatcher.push(event)
     .flowOn(Dispatchers.IO) // 切换事件调度流程中的上下文
     .take(3)
     .collect { ... } // flow 中切换了调度上下文，这可能会使所有的listener都被实际上的执行，但是只收集到3个最新的结果。

异常

如果事件处理器 EventListener 或者事件拦截器 EventInterceptor 的执行过程中产生了异常，则对应位置的 EventResult 将会是包装了此异常的 StandardEventResult.Error，且不会中断后续其他处理器或拦截器的执行。

eventDispatcher.push(event)
    .onEach { result ->
        if (result is StandardEventResult.Error) {
            // 这个 result 代表了一个异常
        }
    }
    .collect { ... }

如果事件调度拦截器在执行的过程中产生了异常，则会直接向 Flow 中抛出异常。此异常可通过 Flow.catch 得到。

eventDispatcher.push(event)
    .catch {
        // 调度拦截器 EventDispatchInterceptor 产生了异常
    }
    .collect { ... }

也可以通过一些预设的扩展API来处理部分特殊的响应结果。(对于特殊的响应结果可参考 StandardEventResult) 例如 Flow.filterNotInvalid 会过滤掉所有表示无效的返回值 StandardEventResult.Invalid:

eventDispatcher.push(event)
   .filterNotInvalid() // 过滤掉所有 Invalid 类型结果
   .collect { ... }

Java API

在 EventProcessors 的静态API中提供了一些非挂起的可供 Java 友好调用的API，例如:

List<EventResult> resultList = EventProcessors.pushAndCollectToListAsync(processor, event, scope);
// ...

Flux<EventResult> resultList = EventProcessors.pushAndAsFlux(processor, event, scope);
// ...

其中提供了一些异步或响应式相关的转化、处理API。对于它们各自的说明、限制、要求则在 push 的基础上参考它们的文档说明。

Return

EventResult 结果。如果具有特殊含义，那么可能是 StandardEventResult 中的某类型。