Improve Task documentation. #85861
Improve Task documentation. #85861
Conversation
Clarifies that Task instances do not inherit cancellation from an enclosing Task within which they are created. Clarifies that the term "child task" does not refer to such tasks. Clarifies some language which had previously made it seem like non-detached Tasks would inherit cancellation (they do not).
| /// Child tasks inherit the parent task's priority and task-local storage, | ||
| /// and canceling a parent task automatically cancels all of its child tasks. | ||
| /// You need to handle these considerations manually with a detached task. | ||
| /// In most cases, an "attached" unstructured task (created via `Task.init`) |
There was a problem hiding this comment.
lazy question since i did not yet search myself, but is this "attached" terminology used anywhere else? i've personally never seen it AFAIK and it seems a bit odd. to what is the Task 'attached'?
There was a problem hiding this comment.
I haven't seen it either. I have put it in quotes here ("attached") to connote the fact that it isn't an accepted term but is being used in a casual manner for rhetorical purposes. I do think, however, that the existence of Task.detached implies that an "attached" alternative must exist. I am also hoping here that by directly stating that Task.init is the alternative, it should help clarify for the reader that there isn't, say, a Task.attached someplace they've yet to stumble upon.
There was a problem hiding this comment.
I would be happy to change "attached" to non-detached if that would be preferable.
2 participants
Explanation
Clarifies that Task instances do not inherit cancellation from an enclosing Task within which they are created. Clarifies that the term "child task" does not refer to such tasks. Clarifies some language which had previously made it seem like non-detached Tasks would inherit cancellation (they do not).
Scope
The changes are limited exclusively to documentation. There is no impact on ABI.
Issues
N/A
Original PRs
N/A
Risk
Risk is minimal to zero, as these changes affect only the documentation.
Testing
N/A
Reviewers
Pending...