后端并发编程异步编程【免费下载链接】akka-coreA platform to build and run apps that are elastic, agile, and resilient. SDK, libraries, and hosted environments.项目地址https://gitcode.com/gh_mirrors/ak/akka-core点击查看免费下载导读Source.future是 Akka Streams 中用于把 Scala 标准库Future[T]无缝接入流式处理管线的核心算子当Future成功完成且下游产生需求demand时它会将唯一的元素发射给下游然后完成数据流。本文以官方文档 Source.future 为主体结合 Akka 源码中的实际实现Source.scala 与 GraphStages.scala和单元测试SourceSpec.scala讲清其签名、语义、底层原理、使用示例与边界情况。读完本文你将掌握如何把异步计算结果如 RPC 响应、数据库查询结果以背压安全的方式注入 Akka Streams 管线并能理解其与Source.completionStage、Source.futureSource等相邻算子的异同。签名SignatureSource.future定义在akka.stream.scaladsl.Source伴生对象中其 Scala 签名为def futureT: Source[T, NotUsed]输入一个scala.concurrent.Future[T]即 Scala 标准库中表示将来某个时刻会完成的一个异步值的类型。输出一个Source[T, NotUsed]即至多发射一个T类型元素的流式数据源其物化值materialized value为NotUsed表示不产生有意义的物化结果。Java 使用者无需直接使用该算子——Akka Streams 为 Java 标准库的CompletionStage提供了对应的Source.completionStage二者在语义上完全等价completionStage内部就是通过completionStage.asScala转成Future后调用future实现的见 Source.scala。描述DescriptionSource.future的核心语义只有一句话当Future完成且下游存在需求时发射该Future的唯一值若Future以失败结束则整个数据流以该异常失败fail。这一语义意味着单元素无论Future何时完成数据流中最多只有一个元素。需求驱动元素只会在下游发出 pull 请求有需求时才被发射因此天然遵守 Reactive Streams 的背压backpressure协议。失败传播Future的失败会直接转化为流的失败下游所有算子与 Sink 都会收到该失败信号这与 Akka Streams 中错误总是随流传播的总体设计一致。需要特别指出与Source.completionStage不同其文档明确说明若CompletionStage以null完成则流不发射任何值直接完成Source.future对null的处理也遵循同一行为——从 GraphStages.scala 的实现可以看到Success(null)时调用completeStage()即不发射元素、直接完成流。Reactive Streams 语义官方文档用如下两条规则概括该算子的流语义项目语义emits发射当Future完成时且下游有需求completes完成在Future完成之后示例Example官方文档在 SourceOperators.scala 中给出了完整可运行的 Scala 示例以下即为#sourceFromFuture代码片段import akka.stream.scaladsl._ import akka.{ Done, NotUsed } import scala.concurrent.Future val source: Source[Int, NotUsed] Source.future(Future.successful(10)) val sink: Sink[Int, Future[Done]] Sink.foreach((i: Int) println(i)) val done: Future[Done] source.runWith(sink) // 输出: 10解读这段代码的执行流程Future.successful(10)创建一个已经成功完成、值为10的FutureSource.future(...)将其包装成单元素SourceSink.foreach对每个到达的元素执行println其物化值为Future[Done]可用于等待流完成runWith将流连接并物化控制台输出10最终done会在流完成后完成。需要implicit的ActorSystem示例代码中为implicit val system: ActorSystem ???来物化流。若希望在真实应用中等待结果可以Await.result(done, timeout)或继续在done上链式组合后续逻辑。对应的 Java 版本使用CompletionStage可以在 FromCompletionStage.java 中看到import akka.Done; import akka.NotUsed; import akka.stream.javadsl.*; import java.util.concurrent.CompletableFuture; import java.util.concurrent.CompletionStage; CompletionStageInteger stage CompletableFuture.completedFuture(10); SourceInteger, NotUsed source Source.completionStage(stage); SinkInteger, CompletionStageDone sink Sink.foreach(i - System.out.println(i.toString())); source.runWith(sink, system); // 输出: 10底层实现与原理源码级剖析Source.future的快路径与常规路径分界清晰理解它有助于你判断不同场景下的性能特征。工厂方法的快速路径优化在 Source.scala 中future工厂方法会先检查futureElement.valueFuture的瞬时状态快照def futureT: Source[T, NotUsed] futureElement.value match { case Some(Success(null)) empty // 已完成且值为 null → 空流 case Some(Success(value)) single(value) // 已完成且值非 null → 单元素流 case Some(Failure(cause)) failed(cause) // 已失败 → 直接失败流 case None fromGraph(new FutureSourceT) // 未完成 → 通用实现 }也就是说如果Future在调用Source.future时已经完成工厂方法会直接退化为更轻量的Source.empty、Source.single或Source.failed绕开通用的FutureSource图阶段GraphStage从而避免不必要的异步回调开销。这一点在 SourceSpec.scala 的测试中得到验证已成功的Future会被优化为singleSource已失败的Future会被优化为failedSource未完成的Future用Promise表示才会使用futureSource。三个测试均通过source.getAttributes.nameLifted断言了优化后的属性名并验证了运行结果成功值done、失败异常TE(boom)。未完成 Future 的通用实现FutureSource GraphStage当Future尚未完成时Source.future会构造一个内部InternalApi图阶段FutureSource完整实现位于 GraphStages.scala。其关键逻辑如下final class FutureSourceT extends GraphStage[SourceShape[T]] { val shape SourceShape(OutletT) val out shape.out override def createLogic(attr: Attributes) new GraphStageLogic(shape) with OutHandler { def onPull(): Unit { future.value match { case Some(completed) // optimization if the future is already completed onFutureCompleted(completed) case None val cb getAsyncCallback[Try[T]](onFutureCompleted).invoke _ future.onComplete(cb)(ExecutionContext.parasitic) } def onFutureCompleted(result: Try[T]): Unit { result match { case scala.util.Success(null) completeStage() case scala.util.Success(v) emit(out, v, () completeStage()) case scala.util.Failure(t) failStage(t) } } setHandler(out, eagerTerminateOutput) // After first pull we wont produce anything more } setHandler(out, this) } }其运作机制体现了 Akka Streams 图阶段GraphStage设计的几个要点拉取触发onPull()在首次收到下游需求时被调用。此时先做一次future.value快照检查——若Future已在此期间完成则直接走onFutureCompleted同步完成无需注册回调否则注册回调。线程安全回调Future.onComplete的回调发生在线程池线程上而 GraphStage 逻辑必须运行在流引擎的专用线程上因此这里用getAsyncCallback将回调结果安全地投递回流的执行上下文规避了任何竞态与线程安全问题。惰性注册回调只在第一次onPull时才注册因此如果下游从未请求元素例如下游提前取消则不会为Future注册回调体现了按需demand-driven的资源使用策略。一次性发射发射元素后通过emit(out, v, () completeStage())在发射完成时立即结束流在第一次 pull 之后handler 被替换为eagerTerminateOutput保证不会再有第二次发射。失败传播Failure(t)分支调用failStage(t)将异常作为流失败传播给下游。这与文档若Future失败则流以该异常失败的描述一一对应。与其他相关算子的对比算子输入输出元素物化值说明Source.futureFuture[T]至多 1 个TNotUsed本文主角Scala 原生Source.completionStageCompletionStage[T]至多 1 个TNotUsedJava 互操作版本内部委托给future见 Source.scalaSource.futureSourceFuture[Source[T, M]]多个T来自内部 SourceFuture[M]等Future完成后展开为内层Source的全部元素见 Source.scalaSource.lazyFutureSource.lazilyAsync的替代() Future[T]工厂至多 1 个TFuture[NotUsed]工厂延迟到下游产生需求时才调用见 Source.scala 的废弃注释选用建议已经持有或即将持有一个Future计算结果且只需要把它作为流中唯一元素继续加工时用Source.future在 Java 代码中使用Source.completionStage当Future本身展开后是一个Source例如异步获取一个流式查询结果时用Source.futureSource当希望延迟创建Future即下游没有需求就完全不发起异步计算时用Source.lazyFuture或Source.lazySource。边界情况与注意事项null值Future成功完成但值为null时流不发射任何元素直接完成等价于Source.empty。失败传播Future失败会导致流失败异常沿流向下传播请确保流中后续的算子/接收方对失败有兜底处理如Sink.onComplete、recover等。取消行为若下游在Future完成前取消回调不会被注册Future的完成结果将无人消费——若该Future承载着昂贵资源如数据库连接需在业务侧自行处理取消语义。物化值NotUsed意味着该算子本身不提供等待完成的句柄若要等整个流结束请依赖runWith(sink)返回的 Sink 物化值如示例中的Future[Done]。已完成的FutureSource.future(Future.successful(v))会被直接优化为Source.single(v)性能上无需担忧同理Future.failed(e)会被优化为Source.failed(e)。总结Source.future是 Akka Streams 中异步计算 → 流转换的基础构件它以背压安全的方式把 ScalaFuture的结果变成流中的唯一元素将失败透明地转化为流失败并对已完成的Future提供了零开销的快路径优化。结合 官方文档、工厂实现、FutureSource GraphStage 实现 与 单元测试你可以放心地将它用于 RPC 响应、缓存读取、数据库查询等典型异步场景并与其他Source算子自由组合构建完整的流式处理管线。若使用 Java请使用其等价物Source.completionStage见 completionStage.md。赞分享后端并发编程异步编程【免费下载链接】akka-coreA platform to build and run apps that are elastic, agile, and resilient. SDK, libraries, and hosted environments.项目地址https://gitcode.com/gh_mirrors/ak/akka-core点击查看免费下载相关推荐Akka Streams 的 Source.futureSource 算子将异步 Future[Source] 转换为流式数据源Akka Streams 的 Source.futureSource 算子将异步 Future Source 转换为流式数据源 本篇文章深入剖析 Akka S后端并发编程异步编程Akka Streams Source.lazyFuture 操作符完全指南延迟创建单元素 Future 的惰性数据源Akka Streams Source.lazyFuture 操作符完全指南延迟创建单元素 Future 的惰性数据源 本文围绕 Akka 项目中 Sourc后端并发编程异步编程Akka Streams Sink.seq 算子详解把流中的元素收集为集合Akka Streams Sink.seq 算子详解把流中的元素收集为集合 Sink.seq 是 Akka Streams 中一个常用且易用的下游算子Sin后端并发编程异步编程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Akka Streams 的 Source.future 算子：将 Future 转换为单元素数据源
后端并发编程异步编程【免费下载链接】akka-coreA platform to build and run apps that are elastic, agile, and resilient. SDK, libraries, and hosted environments.项目地址https://gitcode.com/gh_mirrors/ak/akka-core点击查看免费下载导读Source.future是 Akka Streams 中用于把 Scala 标准库Future[T]无缝接入流式处理管线的核心算子当Future成功完成且下游产生需求demand时它会将唯一的元素发射给下游然后完成数据流。本文以官方文档 Source.future 为主体结合 Akka 源码中的实际实现Source.scala 与 GraphStages.scala和单元测试SourceSpec.scala讲清其签名、语义、底层原理、使用示例与边界情况。读完本文你将掌握如何把异步计算结果如 RPC 响应、数据库查询结果以背压安全的方式注入 Akka Streams 管线并能理解其与Source.completionStage、Source.futureSource等相邻算子的异同。签名SignatureSource.future定义在akka.stream.scaladsl.Source伴生对象中其 Scala 签名为def futureT: Source[T, NotUsed]输入一个scala.concurrent.Future[T]即 Scala 标准库中表示将来某个时刻会完成的一个异步值的类型。输出一个Source[T, NotUsed]即至多发射一个T类型元素的流式数据源其物化值materialized value为NotUsed表示不产生有意义的物化结果。Java 使用者无需直接使用该算子——Akka Streams 为 Java 标准库的CompletionStage提供了对应的Source.completionStage二者在语义上完全等价completionStage内部就是通过completionStage.asScala转成Future后调用future实现的见 Source.scala。描述DescriptionSource.future的核心语义只有一句话当Future完成且下游存在需求时发射该Future的唯一值若Future以失败结束则整个数据流以该异常失败fail。这一语义意味着单元素无论Future何时完成数据流中最多只有一个元素。需求驱动元素只会在下游发出 pull 请求有需求时才被发射因此天然遵守 Reactive Streams 的背压backpressure协议。失败传播Future的失败会直接转化为流的失败下游所有算子与 Sink 都会收到该失败信号这与 Akka Streams 中错误总是随流传播的总体设计一致。需要特别指出与Source.completionStage不同其文档明确说明若CompletionStage以null完成则流不发射任何值直接完成Source.future对null的处理也遵循同一行为——从 GraphStages.scala 的实现可以看到Success(null)时调用completeStage()即不发射元素、直接完成流。Reactive Streams 语义官方文档用如下两条规则概括该算子的流语义项目语义emits发射当Future完成时且下游有需求completes完成在Future完成之后示例Example官方文档在 SourceOperators.scala 中给出了完整可运行的 Scala 示例以下即为#sourceFromFuture代码片段import akka.stream.scaladsl._ import akka.{ Done, NotUsed } import scala.concurrent.Future val source: Source[Int, NotUsed] Source.future(Future.successful(10)) val sink: Sink[Int, Future[Done]] Sink.foreach((i: Int) println(i)) val done: Future[Done] source.runWith(sink) // 输出: 10解读这段代码的执行流程Future.successful(10)创建一个已经成功完成、值为10的FutureSource.future(...)将其包装成单元素SourceSink.foreach对每个到达的元素执行println其物化值为Future[Done]可用于等待流完成runWith将流连接并物化控制台输出10最终done会在流完成后完成。需要implicit的ActorSystem示例代码中为implicit val system: ActorSystem ???来物化流。若希望在真实应用中等待结果可以Await.result(done, timeout)或继续在done上链式组合后续逻辑。对应的 Java 版本使用CompletionStage可以在 FromCompletionStage.java 中看到import akka.Done; import akka.NotUsed; import akka.stream.javadsl.*; import java.util.concurrent.CompletableFuture; import java.util.concurrent.CompletionStage; CompletionStageInteger stage CompletableFuture.completedFuture(10); SourceInteger, NotUsed source Source.completionStage(stage); SinkInteger, CompletionStageDone sink Sink.foreach(i - System.out.println(i.toString())); source.runWith(sink, system); // 输出: 10底层实现与原理源码级剖析Source.future的快路径与常规路径分界清晰理解它有助于你判断不同场景下的性能特征。工厂方法的快速路径优化在 Source.scala 中future工厂方法会先检查futureElement.valueFuture的瞬时状态快照def futureT: Source[T, NotUsed] futureElement.value match { case Some(Success(null)) empty // 已完成且值为 null → 空流 case Some(Success(value)) single(value) // 已完成且值非 null → 单元素流 case Some(Failure(cause)) failed(cause) // 已失败 → 直接失败流 case None fromGraph(new FutureSourceT) // 未完成 → 通用实现 }也就是说如果Future在调用Source.future时已经完成工厂方法会直接退化为更轻量的Source.empty、Source.single或Source.failed绕开通用的FutureSource图阶段GraphStage从而避免不必要的异步回调开销。这一点在 SourceSpec.scala 的测试中得到验证已成功的Future会被优化为singleSource已失败的Future会被优化为failedSource未完成的Future用Promise表示才会使用futureSource。三个测试均通过source.getAttributes.nameLifted断言了优化后的属性名并验证了运行结果成功值done、失败异常TE(boom)。未完成 Future 的通用实现FutureSource GraphStage当Future尚未完成时Source.future会构造一个内部InternalApi图阶段FutureSource完整实现位于 GraphStages.scala。其关键逻辑如下final class FutureSourceT extends GraphStage[SourceShape[T]] { val shape SourceShape(OutletT) val out shape.out override def createLogic(attr: Attributes) new GraphStageLogic(shape) with OutHandler { def onPull(): Unit { future.value match { case Some(completed) // optimization if the future is already completed onFutureCompleted(completed) case None val cb getAsyncCallback[Try[T]](onFutureCompleted).invoke _ future.onComplete(cb)(ExecutionContext.parasitic) } def onFutureCompleted(result: Try[T]): Unit { result match { case scala.util.Success(null) completeStage() case scala.util.Success(v) emit(out, v, () completeStage()) case scala.util.Failure(t) failStage(t) } } setHandler(out, eagerTerminateOutput) // After first pull we wont produce anything more } setHandler(out, this) } }其运作机制体现了 Akka Streams 图阶段GraphStage设计的几个要点拉取触发onPull()在首次收到下游需求时被调用。此时先做一次future.value快照检查——若Future已在此期间完成则直接走onFutureCompleted同步完成无需注册回调否则注册回调。线程安全回调Future.onComplete的回调发生在线程池线程上而 GraphStage 逻辑必须运行在流引擎的专用线程上因此这里用getAsyncCallback将回调结果安全地投递回流的执行上下文规避了任何竞态与线程安全问题。惰性注册回调只在第一次onPull时才注册因此如果下游从未请求元素例如下游提前取消则不会为Future注册回调体现了按需demand-driven的资源使用策略。一次性发射发射元素后通过emit(out, v, () completeStage())在发射完成时立即结束流在第一次 pull 之后handler 被替换为eagerTerminateOutput保证不会再有第二次发射。失败传播Failure(t)分支调用failStage(t)将异常作为流失败传播给下游。这与文档若Future失败则流以该异常失败的描述一一对应。与其他相关算子的对比算子输入输出元素物化值说明Source.futureFuture[T]至多 1 个TNotUsed本文主角Scala 原生Source.completionStageCompletionStage[T]至多 1 个TNotUsedJava 互操作版本内部委托给future见 Source.scalaSource.futureSourceFuture[Source[T, M]]多个T来自内部 SourceFuture[M]等Future完成后展开为内层Source的全部元素见 Source.scalaSource.lazyFutureSource.lazilyAsync的替代() Future[T]工厂至多 1 个TFuture[NotUsed]工厂延迟到下游产生需求时才调用见 Source.scala 的废弃注释选用建议已经持有或即将持有一个Future计算结果且只需要把它作为流中唯一元素继续加工时用Source.future在 Java 代码中使用Source.completionStage当Future本身展开后是一个Source例如异步获取一个流式查询结果时用Source.futureSource当希望延迟创建Future即下游没有需求就完全不发起异步计算时用Source.lazyFuture或Source.lazySource。边界情况与注意事项null值Future成功完成但值为null时流不发射任何元素直接完成等价于Source.empty。失败传播Future失败会导致流失败异常沿流向下传播请确保流中后续的算子/接收方对失败有兜底处理如Sink.onComplete、recover等。取消行为若下游在Future完成前取消回调不会被注册Future的完成结果将无人消费——若该Future承载着昂贵资源如数据库连接需在业务侧自行处理取消语义。物化值NotUsed意味着该算子本身不提供等待完成的句柄若要等整个流结束请依赖runWith(sink)返回的 Sink 物化值如示例中的Future[Done]。已完成的FutureSource.future(Future.successful(v))会被直接优化为Source.single(v)性能上无需担忧同理Future.failed(e)会被优化为Source.failed(e)。总结Source.future是 Akka Streams 中异步计算 → 流转换的基础构件它以背压安全的方式把 ScalaFuture的结果变成流中的唯一元素将失败透明地转化为流失败并对已完成的Future提供了零开销的快路径优化。结合 官方文档、工厂实现、FutureSource GraphStage 实现 与 单元测试你可以放心地将它用于 RPC 响应、缓存读取、数据库查询等典型异步场景并与其他Source算子自由组合构建完整的流式处理管线。若使用 Java请使用其等价物Source.completionStage见 completionStage.md。赞分享后端并发编程异步编程【免费下载链接】akka-coreA platform to build and run apps that are elastic, agile, and resilient. SDK, libraries, and hosted environments.项目地址https://gitcode.com/gh_mirrors/ak/akka-core点击查看免费下载相关推荐Akka Streams 的 Source.futureSource 算子将异步 Future[Source] 转换为流式数据源Akka Streams 的 Source.futureSource 算子将异步 Future Source 转换为流式数据源 本篇文章深入剖析 Akka S后端并发编程异步编程Akka Streams Source.lazyFuture 操作符完全指南延迟创建单元素 Future 的惰性数据源Akka Streams Source.lazyFuture 操作符完全指南延迟创建单元素 Future 的惰性数据源 本文围绕 Akka 项目中 Sourc后端并发编程异步编程Akka Streams Sink.seq 算子详解把流中的元素收集为集合Akka Streams Sink.seq 算子详解把流中的元素收集为集合 Sink.seq 是 Akka Streams 中一个常用且易用的下游算子Sin后端并发编程异步编程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考