Skip to content

Update TaskContinuationOptions.xml #8998

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Caleb-D wants to merge 1 commit into from
Closed

Update TaskContinuationOptions.xml #8998

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion xml/System.Threading.Tasks/TaskContinuationOptions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -394,7 +394,10 @@
</ReturnValue>
<MemberValue>262144</MemberValue>
<Docs>
<summary>Specifies that the continuation task should not be scheduled if its antecedent was canceled. An antecedent is canceled if its <see cref="P:System.Threading.Tasks.Task.Status" /> property upon completion is <see cref="F:System.Threading.Tasks.TaskStatus.Canceled" />. This option is not valid for multi-task continuations.</summary>
<summary>Specifies that the continuation task should not be scheduled if its antecedent was canceled. An antecedent is canceled if its <see cref="P:System.Threading.Tasks.Task.Status" /> property upon completion is <see cref="F:System.Threading.Tasks.TaskStatus.Canceled" />. This option is not valid for multi-task continuations.

Note: if you intend that a chain of continuation tasks should stop when one of the tasks throws an exception, use the flag <see cref="OnlyOnRanToCompletion"/> on all the continuation tasks instead of <see cref="NotOnFaulted"/>.
Copy link
Member

@stephentoub stephentoub May 5, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not really sure what benefit this is adding. It's also not entirely accurate; a task might end as canceled without there having ever been an exception involved.

Copy link
Author

@Caleb-D Caleb-D May 5, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess the documentation is not clear enough. This is just the use case I ran into. I had to create myself a test project and reverse engineer how these TaskContinuationOptions flags actually worked.

Maybe this isn't the best way to address this problem, but at least it would be nice to know that myContinuedTask.Status->Canceled when previousTask.Status==Faulted and myContinuedTask.ContinuationOptions=NotOnFaulted, and that myContinuedTask2 will still be scheduled.

Copy link
Author

@Caleb-D Caleb-D May 5, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, "multi-task continuations" seems vague and ambiguous. Are we talking about a chain of more than one continuation? Or a fan-out of continuations on one task? And does "not valid" mean you get a runtime exception, compile exception, undefined behavior? etc.

Copy link
Member

@stephentoub stephentoub May 5, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, "multi-task continuations" seems vague and ambiguous.

It's referring to the APIs that let you create continuations from multiple tasks, e.g. TaskFactory.ContinueWhenAll.

Copy link
Author

@Caleb-D Caleb-D May 5, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, thanks for clarifying.

Where do you suggest we go from here as far as documentation? Maybe I'm not the best one to make the changes since I don't have detailed knowledge of all the details.

Copy link
Member

@stephentoub stephentoub May 6, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm still not totally clear on what additional information you'd hope to see in the docs.

This particular enum value being edited is "NotOnCanceled" and it states "Specifies that the continuation task should not be scheduled if its antecedent was canceled." Is your concern that it doesn't spell out what state this continuation task will be in if the antecedent completes as Canceled? i.e. you'd want it to also say "If the antecedent ends in a canceled state, this continuation task will transition to a canceled state."?

Copy link
Author

@Caleb-D Caleb-D May 6, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think "If the antecedent ends in a canceled state, this continuation task will transition to a canceled state." would be a slight improvement. At least that helps me realize that not being scheduled doesn't mean "it gets discarded (and therefore any continuation tasks dependent on this continuation task get discarded)," which is what I initially thought.

You could follow that sentence with "Note that any continuation tasks dependent on this continuation task will still be scheduled, dependent on their TaskContinuationOptions."

</summary>
</Docs>
</Member>
<Member MemberName="NotOnFaulted">
Expand Down