33

In Async/Await FAQ, Stephen Toub says:

An awaitable is any type that exposes a GetAwaiter method which returns a valid awaiter.
...
An awaiter is any type returned from an awaitable’s GetAwaiter method and that conforms to a particular pattern.

So in order to be an awaiter, a type should:

  • Implement the INotifyCompletion interface.
  • Provide a boolean property called IsCompleted.
  • Provide a parameterless GetResult method that returns void or TResult.

(I'm ignoring ICriticalNotifyCompletion for now.)

I know the page I mentioned has a sample that shows how the compiler translates await operations but I'm stil having a hard time understanding.

When I await an awaitable,

  • When is IsCompleted checked? Where should I set it?
  • When is OnCompleted called?
  • Which thread calls OnCompleted?
  • I saw examples of both directly invoking the continuation parameter of OnCompleted and using Task.Run(continuation) in different examples, which should I go for and why?
Şafak Gür
  • 7,045
  • 5
  • 59
  • 96

2 Answers2

18

Why would you want a custom awaiter?

You can see the compiler's interpretation of await here. Essentially:

var temp = e.GetAwaiter();
if (!temp.IsCompleted)
{
  SAVE_STATE()
  temp.OnCompleted(&cont);
  return;

cont:
  RESTORE_STATE()
}
var i = temp.GetResult();

Edit from comments: OnCompleted should schedule its argument as a continuation of the asynchronous operation.

Stephen Cleary
  • 437,863
  • 77
  • 675
  • 810
  • 1
    No particular reason, I just want to know how it works. Though I still don't get the compiler's interpretation of await (sorry) does it call OnCompleted on parallel or should I provide an asynchronous implementation? (When will you do some awaitable socket posts by the way?) – Şafak Gür Sep 30 '12 at 13:10
  • 1
    `OnCompleted` is used to schedule the rest of the method as a continuation. So your implementation would just add it as a continuation to your asynchronous operation. And I'm working on the awaitable sockets... :) – Stephen Cleary Sep 30 '12 at 13:15
  • 1
    Well, the awaiter has to run the continuation *somewhere*. If you don't care about synchronization context, using `Task.Run()` might make sense. Ignoring the context would be unusual, but if it was a common situation, you wouldn't be creating a custom awaiter in the first place. – svick Sep 30 '12 at 13:15
  • @svick: OK, I can see the reasoning in that. – Stephen Cleary Sep 30 '12 at 13:19
5

In the vast majority of cases, you as a developer need not worry about this. Use the async and await keywords and the compiler and runtime handle all this for you.

To answer your questions:

When does the code checks IsCompleted? Where should I set it?

The task should set IsCompleted when the task has finished doing what it was doing. For example, if the task was loading data from a file, IsCompleted should return true when the data is loaded and the caller can access it.

When does it calls OnCompleted?

OnCompleted usually contains a delegate supplied by the caller to execute when the task has completed.

Does it call OnCompleted in parallel or should the code inside OnCompleted be asynchronous?

The code in OnCompleted should be thread neutral (not care which thread it is called from). This may be problematic for updating COM objects in Single Threaded Apartments (like any UI classes in Metro/Windows8/Windows Store apps). It does not have to be asynchronous but may contain asynchronous code.

I saw examples of both directly invoking the continuation parameter of OnCompleted and using Task.Run(continuation) in different examples, which should I go for and when?

Use async/await when you can. Otherwise, use Task.Run() or Task.Wait() because they follow the sequential programming model most people are used to. Using continuations may still be required, particularly in Metro apps where you have apartment issues.

akton
  • 14,148
  • 3
  • 43
  • 47
  • `Set IsCompleted when the task has finished doing what it was doing.` So when to start doing what it should be doing? In the constructor? In `OnCompleted`? – Şafak Gür Sep 30 '12 at 13:13
  • The awaiter should wait until IsCompleted is true and OnCompleted has been called. The task should do what it needs to do by whatever means is appropriate, usually on a different thread and/or using a ThreadPool. – akton Sep 30 '12 at 13:18
  • @ŞafakGür That depends on what your awaiter is supposed to do. But a constructor sounds like a reasonable choice. – svick Sep 30 '12 at 13:18