TaskCompletionSource : When to use SetResult() versus TrySetResult(), etc

I'm trying to wrap my head around the TPL, the new async / await features in C# 5, and the mysteries of TaskCompletionSource.

One thing that isn't clear to me is when to use SetResult, SetException, and SetCancel versus TrySetResult, TrySetException and TrySetCancel.

This is what MSDN has to say:

> This operation will return false if the Task is already in > one of the three final states: RanToCompletion, Faulted, or Canceled. > > This method also returns false if the underlying Task has > already been disposed.

Ok, I get that, but it doesn't really offer any guidance on when or why to use one over the other.

So, what's the deal?

I suspect the point is that if there's only one thing which will be setting the result, just call SetResult etc. If you end up calling SetResult twice, that indicates a bug. (Likewise if the TaskCompletionSource has been disposed.)

If you've got several threads which could all be trying to set the result at the same time (e.g. it's there to indicate the first result out of several parallel web service calls) then use TrySetResult, as it's entirely reasonable for multiple threads to "try" to set the result, unaware of whether another thread has already set it.

I've not seen any official guidance on it, but that would make sense.

In addition to Jon's answed, MS docs portal says regarding TrySetResult:

This operation will return false if the Task<TResult> is already in one of the three final states:

• RanToCompletion
• Faulted
• Canceled

link: https://docs.microsoft.com/en-us/dotnet/api/system.threading.tasks.taskcompletionsource-1.trysetresult?view=net-5.0