docs: clarify how async updates can overtake each other (#3581) · googleapis/java-spanner@1be250f (original) (raw)

`@@ -121,11 +121,11 @@ default ApiFuture bufferAsync(Iterable mutations) {

`

121

121

`/**

`

122

122

` * Same as {@link #executeUpdate(Statement,UpdateOption...)}, but is guaranteed to be

`

123

123

` * non-blocking. If multiple asynchronous update statements are submitted to the same read/write

`

124

``

`-

• transaction, the statements are guaranteed to be submitted to Cloud Spanner in the order that

`

125

``

`-

• they were submitted in the client. This does however not guarantee that an asynchronous update

`

126

``

`-

• statement will see the results of all previously submitted statements, as the execution of the

`

127

``

`-

• statements can be parallel. If you rely on the results of a previous statement, you should

`

128

``

`-

• block until the result of that statement is known and has been returned to the client.

`

``

124

`+

• transaction, the statements are guaranteed to be sent to Cloud Spanner in the order that they

`

``

125

`+

• were submitted in the client. This does however not guarantee that Spanner will receive the

`

``

126

`+

• requests in the same order as they were sent, as requests that are sent partly in parallel can

`

``

127

`+

• overtake each other. It is therefore recommended to block until an update statement has

`

``

128

`+

• returned a result before sending the next update statement.

`

129

129

` */

`

130

130

`ApiFuture executeUpdateAsync(Statement statement, UpdateOption... options);

`

131

131

``

`@@ -181,11 +181,11 @@ default ResultSet analyzeUpdateStatement(

`

181

181

`/**

`

182

182

` * Same as {@link #batchUpdate(Iterable, UpdateOption...)}, but is guaranteed to be non-blocking.

`

183

183

` * If multiple asynchronous update statements are submitted to the same read/write transaction,

`

184

``

`-

• the statements are guaranteed to be submitted to Cloud Spanner in the order that they were

`

185

``

`-

• submitted in the client. This does however not guarantee that an asynchronous update statement

`

186

``

`-

• will see the results of all previously submitted statements, as the execution of the statements

`

187

``

`-

• can be parallel. If you rely on the results of a previous statement, you should block until the

`

188

``

`-

• result of that statement is known and has been returned to the client.

`

``

184

`+

• the statements are guaranteed to be sent to Cloud Spanner in the order that they were submitted

`

``

185

`+

• in the client. This does however not guarantee that Spanner will receive the requests in the

`

``

186

`+

• same order as they were sent, as requests that are sent partly in parallel can overtake each

`

``

187

`+

• other. It is therefore recommended to block until an update statement has returned a result

`

``

188

`+

• before sending the next update statement.

`

189

189

` */

`

190

190

`ApiFuture<long[]> batchUpdateAsync(Iterable statements, UpdateOption... options);

`

191

191

`}

`