alamb commented on code in PR #15030:
URL: https://github.com/apache/datafusion/pull/15030#discussion_r1982248397
##########
datafusion/physical-plan/src/execution_plan.rs:
##########
@@ -260,13 +260,30 @@ pub trait ExecutionPlan: Debug + DisplayAs + Send + Sync {
/// used.
/// Thus, [`spawn`] is disallowed, and instead use [`SpawnedTask`].
///
+ /// To enable timely cancellation, the [`Stream`] that is returned must not
+ /// pin the CPU and must yield back to the tokio runtime regularly. This
can
+ /// be achieved by manually returning [`Poll::Pending`] in regular
intervals,
+ /// or the use of [`tokio::task::yield_now()`]. Cooperative scheduling may
also
Review Comment:
I am not sure how one would apply the `coop` suggestion here and I read the
linked PR and it didn't really explain much from a "how would I use this"
perspective -- so I would personally suggest removing this sentence.
##########
datafusion/physical-plan/src/execution_plan.rs:
##########
@@ -260,13 +260,30 @@ pub trait ExecutionPlan: Debug + DisplayAs + Send + Sync {
/// used.
/// Thus, [`spawn`] is disallowed, and instead use [`SpawnedTask`].
///
+ /// To enable timely cancellation, the [`Stream`] that is returned must not
+ /// pin the CPU and must yield back to the tokio runtime regularly. This
can
+ /// be achieved by manually returning [`Poll::Pending`] in regular
intervals,
+ /// or the use of [`tokio::task::yield_now()`]. Cooperative scheduling may
also
+ /// be a way to achieve this goal, as [tokio support for it
improves][coop].
+ /// Determination for "regularly" may be made using a timer (being careful
with
+ /// the overhead-heavy syscall needed to take the time) or by counting
rows or
+ /// batches.
+ ///
+ /// The goal is for `datafusion`-provided operator implementation to
+ /// strive for [the guideline of not spending a long time without reaching
+ /// an `await`/yield point][async-guideline]. Progress towards this goal
+ /// is tracked partially by the cancellation benchmark.
Review Comment:
I recommend making this the sentence higher up as the rationale is important
```
pin the CPU and must yield back to the tokio runtime regularly. ... <move
this paragraph up there>
```
I think we could potentially make the wording more concise, something like
```suggestion
/// `ExecutionPlan` implementations should follow
/// [the guideline of not spending a long time without reaching
/// an `await`/yield point][async-guideline].
```
In terms of the cancellation benchmark, I would suggest a sentence with a
link to the actual benchmark --
https://github.com/apache/datafusion/blob/main/benchmarks/README.md#benchmarks
Actually, now that I went to look it seems like we should docment the
cancellation benchmark there too 🤔
--
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.
To unsubscribe, e-mail: github-unsubscr...@datafusion.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscr...@datafusion.apache.org
For additional commands, e-mail: github-h...@datafusion.apache.org
