klion26 commented on a change in pull request #9150: [FLINK-13227][docs-zh]
Translate "asyncio" page into Chinese
URL: https://github.com/apache/flink/pull/9150#discussion_r304705962
##########
File path: docs/dev/stream/operators/asyncio.zh.md
##########
@@ -140,130 +124,114 @@ DataStream<Tuple2<String, String>> resultStream =
<div data-lang="scala" markdown="1">
{% highlight scala %}
/**
- * An implementation of the 'AsyncFunction' that sends requests and sets the
callback.
+ * 实现 'AsyncFunction' 用于发送请求和设置回调。
*/
class AsyncDatabaseRequest extends AsyncFunction[String, (String, String)] {
- /** The database specific client that can issue concurrent requests with
callbacks */
+ /** 使用回调函数来并发发送请求的数据库客户端 */
lazy val client: DatabaseClient = new DatabaseClient(host, post,
credentials)
- /** The context used for the future callbacks */
+ /** 用于 future 回调的上下文环境 */
implicit lazy val executor: ExecutionContext =
ExecutionContext.fromExecutor(Executors.directExecutor())
override def asyncInvoke(str: String, resultFuture: ResultFuture[(String,
String)]): Unit = {
- // issue the asynchronous request, receive a future for the result
+ // 发送异步请求，接收 future 结果
val resultFutureRequested: Future[String] = client.query(str)
- // set the callback to be executed once the request by the client is
complete
- // the callback simply forwards the result to the result future
+ // 设置客户端完成请求后要执行的回调函数
+ // 回调函数只是简单地把结果发给 future
resultFutureRequested.onSuccess {
case result: String => resultFuture.complete(Iterable((str,
result)))
}
}
}
-// create the original stream
+// 创建初始 DataStream
val stream: DataStream[String] = ...
-// apply the async I/O transformation
+// 应用异步 I/O 转换操作
val resultStream: DataStream[(String, String)] =
AsyncDataStream.unorderedWait(stream, new AsyncDatabaseRequest(), 1000,
TimeUnit.MILLISECONDS, 100)
{% endhighlight %}
</div>
</div>
-**Important note**: The `ResultFuture` is completed with the first call of
`ResultFuture.complete`.
-All subsequent `complete` calls will be ignored.
+**重要提示**： 第一次调用 `ResultFuture.complete` 后 `ResultFuture` 就完成了。
+后续的 `complete` 调用都将被忽略。
-The following two parameters control the asynchronous operations:
+下面两个参数控制异步操作：
- - **Timeout**: The timeout defines how long an asynchronous request may take
before it is considered failed. This parameter
- guards against dead/failed requests.
+ - **Timeout**： 超时参数定义了异步请求发出多久后未得到响应即被认定为失败。 它可以防止一直等待得不到响应的请求。
- - **Capacity**: This parameter defines how many asynchronous requests may be
in progress at the same time.
- Even though the async I/O approach leads typically to much better
throughput, the operator can still be the bottleneck in
- the streaming application. Limiting the number of concurrent requests
ensures that the operator will not
- accumulate an ever-growing backlog of pending requests, but that it will
trigger backpressure once the capacity
- is exhausted.
+ - **Capacity**： 容量参数定义了可以同时进行的异步请求数。
+ 即使异步 I/O 通常带来更高的吞吐量， 执行异步 I/O 操作的算子仍然可能成为流处理的瓶颈。
限制并发请求的数量可以确保算子不会持续累积待处理的请求进而造成积压，而是在容量耗尽时触发反压。
-### Timeout Handling
+### 超时处理
-When an async I/O request times out, by default an exception is thrown and job
is restarted.
-If you want to handle timeouts, you can override the `AsyncFunction#timeout`
method.
+当异步 I/O 请求超时的时候，默认会抛出异常并重启作业。
+如果你想处理超时，可以覆写 `AsyncFunction#timeout` 方法。
+### 结果的顺序
-### Order of Results
+`AsyncFunction` 发出的并发请求经常以不确定的顺序完成，这取决于请求得到响应的顺序。
+Flink 提供两种模式控制结果记录以何种顺序发出。
-The concurrent requests issued by the `AsyncFunction` frequently complete in
some undefined order, based on which request finished first.
-To control in which order the resulting records are emitted, Flink offers two
modes:
+ - **无序模式**： 异步请求一结束就立刻发出结果记录。
+ 流中记录的顺序在经过异步 I/O 算子之后发生了改变。
+ 当使用 *处理时间* 作为基本时间特征时，这个模式具有最低的延迟和最少的开销。
+ 此模式使用 `AsyncDataStream.unorderedWait(...)` 方法。
- - **Unordered**: Result records are emitted as soon as the asynchronous
request finishes.
- The order of the records in the stream is different after the async I/O
operator than before.
- This mode has the lowest latency and lowest overhead, when used with
*processing time* as the basic time characteristic.
- Use `AsyncDataStream.unorderedWait(...)` for this mode.
+ - **有序模式**:
这种模式保持了流的顺序。发出结果记录的顺序与触发异步请求的顺序（记录输入算子的顺序）相同。为了实现这一点，算子将缓冲一个结果记录直到这条记录前面的所有记录都发出（或超时）。由于记录或者结果要在
checkpoint 的状态中保存更长的时间，所以与无序模式相比，有序模式通常会带来一些额外的延迟和 checkpoint 开销。此模式使用
`AsyncDataStream.orderedWait(...)` 方法。
Review comment:
```suggestion
- **有序模式**:
这种模式保持了流的顺序。发出结果记录的顺序与触发异步请求的顺序（记录输入算子的顺序）相同。为了实现这一点，算子将缓冲一个结果记录直到这条记录前面的所有记录都发出（或超时）。由于记录或者结果要在
checkpoint 的状态中保存更长的时间，所以与无序模式相比，有序模式通常会带来一些额外的延迟和 checkpoint 开销。此模式使用
`AsyncDataStream.orderedWait(...)` 方法。
```
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
With regards,
Apache Git Services
